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
77 lines
4.4 KiB
Markdown
77 lines
4.4 KiB
Markdown
# Epic 1: Core Kernel & Infrastructure
|
|
|
|
## Overview
|
|
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 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 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)
|
|
- **Goal:** Implement comprehensive health checks and Prometheus metrics for monitoring platform health and performance.
|
|
- **Deliverables:** Health check system, Prometheus metrics, health endpoints, metrics endpoint
|
|
|
|
### 1.4 Error Handling and Error Bus
|
|
- [Story: 1.4 - Error Handling](./1.4-error-handling.md)
|
|
- **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/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 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 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/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 for all services
|
|
- `GET /ready` checks service health
|
|
- `GET /metrics` exposes Prometheus metrics
|
|
- Panic recovery logs errors via error bus
|
|
- 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
|
|
|
|
- [Implementation Summary and Verification Instructions](./SUMMARY.md) - Complete guide on how to verify all Epic 1 functionality, including database testing and Docker Compose setup
|