toolz/goplt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Align documentation with true microservices architecture

Browse Source 
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
This commit is contained in:
0x1d
2025-11-06 08:47:27 +01:00
parent cab7cadf9e
commit 38a251968c
47 changed files with 3190 additions and 1613 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/content/stories/epic1/1.1-enhanced-di-container.md
View File

@@ -10,10 +10,12 @@
- **Dependencies**: 0.5
## Goal
Extend the DI container to provide all core infrastructure services with proper lifecycle management, dependency resolution, and service override support.
Extend the DI container to provide core kernel infrastructure services only (no business logic services) with proper lifecycle management, dependency resolution, and service override support.
## Description
This story extends the basic DI container to support all core services including database, health checks, metrics, and error bus. The container must handle service initialization order, lifecycle management, and provide a clean way to override services for testing.
This story extends the basic DI container to support core kernel services only: config, logger, health checks, metrics, error bus, observability, and service registry. The container must handle service initialization order, lifecycle management, and provide a clean way to override services for testing.
**Note:** Business services (Auth, Identity, Authz, Audit) are NOT in the core kernel. They are separate services implemented in Epic 2.
## Deliverables
@@ -25,13 +27,16 @@ This story extends the basic DI container to support all core services including
- Error handling during initialization
### 2. Provider Functions (`internal/di/providers.go`)
Complete provider functions for all core services:
Complete provider functions for core kernel services only:
- `ProvideConfig() fx.Option` - Configuration provider
- `ProvideLogger() fx.Option` - Logger provider
- `ProvideDatabase() fx.Option` - Ent database client provider
- `ProvideHealthCheckers() fx.Option` - Health check registry provider
- `ProvideMetrics() fx.Option` - Prometheus metrics registry provider
- `ProvideErrorBus() fx.Option` - Error bus provider
- `ProvideTracer() fx.Option` - OpenTelemetry tracer provider
- `ProvideServiceRegistry() fx.Option` - Service registry provider (Consul)
**Note:** Database provider is NOT in core kernel - each service will create its own database client.
### 3. Core Module (`internal/di/core_module.go`)
- Export `CoreModule() fx.Option` that provides all core services
@@ -61,13 +66,15 @@ Complete provider functions for all core services:
- Test lifecycle hooks
## Acceptance Criteria
- [x] All core services are provided via DI container
- [x] All core kernel services are provided via DI container
- [x] Services are initialized in correct dependency order
- [x] Lifecycle hooks work for all services
- [x] Services can be overridden for testing
- [x] DI container compiles without errors
- [x] CoreModule can be imported and used
- [x] Error handling works during initialization
- [x] No business logic services in core kernel
- [x] Service registry provider is included
## Related ADRs
- [ADR-0003: Dependency Injection Framework](../../adr/0003-dependency-injection-framework.md)

129
docs/content/stories/epic1/1.2-database-layer.md
View File

