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
Epic 3: Module Framework (Feature Services)
Overview
Design and implement the module framework for feature services. Modules are implemented as independent services with their own entry points (cmd/{service}/), gRPC servers, and database schemas. The framework provides module interfaces, service registration, permission code generation, and CLI tooling for service management.
Key Principle: Modules are services - each module is an independently deployable service that registers with Consul and communicates via service clients.
Stories
3.1 Module System Interface and Service Registry
- Story: 3.1 - Module System Interface
- Goal: Design module interface for feature services with service registration and dependency resolution.
- Deliverables: Module interface, module manifest, service registration integration
3.2 Permission Code Generation System
- Story: 3.2 - Permission Code Generation
- Goal: Create automated permission code generation from module manifests to ensure type-safe permission constants.
- Deliverables: Permission generation script, Go generate integration, Makefile integration
3.3 Service Loader and Initialization
- Story: 3.3 - Service Loader
- Goal: Implement service loading and initialization for feature services with dependency resolution.
- Deliverables: Service loader, service initialization, FX lifecycle integration, Consul registration
3.4 Service Management CLI Tool
- Story: 3.4 - Service CLI
- Goal: Provide CLI tooling for managing feature services, validating dependencies, and testing service loading.
- Deliverables: CLI tool, Makefile integration
3.5 Service Registry and Discovery
- Story: 3.5 - Service Registry
- Goal: Implement Consul-based service registry for service discovery (already implemented in Epic 1, verify integration).
- Deliverables: Service registry interface verification, Consul integration verification
Deliverables Checklist
- Module interface for feature services
- Service registration with Consul
- Permission code generation tool
- Service loader with dependency resolution
- Service initialization in service entry points
- CLI tool for service management
- Service registry integration verified
Acceptance Criteria
- Feature services can register via module interface
- Permission constants are generated from
module.yaml - Services load in correct dependency order
- Service migrations run on startup
- Services register with Consul automatically
platformctl services listshows all services- Integration test: load multiple services and verify Consul registration