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

140
docs/content/architecture/system-behavior.md
View File

@@ -6,7 +6,7 @@ This document provides a high-level explanation of how the Go Platform behaves e
## Overview
The Go Platform is a microservices-based system where each module operates as an independent service. Services communicate via gRPC (primary) or HTTP (fallback), share infrastructure components (PostgreSQL, Redis, Kafka), and are orchestrated through service discovery and dependency injection.
The Go Platform is a microservices-based system where each service is independently deployable from day one. Services communicate via gRPC (primary) or HTTP (fallback) through service clients, share infrastructure components (PostgreSQL instance, Redis, Kafka), and are orchestrated through service discovery and dependency injection. All external traffic enters through the API Gateway.
## Key Concepts
@@ -16,9 +16,11 @@ The Go Platform is a microservices-based system where each module operates as an
- **Event Bus**: Asynchronous communication channel for events
- **DI Container**: Dependency injection container managing service lifecycle
## Application Bootstrap Sequence
## Service Bootstrap Sequence
The platform follows a well-defined startup sequence that ensures all services are properly initialized and registered.
Each service (API Gateway, Auth, Identity, Authz, Audit, and feature services) follows a well-defined startup sequence. Services bootstrap independently.
### Individual Service Startup
```mermaid
sequenceDiagram
@@ -26,9 +28,9 @@ sequenceDiagram
participant Config
participant Logger
participant DI
participant Registry
participant ModuleLoader
participant ServiceImpl
participant ServiceRegistry
participant DB
participant HTTP
participant gRPC
@@ -39,63 +41,121 @@ sequenceDiagram
Logger-->>Main: Logger ready
Main->>DI: Create DI container
DI->>DI: Register core services
DI->>DI: Register core kernel services
DI-->>Main: DI container ready
Main->>ModuleLoader: Discover modules
ModuleLoader->>ModuleLoader: Scan module directories
ModuleLoader->>ModuleLoader: Load module.yaml files
ModuleLoader-->>Main: Module list
Main->>ServiceImpl: Register service implementation
ServiceImpl->>DI: Register service dependencies
ServiceImpl->>DB: Connect to database
DB-->>ServiceImpl: Connection ready
Main->>Registry: Register modules
Registry->>Registry: Resolve dependencies
Registry->>Registry: Order modules
Registry-->>Main: Ordered modules
loop For each module
Main->>Module: Initialize module
Module->>DI: Register services
Module->>Registry: Register routes
Module->>Registry: Register migrations
end
Main->>Registry: Run migrations
Registry->>Registry: Execute in dependency order
Main->>DB: Run migrations
DB-->>Main: Migrations complete
Main->>ServiceRegistry: Register service
ServiceRegistry->>ServiceRegistry: Register with Consul/K8s
ServiceRegistry-->>Main: Service registered
Main->>gRPC: Start gRPC server
Main->>HTTP: Start HTTP server
HTTP-->>Main: Server ready
gRPC-->>Main: Server ready
Main->>HTTP: Start HTTP server (if needed)
HTTP-->>Main: HTTP server ready
gRPC-->>Main: gRPC server ready
Main->>DI: Start lifecycle
DI->>DI: Execute OnStart hooks
DI-->>Main: All services started
DI-->>Main: Service started
```
### Bootstrap Phases
### Platform Startup (All Services)
```mermaid
sequenceDiagram
participant Docker
participant Gateway
participant AuthSvc
participant IdentitySvc
participant AuthzSvc
participant AuditSvc
participant BlogSvc
participant Registry
participant DB
Docker->>DB: Start PostgreSQL
Docker->>Registry: Start Consul
DB-->>Docker: Database ready
Registry-->>Docker: Registry ready
par Service Startup (in parallel)
Docker->>Gateway: Start API Gateway
Gateway->>Registry: Register
Gateway->>Gateway: Start HTTP server
Gateway-->>Docker: Gateway ready
and
Docker->>AuthSvc: Start Auth Service
AuthSvc->>DB: Connect
AuthSvc->>Registry: Register
AuthSvc->>AuthSvc: Start gRPC server
AuthSvc-->>Docker: Auth Service ready
and
Docker->>IdentitySvc: Start Identity Service
IdentitySvc->>DB: Connect
IdentitySvc->>Registry: Register
IdentitySvc->>IdentitySvc: Start gRPC server
IdentitySvc-->>Docker: Identity Service ready
and
Docker->>AuthzSvc: Start Authz Service
AuthzSvc->>DB: Connect
AuthzSvc->>Registry: Register
AuthzSvc->>AuthzSvc: Start gRPC server
AuthzSvc-->>Docker: Authz Service ready
and
Docker->>AuditSvc: Start Audit Service
AuditSvc->>DB: Connect
AuditSvc->>Registry: Register
AuditSvc->>AuditSvc: Start gRPC server
AuditSvc-->>Docker: Audit Service ready
and
Docker->>BlogSvc: Start Blog Service
BlogSvc->>DB: Connect
BlogSvc->>Registry: Register
BlogSvc->>BlogSvc: Start gRPC server
BlogSvc-->>Docker: Blog Service ready
end
Docker->>Docker: All services ready
```
### Service Bootstrap Phases (Per Service)
1. **Configuration Loading**: Load YAML files, environment variables, and secrets
2. **Foundation Services**: Initialize logger, config provider, DI container
3. **Module Discovery**: Scan and load module manifests
4. **Dependency Resolution**: Build dependency graph and order modules
5. **Module Initialization**: Initialize each module in dependency order
6. **Database Migrations**: Run migrations in dependency order
7. **Service Registration**: Register service with service registry
8. **Server Startup**: Start HTTP and gRPC servers
9. **Lifecycle Hooks**: Execute OnStart hooks for all services
2. **Foundation Services**: Initialize core kernel (logger, config, DI container)
3. **Database Connection**: Connect to database with own connection pool
4. **Service Implementation**: Register service-specific implementations
5. **Database Migrations**: Run service-specific migrations
6. **Service Registration**: Register service with service registry
7. **Server Startup**: Start gRPC server (and HTTP if needed)
8. **Lifecycle Hooks**: Execute OnStart hooks
### Platform Startup Order
1. **Infrastructure**: Start PostgreSQL, Redis, Kafka, Consul
2. **Core Services**: Start Auth, Identity, Authz, Audit services (can start in parallel)
3. **API Gateway**: Start API Gateway (depends on service registry)
4. **Feature Services**: Start Blog, Billing, etc. (can start in parallel)
5. **Health Checks**: All services report healthy to registry
## Request Processing Pipeline
Every HTTP request flows through a standardized pipeline that ensures security, observability, and proper error handling.
Every HTTP request flows through API Gateway first, then to backend services. The pipeline ensures security, observability, and proper error handling.
```mermaid
graph TD
Start([HTTP Request]) --> Auth[Authentication Middleware]
Auth -->|Valid Token| Authz[Authorization Middleware]
Start([HTTP Request]) --> Gateway[API Gateway]
Gateway --> RateLimit[Rate Limiting]
RateLimit -->|Allowed| Auth[Validate JWT via Auth Service]
RateLimit -->|Exceeded| Error0[429 Too Many Requests]
Auth -->|Valid Token| Authz[Check Permission via Authz Service]
Auth -->|Invalid Token| Error1[401 Unauthorized]
Authz -->|Authorized| RateLimit[Rate Limiting]