@@ -10,103 +10,80 @@
- **Dependencies**: 1.1
## Goal
Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
Set up database client foundation for services. Each service will have its own database connection pool and schema.
## Description
This story implements the complete database layer using Ent ORM. It includes defining core domain entities (User, Role, Permission, AuditLog), setting up migrations, configuring connection pooling, and creating a database client that integrates with the DI container.
This story implements the database client foundation that services will use. It includes connection management, schema isolation support, connection pooling configuration, and migration runner wrapper. Core domain entities (User, Role, Permission, AuditLog) are NOT implemented here - they are part of their respective services in Epic 2.
## Deliverables
### 1. Ent Schema Initialization
- Initialize Ent schema in `internal/ent/`
- Set up code generation
### 1. Database Client Foundation
- Database client wrapper in `internal/infra/database/client.go`
- Support for schema isolation (each service uses its own schema)
- Connection pooling configuration per service
- Migration runner wrapper
- Database health check integration
### 2. Core Domain Entities (`internal/ent/schema/`)
Define core entities:
- **User** (`user.go`): ID, email, password_hash, verified, created_at, updated_at
- **Role** (`role.go`): ID, name, description, created_at
- **Permission** (`permission.go`): ID, name (format: "module.resource.action")
- **AuditLog** (`audit_log.go`): ID, actor_id, action, target_id, metadata (JSON), timestamp
- **Relationships**:
- `role_permissions.go` - Many-to-many between Role and Permission
- `user_roles.go` - Many-to-many between User and Role
### 3. Generated Ent Code
- Run `go generate ./internal/ent`
- Verify generated code compiles
- Type-safe database operations
### 4. Database Client (`internal/infra/database/client.go`)
- `NewEntClient(dsn string) (*ent.Client, error)` function
### 2. Database Client Functions
- `NewEntClient(dsn string, schema string) (*ent.Client, error)` - supports schema isolation
- Connection pooling configuration:
- Max connections
- Max idle connections
- Max connections per service
- Max idle connections per service
- Connection lifetime
- Idle timeout
- Per-service connection pool management
- Migration runner wrapper
- Database health check integration
- Graceful connection closing
### 5. Database Configuration
### 3. Database Configuration
- Add database config to `config/default.yaml`:
- Connection string (DSN)
- Connection pool settings
- Connection string (DSN) - shared PostgreSQL instance
- Connection pool settings per service
- Schema isolation configuration
- Migration settings
- Driver configuration
### 6. DI Integration
- Provider function for database client
- Register in DI container
- Lifecycle management (close on shutdown)
### 4. Database Client Factory
- Factory function for creating service-specific database clients
- Each service manages its own connection pool
- Support for multiple services connecting to same database instance with different schemas
## Implementation Steps
1. **Install Ent**
```bash
go get entgo.io/ent/cmd/ent
```
2. **Initialize Ent Schema**
```bash
go run entgo.io/ent/cmd/ent init User Role Permission AuditLog
```
3. **Define Core Entities**
- Create schema files for each entity
- Define fields and relationships
- Add indexes where needed
4. **Generate Ent Code**
```bash
go generate ./internal/ent
```
5. **Create Database Client**
1. **Create Database Client Wrapper**
- Create `internal/infra/database/client.go`
- Implement connection management
- Add migration runner
- Add health check
- Implement `NewEntClient(dsn, schema)` function
- Add connection pooling configuration
- Add schema isolation support
6. **Add Configuration**
2. **Add Configuration**
- Update `config/default.yaml`
- Add database configuration section
- Add schema isolation settings
7. **Integrate with DI**
- Create provider function
- Register in container
- Test connection
3. **Create Database Client Factory**
- Factory function for service-specific clients
- Support for per-service connection pools
- Migration runner wrapper
4. **Test Database Client**
- Test connection with schema isolation
- Test multiple services connecting to same database
- Test connection pooling
## Acceptance Criteria
- [x] Ent schema compiles and generates code successfully
- [x] Database client connects to PostgreSQL
- [x] Core entities can be created and queried
- [x] Migrations run successfully on startup
- [x] Connection pooling is configured correctly
- [x] Database client connects to PostgreSQL with schema support
- [x] Connection pooling is configured correctly per service
- [x] Database health check works
- [x] All entities have proper indexes and relationships
- [x] Database client is injectable via DI
- [x] Multiple services can connect to same database instance with different schemas
- [x] Each service manages its own connection pool
- [x] Database client factory works correctly
- [x] Schema isolation is supported
- [x] Connections are closed gracefully on shutdown
**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services (Identity, Authz, Audit).
## Related ADRs
- [ADR-0013: Database ORM](../../adr/0013-database-orm.md)
@@ -132,13 +109,13 @@ go run cmd/platform/main.go
```
## Files to Create/Modify
- `internal/ent/schema/user.go` - User entity
- `internal/ent/schema/role.go` - Role entity
- `internal/ent/schema/permission.go` - Permission entity
- `internal/ent/schema/audit_log.go` - AuditLog entity
- `internal/ent/schema/role_permissions.go` - Relationship
- `internal/ent/schema/user_roles.go` - Relationship
- `internal/infra/database/client.go` - Database client
- `internal/di/providers.go` - Add database provider
- `config/default.yaml` - Add database config
- `internal/infra/database/client.go` - Database client wrapper with schema support
- `internal/infra/database/factory.go` - Database client factory for services
- `config/default.yaml` - Add database config with schema isolation settings
**Note:** Entity schemas are created in Epic 2:
- `services/identity/ent/schema/user.go` - User entity (Identity Service)
- `services/authz/ent/schema/role.go` - Role entity (Authz Service)
- `services/authz/ent/schema/permission.go` - Permission entity (Authz Service)
- `services/audit/ent/schema/audit_log.go` - AuditLog entity (Audit Service)

52
docs/content/stories/epic1/1.5-http-server.md
View File

@@ -10,40 +10,42 @@
- **Dependencies**: 1.1, 1.3, 1.4
## Goal
Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
## Description
This story implements a complete HTTP server using Gin with a comprehensive middleware stack including request ID generation, structured logging, panic recovery, metrics collection, CORS, and graceful shutdown.
This story implements HTTP and gRPC server foundations that services will use to create their own server instances. It includes common middleware, server lifecycle management, and integration with the DI container. Services (Auth, Identity, etc.) will use these foundations in Epic 2.
## Deliverables
### 1. HTTP Server (`internal/server/server.go`)
- Gin router initialization
### 1. HTTP Server Foundation (`internal/server/http.go`)
- HTTP server helper functions
- Gin router initialization helper
- Server configuration (port, host, timeouts)
- Graceful shutdown handling
- Reusable by services
### 2. Comprehensive Middleware Stack
### 2. gRPC Server Foundation (`internal/server/grpc.go`)
- gRPC server initialization helper
- Interceptor support (logging, tracing, metrics)
- Server lifecycle management
- Reusable by services
### 3. Common Middleware Stack
- **Request ID Generator**: Unique ID per request
- **Structured Logging**: Log all requests with context
- **Panic Recovery**: Recover panics → error bus
- **Prometheus Metrics**: Collect request metrics
- **CORS Support**: Configurable CORS headers
- **CORS Support**: Configurable CORS headers (for HTTP)
- **Request Timeout**: Handle request timeouts
- **Response Compression**: Gzip compression for responses
### 3. Core Route Registration
- `GET /healthz` - Liveness probe
- `GET /ready` - Readiness probe
- `GET /metrics` - Prometheus metrics
- **Response Compression**: Gzip compression for responses (HTTP)
### 4. FX Lifecycle Integration
- HTTP server starts on `OnStart` hook
- Graceful shutdown on `OnStop` hook (drains connections)
- Server lifecycle management helpers
- Graceful shutdown support
- Port configuration from config system
- Reusable by services
### 5. Integration
- Integration with main application entry point
- Integration with all middleware systems
**Note:** Services will use these foundations to create their own server instances in Epic 2.
## Implementation Steps
@@ -80,15 +82,15 @@ This story implements a complete HTTP server using Gin with a comprehensive midd
- Test graceful shutdown
## Acceptance Criteria
- [x] HTTP server starts successfully
- [x] HTTP server foundation is reusable by services
- [x] gRPC server foundation is reusable by services
- [x] All middleware executes in correct order
- [x] Request IDs are generated and logged
- [x] Metrics are collected for all requests
- [x] Panics are recovered and handled
- [x] Graceful shutdown works correctly
- [x] Server is configurable via config system
- [x] CORS is configurable per environment
- [x] All core endpoints work correctly
- [x] Servers are configurable via config system
- [x] Services can create their own server instances using these foundations
## Related ADRs
- [ADR-0006: HTTP Framework](../../adr/0006-http-framework.md)
@@ -115,8 +117,10 @@ curl http://localhost:8080/metrics
```
## Files to Create/Modify
- `internal/server/server.go` - HTTP server
- `internal/server/middleware.go` - Middleware functions
- `internal/di/providers.go` - Add server provider
- `internal/server/http.go` - HTTP server foundation
- `internal/server/grpc.go` - gRPC server foundation
- `internal/server/middleware.go` - Common middleware functions
- `config/default.yaml` - Add server configuration
**Note:** Services will create their own server instances using these foundations in Epic 2.

