docs: Align documentation with true microservices architecture

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
2025-11-06 08:47:27 +01:00
parent cab7cadf9e
commit 38a251968c
47 changed files with 3190 additions and 1613 deletions
--- a/docs/content/adr/0032-api-gateway-strategy.md
+++ b/docs/content/adr/0032-api-gateway-strategy.md
@@ -0,0 +1,166 @@
+# ADR-0032: API Gateway Strategy
+
+## Status
+Accepted
+
+## Context
+The platform follows a microservices architecture where each service is independently deployable. We need a central entry point that handles:
+- Request routing to backend services
+- Authentication and authorization at the edge
+- Rate limiting and throttling
+- CORS and request/response transformation
+- Service discovery integration
+
+Options considered:
+1. **Custom API Gateway** - Build our own gateway service
+2. **Kong** - Open-source API Gateway
+3. **Envoy** - High-performance proxy
+4. **Traefik** - Modern reverse proxy
+
+## Decision
+Implement a **custom API Gateway service** as a core infrastructure component in Epic 1:
+
+1. **API Gateway as Core Component**:
+   - Entry point: `cmd/api-gateway/`
+   - Implementation: `services/gateway/internal/`
+   - Implemented in Epic 1 (not deferred to Epic 8)
+   - Required for microservices architecture, not optional
+
+2. **Responsibilities**:
+   - **Request Routing**: Route requests to backend services via service discovery
+   - **Authentication**: Validate JWT tokens via Auth Service
+   - **Authorization**: Check permissions via Authz Service (for route-level auth)
+   - **Rate Limiting**: Per-user and per-IP rate limiting
+   - **CORS**: Handle cross-origin requests
+   - **Request Transformation**: Modify requests before forwarding
+   - **Response Transformation**: Modify responses before returning
+   - **Load Balancing**: Distribute requests across service instances
+
+3. **Integration Points**:
+   - Service registry for service discovery
+   - Auth Service client for token validation
+   - Authz Service client for permission checks
+   - Cache (Redis) for rate limiting state
+
+4. **Implementation Approach**:
+   - Built with Go (Gin/Echo framework)
+   - Uses service clients for backend communication
+   - Configurable routing rules
+   - Middleware-based architecture
+
+## Architecture
+
+```mermaid
+graph TB
+    Client[Client] --> Gateway[API Gateway<br/>:8080]
+    
+    Gateway --> AuthClient[Auth Service Client]
+    Gateway --> AuthzClient[Authz Service Client]
+    Gateway --> ServiceRegistry[Service Registry]
+    Gateway --> Cache[Cache<br/>Rate Limiting]
+    
+    AuthClient --> AuthSvc[Auth Service<br/>:8081]
+    AuthzClient --> AuthzSvc[Authz Service<br/>:8083]
+    ServiceRegistry --> BackendSvc[Backend Services]
+    
+    Gateway --> BackendSvc
+    
+    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
+    style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
+    style BackendSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
+```
+
+## Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant AuthSvc
+    participant AuthzSvc
+    participant Registry
+    participant BackendSvc
+    
+    Client->>Gateway: HTTP Request
+    Gateway->>Gateway: Rate limiting check
+    Gateway->>AuthSvc: Validate JWT (gRPC)
+    AuthSvc-->>Gateway: Token valid + user info
+    Gateway->>AuthzSvc: Check route permission (gRPC, optional)
+    AuthzSvc-->>Gateway: Authorized
+    Gateway->>Registry: Discover backend service
+    Registry-->>Gateway: Service endpoint
+    Gateway->>BackendSvc: Forward request (gRPC/HTTP)
+    BackendSvc-->>Gateway: Response
+    Gateway-->>Client: HTTP Response
+```
+
+## Consequences
+
+### Positive
+- **Single Entry Point**: All external traffic goes through one gateway
+- **Centralized Security**: Authentication and authorization at the edge
+- **Performance**: Rate limiting and caching at gateway level
+- **Flexibility**: Easy to add new routes and services
+- **Consistency**: Uniform API interface for clients
+- **Observability**: Central point for metrics and logging
+
+### Negative
+- **Single Point of Failure**: Gateway failure affects all traffic
+- **Additional Latency**: Extra hop in request path
+- **Complexity**: Additional service to maintain and deploy
+- **Scaling**: Gateway must scale to handle all traffic
+
+### Mitigations
+1. **High Availability**: Deploy multiple gateway instances behind load balancer
+2. **Circuit Breakers**: Implement circuit breakers for backend service failures
+3. **Caching**: Cache authentication results and service endpoints
+4. **Monitoring**: Comprehensive monitoring and alerting
+5. **Graceful Degradation**: Fallback mechanisms for service failures
+
+## Implementation Strategy
+
+### Epic 1: Core Infrastructure
+- Create `cmd/api-gateway/` entry point
+- Implement basic routing with service discovery
+- JWT validation via Auth Service client
+- Rate limiting middleware
+- CORS support
+
+### Epic 2-3: Enhanced Features
+- Permission-based routing (via Authz Service)
+- Request/response transformation
+- Advanced load balancing
+- Health check integration
+
+## Configuration
+
+```yaml
+gateway:
+  port: 8080
+  routes:
+    - path: /api/v1/auth/**
+      service: auth-service
+      auth_required: false
+    - path: /api/v1/users/**
+      service: identity-service
+      auth_required: true
+      permission: user.read
+    - path: /api/v1/blog/**
+      service: blog-service
+      auth_required: true
+      permission: blog.post.read
+  rate_limiting:
+    enabled: true
+    per_user: 100/minute
+    per_ip: 1000/minute
+  cors:
+    allowed_origins: ["*"]
+    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
+```
+
+## References
+- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md)
+- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md)
+- [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md)
+- [API Gateway Pattern](https://microservices.io/patterns/apigateway.html)
+