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
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
# Story 3.1: Module System Interface and Service Registry
|
|
|
|
## Metadata
|
|
- **Story ID**: 3.1
|
|
- **Title**: Module System Interface and Service Registry
|
|
- **Epic**: 3 - Module Framework (Feature Services)
|
|
- **Status**: Pending
|
|
- **Priority**: High
|
|
- **Estimated Time**: 5-6 hours
|
|
- **Dependencies**: 1.1, 1.7, 2.3
|
|
|
|
## Goal
|
|
Design module interface for feature services with service registration and dependency resolution. Modules are services that register with Consul and communicate via service clients.
|
|
|
|
## Description
|
|
This story creates the foundation for feature services (modules) by defining the module interface, manifest structure, and service registration. Feature services are independent services with their own entry points, gRPC servers, and database schemas. They register with Consul and use service clients for inter-service communication.
|
|
|
|
## Deliverables
|
|
|
|
### 1. Module Interface (`pkg/module/module.go`)
|
|
- `IModule` interface for feature services:
|
|
- `Name() string` - Service name
|
|
- `Version() string` - Service version
|
|
- `Dependencies() []string` - Service dependencies (other services)
|
|
- `Init() fx.Option` - FX options for service initialization
|
|
- `Migrations() []func(*ent.Client) error` - Database migrations (per-service schema)
|
|
- Optional lifecycle hooks: `OnStart(ctx context.Context) error`
|
|
- Optional lifecycle hooks: `OnStop(ctx context.Context) error`
|
|
|
|
**Note:** Modules are services - each module has its own `cmd/{service}/main.go` entry point.
|
|
|
|
### 2. Module Manifest (`pkg/module/manifest.go`)
|
|
- `Manifest` struct with:
|
|
- Name, Version, Dependencies (service names)
|
|
- Permissions list
|
|
- gRPC service definitions
|
|
- Database schema information
|
|
- `module.yaml` schema definition
|
|
- Manifest parsing and validation
|
|
|
|
### 3. Service Registration Integration
|
|
- Integration with Consul service registry (from Epic 1)
|
|
- Service registration helpers
|
|
- Service discovery integration
|
|
- Health check integration
|
|
|
|
### 4. Module Registry (`internal/registry/module_registry.go`)
|
|
- Thread-safe module map (for tracking feature services)
|
|
- `Register(m IModule)` function
|
|
- `All() []IModule` function
|
|
- `Get(name string) (IModule, error)` function
|
|
- Dependency validation (check service dependencies are available)
|
|
- Duplicate name detection
|
|
- Version compatibility checking
|
|
- Dependency cycle detection
|
|
|
|
**Note:** This is separate from the service registry (Consul) - this tracks feature services for dependency resolution.
|
|
|
|
## Implementation Steps
|
|
|
|
1. **Create Module Interface**
|
|
- Create `pkg/module/module.go`
|
|
- Define IModule interface
|
|
- Add lifecycle hooks
|
|
|
|
2. **Create Module Manifest**
|
|
- Create `pkg/module/manifest.go`
|
|
- Define Manifest struct
|
|
- Define module.yaml schema
|
|
|
|
3. **Create Module Registry**
|
|
- Create `internal/registry/registry.go`
|
|
- Implement thread-safe registry
|
|
- Add validation logic
|
|
|
|
4. **Test Registration**
|
|
- Test module registration
|
|
- Test dependency validation
|
|
- Test duplicate detection
|
|
|
|
## Acceptance Criteria
|
|
- [x] Feature services can register via module interface
|
|
- [x] Registry validates service dependencies
|
|
- [x] Registry prevents duplicate registrations
|
|
- [x] Module interface supports service architecture
|
|
- [x] Dependency cycles are detected
|
|
- [x] Version compatibility is checked
|
|
- [x] Service registration with Consul is integrated
|
|
- [x] Feature services can discover core services via service registry
|
|
|
|
## Related ADRs
|
|
- [ADR-0021: Module Loading Strategy](../../adr/0021-module-loading-strategy.md)
|
|
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
|
|
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
|
|
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
|
|
|
|
## Files to Create/Modify
|
|
- `pkg/module/module.go` - Module interface for feature services
|
|
- `pkg/module/manifest.go` - Module manifest
|
|
- `internal/registry/module_registry.go` - Module registry (for dependency tracking)
|
|
- Integration with `internal/registry/consul/` (service registry from Epic 1)
|
|
|