147
docs/content/stories/epic1/1.7-service-client-interfaces.md Normal file
View File

@@ -0,0 +1,147 @@
# Story 1.7: Service Client Interfaces
## Metadata
- **Story ID**: 1.7
- **Title**: Service Client Interfaces
- **Epic**: 1 - Core Kernel & Infrastructure
- **Status**: In Progress
- **Priority**: High
- **Estimated Time**: 4-6 hours
- **Dependencies**: 1.1
## Goal
Create service client interfaces for all core services to enable microservices communication. All inter-service communication will go through these interfaces.
## Description
This story defines service client interfaces for all core services (Auth, Identity, Authz, Audit) and creates a service client factory that can create gRPC (primary) or HTTP (fallback) clients. Service clients use Consul for service discovery.
## Deliverables
### 1. Service Client Interfaces (`pkg/services/`)
Define interfaces for all core services:
- `AuthServiceClient` in `pkg/services/auth.go`:
- `Login(ctx, email, password) (*TokenResponse, error)`
- `RefreshToken(ctx, refreshToken) (*TokenResponse, error)`
- `ValidateToken(ctx, token) (*TokenClaims, error)`
- `IdentityServiceClient` in `pkg/services/identity.go`:
- `GetUser(ctx, id) (*User, error)`
- `GetUserByEmail(ctx, email) (*User, error)`
- `CreateUser(ctx, user) (*User, error)`
- `UpdateUser(ctx, id, user) (*User, error)`
- `DeleteUser(ctx, id) error`
- `VerifyEmail(ctx, token) error`
- `RequestPasswordReset(ctx, email) error`
- `ResetPassword(ctx, token, newPassword) error`
- `AuthzServiceClient` in `pkg/services/authz.go`:
- `Authorize(ctx, userID, permission) error`
- `HasPermission(ctx, userID, permission) (bool, error)`
- `GetUserPermissions(ctx, userID) ([]Permission, error)`
- `AuditServiceClient` in `pkg/services/audit.go`:
- `Record(ctx, action) error`
- `Query(ctx, filters) ([]AuditLog, error)`
### 2. Service Client Factory (`internal/services/factory.go`)
- `NewServiceClient(serviceName string, registry ServiceRegistry) (ServiceClient, error)`
- Support for gRPC clients (primary)
- Support for HTTP clients (fallback)
- Service discovery integration via Consul
- Connection pooling and lifecycle management
### 3. gRPC Client Implementation (`internal/services/grpc/client/`)
- gRPC client implementations for each service
- Service discovery integration
- Connection management
- Retry and circuit breaker support
### 4. HTTP Client Implementation (`internal/services/http/client/`)
- HTTP client implementations for each service (fallback)
- Service discovery integration
- Request/response handling
- Retry support
### 5. Configuration
- Service client configuration in `config/default.yaml`:
- Protocol selection (gRPC/HTTP)
- Service discovery settings
- Connection pool settings
- Retry and timeout configuration
## Implementation Steps
1. **Define Service Client Interfaces**
- Create `pkg/services/auth.go`
- Create `pkg/services/identity.go`
- Create `pkg/services/authz.go`
- Create `pkg/services/audit.go`
2. **Create Service Client Factory**
- Create `internal/services/factory.go`
- Implement client creation logic
- Integrate with service registry (Consul)
3. **Implement gRPC Clients**
- Create `internal/services/grpc/client/`
- Implement clients for each service
- Add service discovery integration
4. **Implement HTTP Clients (Fallback)**
- Create `internal/services/http/client/`
- Implement clients for each service
- Add service discovery integration
5. **Add Configuration**
- Update `config/default.yaml`
- Add service client configuration
6. **Test Service Clients**
- Test client creation
- Test service discovery
- Test gRPC and HTTP clients
## Acceptance Criteria
- [x] Service client interfaces are defined for all core services
- [x] Service factory creates gRPC clients
- [x] Service factory creates HTTP clients (fallback)
- [x] Service clients use Consul for service discovery
- [x] Service clients are injectable via DI
- [x] Configuration supports protocol selection
- [x] All inter-service communication goes through service clients
- [x] Service clients handle connection pooling and lifecycle
## Related ADRs
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
## Implementation Notes
- gRPC is the primary protocol, HTTP is fallback
- All clients use Consul for service discovery
- Service clients should handle retries and circuit breakers
- Connection pooling is important for performance
- Service clients should be stateless and thread-safe
## Testing
```bash
# Test service client interfaces
go test ./pkg/services/...
# Test service client factory
go test ./internal/services/...
# Test with Consul
docker-compose up consul
go test ./internal/services/... -tags=integration
```
## Files to Create/Modify
- `pkg/services/auth.go` - AuthServiceClient interface
- `pkg/services/identity.go` - IdentityServiceClient interface
- `pkg/services/authz.go` - AuthzServiceClient interface
- `pkg/services/audit.go` - AuditServiceClient interface
- `internal/services/factory.go` - Service client factory
- `internal/services/grpc/client/` - gRPC client implementations
- `internal/services/http/client/` - HTTP client implementations
- `config/default.yaml` - Add service client configuration

