0x1d
38a251968c
Transform all documentation from modular monolith to true microservices
architecture where core services are independently deployable.
Key Changes:
- Core Kernel: Infrastructure only (no business logic)
- Core Services: Auth, Identity, Authz, Audit as separate microservices
- Each service has own entry point (cmd/{service}/)
- Each service has own gRPC server and database schema
- Services register with Consul for service discovery
- API Gateway: Moved from Epic 8 to Epic 1 as core infrastructure
- Single entry point for all external traffic
- Handles routing, JWT validation, rate limiting, CORS
- Service Discovery: Consul as primary mechanism (ADR-0033)
- Database Pattern: Per-service connections with schema isolation
Documentation Updates:
- Updated all 9 architecture documents
- Updated 4 ADRs and created 2 new ADRs (API Gateway, Service Discovery)
- Rewrote Epic 1: Core Kernel & Infrastructure (infrastructure only)
- Rewrote Epic 2: Core Services (Auth, Identity, Authz, Audit as services)
- Updated Epic 3-8 stories for service architecture
- Updated plan.md, playbook.md, requirements.md, index.md
- Updated all epic READMEs and story files
New ADRs:
- ADR-0032: API Gateway Strategy
- ADR-0033: Service Discovery Implementation (Consul)
New Stories:
- Epic 1.7: Service Client Interfaces
- Epic 1.8: API Gateway Implementation
Architecture Decision Records (ADRs)
This directory contains Architecture Decision Records (ADRs) for the Go Platform project.
What are ADRs?
ADRs document important architectural decisions made during the project. They help:
- Track why decisions were made
- Understand the context and constraints
- Review decisions when requirements change
- Onboard new team members
ADR Format
Each ADR follows this structure:
- Status: Proposed | Accepted | Rejected | Superseded
- Context: The situation that led to the decision
- Decision: What was decided
- Consequences: Positive and negative impacts
ADR Index
Epic 0: Project Setup & Foundation
- ADR-0001: Go Module Path - Module path:
git.dcentral.systems/toolz/goplt - ADR-0002: Go Version - Go 1.24.3
- ADR-0003: Dependency Injection Framework - uber-go/fx
- ADR-0004: Configuration Management - spf13/viper + cobra
- ADR-0005: Logging Framework - go.uber.org/zap
- ADR-0006: HTTP Framework - gin-gonic/gin
- ADR-0007: Project Directory Structure - Standard Go layout with internal/pkg separation
- ADR-0008: Error Handling Strategy - Wrapped errors with typed errors
- ADR-0009: Context Key Types - Typed context keys
- ADR-0010: CI/CD Platform - GitHub Actions
- ADR-0011: Code Generation Tools - go generate workflow
- ADR-0012: Logger Interface Design - Logger interface abstraction
Epic 1: Core Kernel & Infrastructure
- ADR-0013: Database ORM Selection - entgo.io/ent
- ADR-0014: Health Check Implementation - Custom health check registry
- ADR-0015: Error Bus Implementation - Channel-based error bus with pluggable sinks
- ADR-0016: OpenTelemetry Observability Strategy - OpenTelemetry for tracing, metrics, logs
Epic 2: Authentication & Authorization
- ADR-0017: JWT Token Strategy - Short-lived access tokens + long-lived refresh tokens
- ADR-0018: Password Hashing Algorithm - argon2id
- ADR-0019: Permission DSL Format - String-based format with code generation
- ADR-0020: Audit Logging Storage - PostgreSQL append-only table with JSONB metadata
Epic 3: Module Framework
- ADR-0021: Module Loading Strategy - Static registration (primary) + dynamic plugin loading (optional)
Epic 5: Infrastructure Adapters
- ADR-0022: Cache Implementation - Redis with in-memory fallback
- ADR-0023: Event Bus Implementation - In-process bus (default) + Kafka (production)
- ADR-0024: Background Job Scheduler - asynq (Redis-backed) + cron
- ADR-0025: Multi-tenancy Model - Shared database with tenant_id column (optional)
Epic 6: Observability & Production Readiness
- ADR-0026: Error Reporting Service - Sentry (optional, configurable)
- ADR-0027: Rate Limiting Strategy - Multi-level (per-user + per-IP) with Redis
Epic 7: Testing, Documentation & CI/CD
- ADR-0028: Testing Strategy - Multi-layered (unit, integration, contract, load)
Architecture & Scaling
- ADR-0029: Microservices Architecture - micromicroservices architecture from day one
- ADR-0030: Service Communication Strategy - Service client abstraction and communication patterns with API Gateway
- ADR-0031: Service Repository Structure - Monorepo with service directories
- ADR-0032: API Gateway Strategy - API Gateway as core infrastructure component
- ADR-0033: Service Discovery Implementation - Consul-based service discovery (primary), Kubernetes as alternative
Adding New ADRs
When making a new architectural decision:
- Create a new file:
XXXX-short-title.md(next sequential number) - Follow the ADR template
- Update this README with the new entry
- Set status to "Proposed" initially
- Update to "Accepted" after review/approval