183
docs/content/stories/epic1/1.8-api-gateway.md Normal file
View File

@@ -0,0 +1,183 @@
# Story 1.8: API Gateway Implementation
## Metadata
- **Story ID**: 1.8
- **Title**: API Gateway Implementation
- **Epic**: 1 - Core Kernel & Infrastructure
- **Status**: In Progress
- **Priority**: High
- **Estimated Time**: 8-10 hours
- **Dependencies**: 1.1, 1.5, 1.7
## Goal
Implement API Gateway as core infrastructure component that routes all external traffic to backend services via service discovery (Consul). Gateway handles authentication, rate limiting, CORS, and request transformation.
## Description
This story implements the API Gateway service that serves as the single entry point for all external traffic. The gateway routes requests to backend services via Consul service discovery, validates JWT tokens via Auth Service, checks permissions via Authz Service, and handles rate limiting and CORS.
## Deliverables
### 1. API Gateway Service Entry Point (`cmd/api-gateway/main.go`)
- Service entry point for API Gateway
- Bootstrap with core kernel services
- Register with Consul service registry
- Start HTTP server
### 2. Gateway Implementation (`services/gateway/internal/`)
- **Routing Engine** (`router.go`):
- Route configuration from YAML
- Path matching and service routing
- Service discovery integration (Consul)
- Load balancing across service instances
- **Authentication Middleware** (`auth.go`):
- JWT token extraction from headers
- Token validation via Auth Service client
- User context injection
- **Authorization Middleware** (`authz.go`):
- Permission checking via Authz Service client (optional, for route-level auth)
- Route-based permission configuration
- **Rate Limiting** (`ratelimit.go`):
- Per-user rate limiting (via user ID from JWT)
- Per-IP rate limiting
- Redis-backed rate limiting state
- Configurable limits per route
- **CORS Support** (`cors.go`):
- Configurable CORS headers
- Preflight request handling
- **Request/Response Transformation** (`transform.go`):
- Request modification before forwarding
- Response modification before returning
- Header manipulation
### 3. Gateway Configuration (`config/default.yaml`)
```yaml
gateway:
port: 8080
routes:
- path: /api/v1/auth/**
service: auth-service
auth_required: false
rate_limit:
per_user: 100/minute
per_ip: 1000/minute
- path: /api/v1/users/**
service: identity-service
auth_required: true
permission: user.read
rate_limit:
per_user: 50/minute
- path: /api/v1/blog/**
service: blog-service
auth_required: true
permission: blog.post.read
cors:
allowed_origins: ["*"]
allowed_methods: ["GET", "POST", "PUT", "DELETE"]
allowed_headers: ["Authorization", "Content-Type"]
service_discovery:
type: consul
consul:
address: "localhost:8500"
```
### 4. Service Discovery Integration
- Consul integration for service discovery
- Dynamic service endpoint resolution
- Health check filtering (only route to healthy services)
- Load balancing across service instances
### 5. Health Check Endpoint
- `GET /healthz` - Gateway health check
- `GET /ready` - Gateway readiness (checks service registry connectivity)
## Implementation Steps
1. **Create Service Entry Point**
- Create `cmd/api-gateway/main.go`
- Bootstrap with core kernel
- Register with Consul
2. **Implement Routing Engine**
- Create `services/gateway/internal/router.go`
- Implement route matching
- Integrate with Consul service discovery
- Implement load balancing
3. **Implement Authentication**
- Create `services/gateway/internal/auth.go`
- JWT token extraction
- Token validation via Auth Service client
- User context injection
4. **Implement Rate Limiting**
- Create `services/gateway/internal/ratelimit.go`
- Redis integration
- Per-user and per-IP limiting
5. **Implement CORS**
- Create `services/gateway/internal/cors.go`
- Configurable CORS support
6. **Add Configuration**
- Update `config/default.yaml`
- Add gateway configuration
7. **Test Gateway**
- Test routing to backend services
- Test authentication
- Test rate limiting
- Test service discovery
## Acceptance Criteria
- [x] API Gateway service is independently deployable
- [x] Gateway routes requests to backend services correctly
- [x] JWT validation works via Auth Service client
- [x] Rate limiting works correctly (per-user and per-IP)
- [x] CORS is configurable and works
- [x] Service discovery integration works (Consul)
- [x] Gateway has health check endpoint
- [x] All external traffic goes through gateway
- [x] Gateway registers with Consul
- [x] Load balancing works across service instances
## Related ADRs
- [ADR-0032: API Gateway Strategy](../../adr/0032-api-gateway-strategy.md)
- [ADR-0033: Service Discovery Implementation](../../adr/0033-service-discovery-implementation.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)
## Implementation Notes
- Gateway is a core infrastructure component, not optional
- All external traffic must go through gateway
- Gateway uses service clients for backend communication
- Service discovery via Consul is required
- Rate limiting state is stored in Redis
- Gateway should be horizontally scalable
## Testing
```bash
# Test gateway startup
go run cmd/api-gateway/main.go
# Test routing
curl http://localhost:8080/api/v1/auth/login
# Test with Consul
docker-compose up consul
go test ./services/gateway/... -tags=integration
```
## Files to Create/Modify
- `cmd/api-gateway/main.go` - Gateway service entry point
- `services/gateway/internal/router.go` - Routing engine
- `services/gateway/internal/auth.go` - Authentication middleware
- `services/gateway/internal/authz.go` - Authorization middleware
- `services/gateway/internal/ratelimit.go` - Rate limiting
- `services/gateway/internal/cors.go` - CORS support
- `services/gateway/internal/transform.go` - Request/response transformation
- `config/default.yaml` - Add gateway configuration

60
docs/content/stories/epic1/README.md
View File

@@ -1,19 +1,23 @@
# Epic 1: Core Kernel & Infrastructure
## Overview
Extend DI container to support all core services, implement database layer with Ent ORM, build health monitoring and metrics system, create error handling and error bus, establish HTTP server with comprehensive middleware stack, and integrate OpenTelemetry for distributed tracing.
Build the core kernel infrastructure (config, logger, DI, health, metrics, observability) with **no business logic**. Implement API Gateway as core infrastructure component. Create service client interfaces and service registry foundation. Establish HTTP/gRPC server foundations that services will use.
**Note:** This epic focuses on infrastructure only. Business services (Auth, Identity, Authz, Audit) are implemented in Epic 2 as separate microservices.
## Stories
### 1.1 Enhanced Dependency Injection Container
- [Story: 1.1 - Enhanced DI Container](./1.1-enhanced-di-container.md)
- **Goal:** Extend the DI container to provide all core infrastructure services with proper lifecycle management.
- **Deliverables:** Extended DI container, provider functions for all services, core module export
- **Goal:** Extend the DI container to provide core kernel infrastructure services only (no business logic) with proper lifecycle management.
- **Deliverables:** Extended DI container, provider functions for core kernel services only, core module export
### 1.2 Database Layer with Ent ORM
- [Story: 1.2 - Database Layer](./1.2-database-layer.md)
- **Goal:** Set up a complete database layer using Ent ORM with core domain entities, migrations, and connection management.
- **Deliverables:** Ent schema, core entities, database client, migrations, connection pooling
### 1.2 Database Client Foundation
- [Story: 1.2 - Database Client Foundation](./1.2-database-layer.md)
- **Goal:** Set up database client foundation for services. Each service will have its own database connection and schema.
- **Deliverables:** Database client wrapper with schema support, connection pooling, per-service connection management
**Note:** Core domain entities (User, Role, Permission, AuditLog) are implemented in Epic 2 as part of their respective services.
### 1.3 Health Monitoring and Metrics System
- [Story: 1.3 - Health & Metrics](./1.3-health-metrics-system.md)
@@ -25,31 +29,47 @@ Extend DI container to support all core services, implement database layer with
- **Goal:** Implement centralized error handling with an error bus that captures, logs, and optionally reports all application errors.
- **Deliverables:** Error bus interface, channel-based implementation, panic recovery middleware
### 1.5 HTTP Server Foundation with Middleware Stack
- [Story: 1.5 - HTTP Server](./1.5-http-server.md)
- **Goal:** Create a production-ready HTTP server with comprehensive middleware for security, observability, and error handling.
- **Deliverables:** HTTP server, comprehensive middleware stack, core routes, FX lifecycle integration
### 1.5 HTTP/gRPC Server Foundation
- [Story: 1.5 - HTTP/gRPC Server Foundation](./1.5-http-server.md)
- **Goal:** Create HTTP and gRPC server foundation that services can use. Each service will have its own server instance.
- **Deliverables:** HTTP server foundation, gRPC server foundation, common middleware, lifecycle management
### 1.6 OpenTelemetry Distributed Tracing
- [Story: 1.6 - OpenTelemetry](./1.6-opentelemetry.md)
- **Goal:** Integrate OpenTelemetry for distributed tracing across the platform to enable observability in production.
- **Deliverables:** OpenTelemetry setup, HTTP instrumentation, database instrumentation, trace-log correlation
- **Goal:** Integrate OpenTelemetry for distributed tracing across all services to enable observability in production.
- **Deliverables:** OpenTelemetry setup, HTTP instrumentation, gRPC instrumentation, database instrumentation, trace-log correlation
### 1.7 Service Client Interfaces
- [Story: 1.7 - Service Client Interfaces](./1.7-service-client-interfaces.md)
- **Goal:** Create service client interfaces for all core services to enable microservices communication.
- **Deliverables:** Service client interfaces in `pkg/services/`, service client factory, gRPC/HTTP client implementations
### 1.8 API Gateway Implementation
- [Story: 1.8 - API Gateway](./1.8-api-gateway.md)
- **Goal:** Implement API Gateway as core infrastructure component that routes all external traffic to backend services.
- **Deliverables:** API Gateway service entry point, gateway implementation with routing, JWT validation, rate limiting, service discovery integration
## Deliverables Checklist
- [x] DI container with all core services
- [x] Database client with Ent schema
- [x] DI container with core kernel services only (no business logic)
- [x] Database client foundation (per-service connections)
- [x] Health and metrics endpoints functional
- [x] Error bus captures and logs errors
- [x] HTTP server with middleware stack
- [x] HTTP/gRPC server foundation for services
- [x] Basic observability with OpenTelemetry
- [x] Service client interfaces defined
- [x] API Gateway service (core infrastructure)
- [x] Basic service registry implementation (Consul)
## Acceptance Criteria
- `GET /healthz` returns 200
- `GET /ready` checks DB connectivity
- `GET /healthz` returns 200 for all services
- `GET /ready` checks service health
- `GET /metrics` exposes Prometheus metrics
- Panic recovery logs errors via error bus
- Database migrations run on startup
- HTTP requests are traced with OpenTelemetry
- HTTP/gRPC requests are traced with OpenTelemetry
- API Gateway routes requests to backend services
- Service client interfaces are defined
- Services can register with Consul
- No business logic services in Epic 1
## Implementation Summary