895 lines
24 KiB
Markdown
895 lines
24 KiB
Markdown
# System Architecture
|
|
|
|
This document provides a comprehensive overview of the Go Platform architecture, including system components, their relationships, and how modules integrate with the core platform.
|
|
|
|
## Table of Contents
|
|
|
|
- [High-Level Architecture](#high-level-architecture)
|
|
- [Layered Architecture](#layered-architecture)
|
|
- [Module System Architecture](#module-system-architecture)
|
|
- [Component Relationships](#component-relationships)
|
|
- [Data Flow](#data-flow)
|
|
- [Deployment Architecture](#deployment-architecture)
|
|
|
|
## High-Level Architecture
|
|
|
|
The Go Platform follows a **microservices architecture** where each service is independently deployable from day one:
|
|
|
|
- **Core Kernel**: Infrastructure only (config, logger, DI, health, metrics, observability) - no business logic
|
|
- **Core Services**: Auth Service, Identity Service, Authz Service, Audit Service - separate microservices
|
|
- **API Gateway**: Single entry point for all external traffic, handles routing and authentication
|
|
- **Feature Services**: Blog, Billing, Analytics, etc. - independent services
|
|
- **Infrastructure Adapters**: Cache, Event Bus, Scheduler, etc. - shared infrastructure
|
|
|
|
All services communicate via gRPC (primary) or HTTP (fallback) through service client interfaces, with service discovery via a service registry. Each service has its own database connection pool and schema. Services share infrastructure (PostgreSQL instance, Redis, Kafka) but are independently deployable and scalable.
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "API Gateway"
|
|
Gateway[API Gateway<br/>:8080]
|
|
end
|
|
|
|
subgraph "Core Services"
|
|
AuthSvc[Auth Service<br/>:8081]
|
|
IdentitySvc[Identity Service<br/>:8082]
|
|
AuthzSvc[Authz Service<br/>:8083]
|
|
AuditSvc[Audit Service<br/>:8084]
|
|
end
|
|
|
|
subgraph "Feature Services"
|
|
BlogSvc[Blog Service<br/>:8091]
|
|
BillingSvc[Billing Service<br/>:8092]
|
|
AnalyticsSvc[Analytics Service<br/>:8093]
|
|
end
|
|
|
|
subgraph "Core Kernel"
|
|
Kernel[Core Kernel<br/>Infrastructure Only]
|
|
end
|
|
|
|
subgraph "Infrastructure"
|
|
DB[(PostgreSQL)]
|
|
Cache[(Redis)]
|
|
Queue[Kafka/Event Bus]
|
|
Storage[S3/Blob Storage]
|
|
Registry[Service Registry]
|
|
end
|
|
|
|
subgraph "External Services"
|
|
OIDC[OIDC Provider]
|
|
Email[Email Service]
|
|
Sentry[Sentry]
|
|
end
|
|
|
|
Gateway --> AuthSvc
|
|
Gateway --> IdentitySvc
|
|
Gateway --> AuthzSvc
|
|
Gateway --> BlogSvc
|
|
Gateway --> BillingSvc
|
|
|
|
AuthSvc --> IdentitySvc
|
|
AuthSvc --> Registry
|
|
AuthzSvc --> IdentitySvc
|
|
AuthzSvc --> Cache
|
|
AuthzSvc --> AuditSvc
|
|
BlogSvc --> AuthzSvc
|
|
BlogSvc --> IdentitySvc
|
|
BlogSvc --> Registry
|
|
|
|
AuthSvc --> DB
|
|
IdentitySvc --> DB
|
|
AuthzSvc --> DB
|
|
AuditSvc --> DB
|
|
BlogSvc --> DB
|
|
BillingSvc --> DB
|
|
|
|
AuthSvc --> Cache
|
|
AuthzSvc --> Cache
|
|
BlogSvc --> Cache
|
|
BillingSvc --> Cache
|
|
|
|
BlogSvc --> Queue
|
|
BillingSvc --> Queue
|
|
AnalyticsSvc --> Queue
|
|
|
|
Kernel --> DB
|
|
Kernel --> Cache
|
|
Kernel --> Queue
|
|
Kernel --> Registry
|
|
|
|
AuthSvc --> OIDC
|
|
IdentitySvc --> Email
|
|
AuditSvc --> Sentry
|
|
|
|
style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
style Kernel fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
|
style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
style IdentitySvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
style BlogSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
|
style BillingSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
## Layered Architecture
|
|
|
|
The platform follows a **hexagonal architecture** with clear separation of concerns across layers.
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph "Presentation Layer"
|
|
HTTP[HTTP/REST API]
|
|
GraphQL[GraphQL API]
|
|
CLI[CLI Interface]
|
|
end
|
|
|
|
subgraph "Application Layer"
|
|
AuthMiddleware[Auth Middleware]
|
|
AuthzMiddleware[Authorization Middleware]
|
|
RateLimit[Rate Limiting]
|
|
Handlers[Request Handlers]
|
|
end
|
|
|
|
subgraph "Domain Layer"
|
|
Services[Domain Services]
|
|
Entities[Domain Entities]
|
|
Policies[Business Policies]
|
|
end
|
|
|
|
subgraph "Infrastructure Layer"
|
|
Repos[Repositories]
|
|
CacheAdapter[Cache Adapter]
|
|
EventBus[Event Bus]
|
|
Jobs[Scheduler/Jobs]
|
|
end
|
|
|
|
subgraph "Core Kernel (Infrastructure Only)"
|
|
DI[DI Container]
|
|
Config[Config Manager]
|
|
Logger[Logger]
|
|
Metrics[Metrics]
|
|
Health[Health Checks]
|
|
Tracer[OpenTelemetry Tracer]
|
|
end
|
|
|
|
HTTP --> AuthMiddleware
|
|
GraphQL --> AuthMiddleware
|
|
CLI --> AuthMiddleware
|
|
|
|
AuthMiddleware --> AuthzMiddleware
|
|
AuthzMiddleware --> RateLimit
|
|
RateLimit --> Handlers
|
|
|
|
Handlers --> Services
|
|
Services --> Entities
|
|
Services --> Policies
|
|
|
|
Services --> Repos
|
|
Services --> CacheAdapter
|
|
Services --> EventBus
|
|
Services --> Jobs
|
|
|
|
Repos --> DB[(Database)]
|
|
CacheAdapter --> Cache[(Redis)]
|
|
EventBus --> Queue[(Kafka)]
|
|
|
|
Services --> DI
|
|
Repos --> DI
|
|
Handlers --> DI
|
|
|
|
DI --> Config
|
|
DI --> Logger
|
|
DI --> Metrics
|
|
DI --> Health
|
|
|
|
style Core fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
style Services fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
|
style Repos fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
## Module System Architecture
|
|
|
|
Modules are the building blocks of the platform. Each module can register services, routes, permissions, and background jobs.
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph Lifecycle["Module Lifecycle"]
|
|
Discover["1. Discover Modules"]
|
|
Load["2. Load Module"]
|
|
Validate["3. Validate Dependencies"]
|
|
Init["4. Initialize Module"]
|
|
Start["5. Start Module"]
|
|
end
|
|
|
|
subgraph Registration["Module Registration"]
|
|
Static["Static Registration<br/>via init()"]
|
|
Dynamic["Dynamic Loading<br/>via .so files"]
|
|
end
|
|
|
|
subgraph Components["Module Components"]
|
|
Routes["HTTP Routes"]
|
|
Services["Services"]
|
|
Repos["Repositories"]
|
|
Perms["Permissions"]
|
|
Jobs["Background Jobs"]
|
|
Migrations["Database Migrations"]
|
|
end
|
|
|
|
Discover --> Load
|
|
Load --> Static
|
|
Load --> Dynamic
|
|
Static --> Validate
|
|
Dynamic --> Validate
|
|
Validate --> Init
|
|
Init --> Routes
|
|
Init --> Services
|
|
Init --> Repos
|
|
Init --> Perms
|
|
Init --> Jobs
|
|
Init --> Migrations
|
|
Routes --> Start
|
|
Services --> Start
|
|
Repos --> Start
|
|
Perms --> Start
|
|
Jobs --> Start
|
|
Migrations --> Start
|
|
|
|
classDef lifecycle fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
|
classDef registration fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
|
classDef components fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
|
classDef start fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
|
|
class Discover,Load,Validate,Init lifecycle
|
|
class Static,Dynamic registration
|
|
class Routes,Services,Repos,Perms,Jobs,Migrations components
|
|
class Start start
|
|
```
|
|
|
|
### Module Initialization Sequence
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Main
|
|
participant Loader
|
|
participant Registry
|
|
participant Module
|
|
participant DI
|
|
participant Router
|
|
participant DB
|
|
|
|
Main->>Loader: LoadModules()
|
|
Loader->>Registry: Discover modules
|
|
Registry-->>Loader: List of modules
|
|
|
|
loop For each module
|
|
Loader->>Module: Load module
|
|
Module->>Registry: Register(module)
|
|
Registry->>Registry: Validate dependencies
|
|
end
|
|
|
|
Main->>Registry: GetAllModules()
|
|
Registry-->>Main: Ordered module list
|
|
|
|
Main->>DI: Create container
|
|
|
|
loop For each module
|
|
Main->>Module: Init()
|
|
Module->>DI: Provide services
|
|
Module->>Router: Register routes
|
|
Module->>DB: Register migrations
|
|
end
|
|
|
|
Main->>DB: Run migrations
|
|
Main->>Router: Start HTTP server
|
|
```
|
|
|
|
## Component Relationships
|
|
|
|
This diagram shows how core components interact with each other and with modules.
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Core Kernel Components (Infrastructure)"
|
|
ConfigMgr[Config Manager]
|
|
LoggerService[Logger Service]
|
|
DI[DI Container]
|
|
ModuleLoader[Module Loader]
|
|
HealthRegistry[Health Registry]
|
|
MetricsRegistry[Metrics Registry]
|
|
ErrorBus[Error Bus]
|
|
Tracer[OpenTelemetry Tracer]
|
|
ServiceRegistry[Service Registry]
|
|
end
|
|
|
|
subgraph "Core Services (Separate Microservices)"
|
|
AuthService[Auth Service<br/>:8081]
|
|
IdentityService[Identity Service<br/>:8082]
|
|
AuthzService[Authz Service<br/>:8083]
|
|
AuditService[Audit Service<br/>:8084]
|
|
end
|
|
|
|
subgraph "Infrastructure Adapters"
|
|
EventBus[Event Bus<br/>Kafka]
|
|
CacheService[Cache Service<br/>Redis]
|
|
end
|
|
|
|
subgraph "Infrastructure Components"
|
|
DBClient[Database Client]
|
|
CacheClient[Cache Client]
|
|
Scheduler[Scheduler]
|
|
Notifier[Notifier]
|
|
end
|
|
|
|
subgraph "External Services"
|
|
Sentry[Sentry<br/>Error Reporting]
|
|
end
|
|
|
|
subgraph "Module Components"
|
|
ModuleRoutes[Module Routes]
|
|
ModuleServices[Module Services]
|
|
ModuleRepos[Module Repositories]
|
|
end
|
|
|
|
DI --> ConfigMgr
|
|
DI --> LoggerService
|
|
DI --> ModuleLoader
|
|
DI --> HealthRegistry
|
|
DI --> MetricsRegistry
|
|
DI --> ErrorBus
|
|
DI --> Tracer
|
|
DI --> ServiceRegistry
|
|
|
|
ModuleServices -->|gRPC| AuthService
|
|
ModuleServices -->|gRPC| IdentityService
|
|
ModuleServices -->|gRPC| AuthzService
|
|
ModuleServices -->|gRPC| AuditService
|
|
ModuleServices --> EventBus
|
|
ModuleServices --> CacheService
|
|
|
|
ModuleServices --> DBClient
|
|
ModuleRepos --> DBClient
|
|
|
|
AuthService --> DBClient
|
|
IdentityService --> DBClient
|
|
AuthzService --> DBClient
|
|
AuditService --> DBClient
|
|
|
|
AuthService --> ServiceRegistry
|
|
IdentityService --> ServiceRegistry
|
|
AuthzService --> ServiceRegistry
|
|
AuditService --> ServiceRegistry
|
|
|
|
ErrorBus --> LoggerService
|
|
ErrorBus --> Sentry
|
|
|
|
style DI fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
style AuthService fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
style IdentityService fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
style ModuleServices fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
### Request Processing Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client
|
|
participant Gateway[API Gateway]
|
|
participant AuthSvc[Auth Service]
|
|
participant AuthzSvc[Authz Service]
|
|
participant Service[Feature Service]
|
|
participant IdentitySvc[Identity Service]
|
|
participant AuditSvc[Audit Service]
|
|
participant Repo
|
|
participant DB
|
|
participant Cache
|
|
participant EventBus
|
|
|
|
Client->>Gateway: HTTP Request
|
|
Gateway->>Gateway: Rate limiting
|
|
Gateway->>AuthSvc: Validate JWT token (gRPC)
|
|
AuthSvc->>AuthSvc: Verify token
|
|
AuthSvc-->>Gateway: Token valid + user info
|
|
|
|
Gateway->>AuthzSvc: Check permissions (gRPC)
|
|
AuthzSvc->>AuthzSvc: Resolve permissions
|
|
AuthzSvc-->>Gateway: Authorized
|
|
|
|
Gateway->>Service: Route to service (gRPC/HTTP)
|
|
Service->>Cache: Check cache
|
|
Cache-->>Service: Cache miss
|
|
|
|
Service->>Repo: Query data
|
|
Repo->>DB: Execute query
|
|
DB-->>Repo: Return data
|
|
Repo-->>Service: Domain entity
|
|
Service->>Cache: Store in cache
|
|
|
|
Service->>IdentitySvc: Get user info (gRPC, if needed)
|
|
IdentitySvc-->>Service: User data
|
|
|
|
Service->>EventBus: Publish event
|
|
Service->>AuditSvc: Record action (gRPC)
|
|
|
|
Service-->>Gateway: Response data
|
|
Gateway-->>Client: JSON response
|
|
```
|
|
|
|
### Module Event Flow
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph "Module A"
|
|
AService[Service A]
|
|
AHandler[Handler A]
|
|
end
|
|
|
|
subgraph "Event Bus"
|
|
Bus[Event Bus]
|
|
end
|
|
|
|
subgraph "Module B"
|
|
BService[Service B]
|
|
BHandler[Handler B]
|
|
end
|
|
|
|
subgraph "Module C"
|
|
CService[Service C]
|
|
end
|
|
|
|
AHandler --> AService
|
|
AService -->|Publish Event| Bus
|
|
Bus -->|Subscribe| BService
|
|
Bus -->|Subscribe| CService
|
|
BService --> BHandler
|
|
CService --> CService
|
|
```
|
|
|
|
## Deployment Architecture
|
|
|
|
### Development Deployment
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Developer Machine"
|
|
IDE[IDE/Editor]
|
|
Go[Go Runtime]
|
|
Docker[Docker]
|
|
end
|
|
|
|
subgraph "Local Services"
|
|
Gateway[API Gateway<br/>:8080]
|
|
AuthSvc[Auth Service<br/>:8081]
|
|
IdentitySvc[Identity Service<br/>:8082]
|
|
AuthzSvc[Authz Service<br/>:8083]
|
|
AuditSvc[Audit Service<br/>:8084]
|
|
BlogSvc[Blog Service<br/>:8091]
|
|
DB[(PostgreSQL<br/>:5432)]
|
|
Redis[(Redis<br/>:6379)]
|
|
Kafka[Kafka<br/>:9092]
|
|
Consul[Consul<br/>:8500]
|
|
end
|
|
|
|
IDE --> Go
|
|
Go --> Gateway
|
|
Go --> AuthSvc
|
|
Go --> IdentitySvc
|
|
Go --> AuthzSvc
|
|
Go --> AuditSvc
|
|
Go --> BlogSvc
|
|
|
|
Gateway --> AuthSvc
|
|
Gateway --> IdentitySvc
|
|
Gateway --> BlogSvc
|
|
|
|
AuthSvc --> DB
|
|
IdentitySvc --> DB
|
|
AuthzSvc --> DB
|
|
AuditSvc --> DB
|
|
BlogSvc --> DB
|
|
|
|
AuthSvc --> Redis
|
|
AuthzSvc --> Redis
|
|
BlogSvc --> Redis
|
|
|
|
BlogSvc --> Kafka
|
|
|
|
AuthSvc --> Consul
|
|
IdentitySvc --> Consul
|
|
AuthzSvc --> Consul
|
|
AuditSvc --> Consul
|
|
BlogSvc --> Consul
|
|
|
|
Docker --> DB
|
|
Docker --> Redis
|
|
Docker --> Kafka
|
|
Docker --> Consul
|
|
|
|
style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
|
style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
style IdentitySvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
### Production Deployment
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Load Balancer"
|
|
LB[Load Balancer<br/>HTTPS]
|
|
end
|
|
|
|
subgraph "Service Instances"
|
|
Gateway1[API Gateway 1]
|
|
Gateway2[API Gateway 2]
|
|
AuthSvc1[Auth Service 1]
|
|
AuthSvc2[Auth Service 2]
|
|
IdentitySvc1[Identity Service 1]
|
|
IdentitySvc2[Identity Service 2]
|
|
BlogSvc1[Blog Service 1]
|
|
BlogSvc2[Blog Service 2]
|
|
end
|
|
|
|
subgraph "Database Cluster"
|
|
Primary[(PostgreSQL<br/>Primary)]
|
|
Replica[(PostgreSQL<br/>Replica)]
|
|
end
|
|
|
|
subgraph "Cache Cluster"
|
|
Redis1[(Redis<br/>Master)]
|
|
Redis2[(Redis<br/>Replica)]
|
|
end
|
|
|
|
subgraph "Message Queue"
|
|
Kafka1[Kafka Broker 1]
|
|
Kafka2[Kafka Broker 2]
|
|
Kafka3[Kafka Broker 3]
|
|
end
|
|
|
|
subgraph "Observability"
|
|
Prometheus[Prometheus]
|
|
Grafana[Grafana]
|
|
Jaeger[Jaeger]
|
|
Loki[Loki]
|
|
end
|
|
|
|
subgraph "External Services"
|
|
Sentry[Sentry]
|
|
S3[S3 Storage]
|
|
end
|
|
|
|
LB --> Gateway1
|
|
LB --> Gateway2
|
|
|
|
Gateway1 --> AuthSvc1
|
|
Gateway1 --> AuthSvc2
|
|
Gateway1 --> IdentitySvc1
|
|
Gateway1 --> IdentitySvc2
|
|
Gateway1 --> BlogSvc1
|
|
Gateway1 --> BlogSvc2
|
|
Gateway2 --> AuthSvc1
|
|
Gateway2 --> AuthSvc2
|
|
Gateway2 --> IdentitySvc1
|
|
Gateway2 --> IdentitySvc2
|
|
Gateway2 --> BlogSvc1
|
|
Gateway2 --> BlogSvc2
|
|
|
|
AuthSvc1 --> Primary
|
|
AuthSvc2 --> Primary
|
|
IdentitySvc1 --> Primary
|
|
IdentitySvc2 --> Primary
|
|
BlogSvc1 --> Primary
|
|
BlogSvc2 --> Primary
|
|
|
|
AuthSvc1 --> Replica
|
|
AuthSvc2 --> Replica
|
|
IdentitySvc1 --> Replica
|
|
IdentitySvc2 --> Replica
|
|
BlogSvc1 --> Replica
|
|
BlogSvc2 --> Replica
|
|
|
|
AuthSvc1 --> Redis1
|
|
AuthSvc2 --> Redis1
|
|
IdentitySvc1 --> Redis1
|
|
IdentitySvc2 --> Redis1
|
|
BlogSvc1 --> Redis1
|
|
BlogSvc2 --> Redis1
|
|
|
|
BlogSvc1 --> Kafka1
|
|
BlogSvc2 --> Kafka2
|
|
|
|
AuthSvc1 --> Prometheus
|
|
AuthSvc2 --> Prometheus
|
|
IdentitySvc1 --> Prometheus
|
|
IdentitySvc2 --> Prometheus
|
|
BlogSvc1 --> Prometheus
|
|
BlogSvc2 --> Prometheus
|
|
|
|
Prometheus --> Grafana
|
|
AuthSvc1 --> Jaeger
|
|
AuthSvc2 --> Jaeger
|
|
IdentitySvc1 --> Jaeger
|
|
IdentitySvc2 --> Jaeger
|
|
BlogSvc1 --> Jaeger
|
|
BlogSvc2 --> Jaeger
|
|
AuthSvc1 --> Loki
|
|
AuthSvc2 --> Loki
|
|
IdentitySvc1 --> Loki
|
|
IdentitySvc2 --> Loki
|
|
BlogSvc1 --> Loki
|
|
BlogSvc2 --> Loki
|
|
|
|
AuthSvc1 --> Sentry
|
|
AuthSvc2 --> Sentry
|
|
IdentitySvc1 --> Sentry
|
|
IdentitySvc2 --> Sentry
|
|
BlogSvc1 --> Sentry
|
|
BlogSvc2 --> Sentry
|
|
|
|
BlogSvc1 --> S3
|
|
BlogSvc2 --> S3
|
|
|
|
style LB fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
style Gateway1 fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
|
style Gateway2 fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
|
style Primary fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
|
style Redis1 fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
## Core Kernel Components
|
|
|
|
The core kernel provides **infrastructure only** - no business logic. It is the foundation that all services depend on. Business logic resides in separate services (Auth, Identity, Authz, Audit).
|
|
|
|
### Component Responsibilities
|
|
|
|
```mermaid
|
|
mindmap
|
|
root((Core Kernel))
|
|
Configuration
|
|
Load configs
|
|
Environment vars
|
|
Secret management
|
|
Dependency Injection
|
|
Service registration
|
|
Lifecycle management
|
|
Module wiring
|
|
Logging
|
|
Structured logs
|
|
Request correlation
|
|
Log levels
|
|
Observability
|
|
Metrics
|
|
Tracing
|
|
Health checks
|
|
Service Discovery
|
|
Service registry
|
|
Service registration
|
|
Health checking
|
|
Module System
|
|
Module discovery
|
|
Module loading
|
|
Dependency resolution
|
|
```
|
|
|
|
## Module Integration Points
|
|
|
|
Modules integrate with the core through well-defined interfaces:
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Core Kernel Interfaces"
|
|
IConfig[ConfigProvider]
|
|
ILogger[Logger]
|
|
ITracer[Tracer]
|
|
IMetrics[Metrics]
|
|
IHealth[Health]
|
|
end
|
|
|
|
subgraph "Service Client Interfaces"
|
|
IAuthClient[AuthServiceClient]
|
|
IIdentityClient[IdentityServiceClient]
|
|
IAuthzClient[AuthzServiceClient]
|
|
IAuditClient[AuditServiceClient]
|
|
end
|
|
|
|
subgraph "Infrastructure Interfaces"
|
|
IEventBus[EventBus]
|
|
ICache[Cache]
|
|
IBlobStore[BlobStore]
|
|
IScheduler[Scheduler]
|
|
INotifier[Notifier]
|
|
end
|
|
|
|
subgraph "Feature Service Implementation"
|
|
Module[Feature Service]
|
|
ModuleServices[Service Layer]
|
|
ModuleRoutes[HTTP/gRPC Routes]
|
|
end
|
|
|
|
Module --> IConfig
|
|
Module --> ILogger
|
|
Module --> ITracer
|
|
Module --> IMetrics
|
|
Module --> IHealth
|
|
|
|
ModuleServices -->|gRPC| IAuthClient
|
|
ModuleServices -->|gRPC| IIdentityClient
|
|
ModuleServices -->|gRPC| IAuthzClient
|
|
ModuleServices -->|gRPC| IAuditClient
|
|
ModuleServices --> IEventBus
|
|
ModuleServices --> ICache
|
|
ModuleServices --> IBlobStore
|
|
ModuleServices --> IScheduler
|
|
ModuleServices --> INotifier
|
|
|
|
ModuleRoutes -->|gRPC| IAuthzClient
|
|
|
|
style IConfig fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
|
style Module fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
## Microservices Architecture
|
|
|
|
The platform is designed as **microservices from day one**, with each module being an independent service.
|
|
|
|
### Service Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "API Gateway"
|
|
Gateway[API Gateway<br/>Routing & Auth]
|
|
end
|
|
|
|
subgraph "Core Services"
|
|
AuthSvc[Auth Service<br/>:8081]
|
|
IdentitySvc[Identity Service<br/>:8082]
|
|
AuthzSvc[Authz Service<br/>:8083]
|
|
AuditSvc[Audit Service<br/>:8084]
|
|
end
|
|
|
|
subgraph "Feature Services"
|
|
BlogSvc[Blog Service<br/>:8091]
|
|
BillingSvc[Billing Service<br/>:8092]
|
|
AnalyticsSvc[Analytics Service<br/>:8093]
|
|
end
|
|
|
|
subgraph "Infrastructure"
|
|
DB[(PostgreSQL)]
|
|
Cache[(Redis)]
|
|
Queue[Kafka]
|
|
Registry[Service Registry]
|
|
end
|
|
|
|
Gateway --> AuthSvc
|
|
Gateway --> IdentitySvc
|
|
Gateway --> BlogSvc
|
|
Gateway --> BillingSvc
|
|
|
|
AuthSvc --> IdentitySvc
|
|
AuthSvc --> Registry
|
|
BlogSvc --> AuthzSvc
|
|
BlogSvc --> IdentitySvc
|
|
BlogSvc --> Registry
|
|
BillingSvc --> IdentitySvc
|
|
BillingSvc --> Registry
|
|
|
|
AuthSvc --> DB
|
|
IdentitySvc --> DB
|
|
BlogSvc --> DB
|
|
BillingSvc --> DB
|
|
|
|
AuthSvc --> Cache
|
|
BlogSvc --> Cache
|
|
BillingSvc --> Cache
|
|
|
|
BlogSvc --> Queue
|
|
BillingSvc --> Queue
|
|
AnalyticsSvc --> Queue
|
|
|
|
style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
### Service Communication
|
|
|
|
All inter-service communication uses service client interfaces:
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Service Client Interface"
|
|
Interface[Service Interface<br/>pkg/services/]
|
|
end
|
|
|
|
subgraph "Implementations"
|
|
GRPC[gRPC Client<br/>Primary]
|
|
HTTP[HTTP Client<br/>Fallback]
|
|
end
|
|
|
|
subgraph "Service Registry"
|
|
Registry[Service Registry<br/>Discovery & Resolution]
|
|
end
|
|
|
|
Interface --> GRPC
|
|
Interface --> HTTP
|
|
|
|
Registry --> GRPC
|
|
Registry --> HTTP
|
|
|
|
style Interface fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
|
```
|
|
|
|
### Service Communication Patterns
|
|
|
|
The platform uses three communication patterns:
|
|
|
|
1. **Synchronous Service Calls** (via Service Clients):
|
|
- gRPC calls (primary) - type-safe, efficient
|
|
- HTTP/REST calls (fallback) - for external integration
|
|
- All calls go through service client interfaces
|
|
- Service discovery via registry
|
|
|
|
2. **Asynchronous Events** (via Event Bus):
|
|
- Distributed via Kafka
|
|
- Preferred for cross-service communication
|
|
- Event-driven architecture for loose coupling
|
|
|
|
3. **Shared Infrastructure** (For state):
|
|
- Redis for cache and distributed state
|
|
- PostgreSQL for persistent data
|
|
- Kafka for events
|
|
|
|
### Service Registry
|
|
|
|
The service registry enables service discovery and resolution:
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Service Registry"
|
|
Registry[Service Registry Interface]
|
|
Consul[Consul Registry]
|
|
K8s[K8s Service Discovery]
|
|
Etcd[etcd Registry]
|
|
end
|
|
|
|
subgraph "Services"
|
|
AuthSvc[Auth Service]
|
|
IdentitySvc[Identity Service]
|
|
BlogSvc[Blog Service]
|
|
end
|
|
|
|
Registry --> Consul
|
|
Registry --> K8s
|
|
Registry --> Etcd
|
|
|
|
Consul --> AuthSvc
|
|
K8s --> IdentitySvc
|
|
Etcd --> BlogSvc
|
|
|
|
style Registry fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
|
```
|
|
|
|
### Scaling Strategy
|
|
|
|
#### Independent Service Scaling
|
|
- Scale individual services based on load
|
|
- Independent resource allocation
|
|
- Independent deployment
|
|
- Better resource utilization
|
|
- Team autonomy
|
|
|
|
#### Development Mode
|
|
- For local development, services can run in the same repository/monorepo
|
|
- Services still communicate via gRPC/HTTP through service clients (no direct in-process calls)
|
|
- Each service has its own process and entry point
|
|
- Docker Compose for easy local setup with all services
|
|
- Maintains microservices architecture even in development
|
|
- Services can be started individually for debugging
|
|
|
|
## Next Steps
|
|
|
|
- [Module Architecture](./architecture-modules.md) - Detailed module architecture and design
|
|
- [Module Requirements](./module-requirements.md) - Requirements for each module
|
|
- [Component Relationships](./component-relationships.md) - Detailed component interactions
|
|
- [ADRs](../adr/README.md) - Architecture Decision Records
|
|
- [ADR-0029: Microservices Architecture](../adr/0029-microservices-architecture.md) - Microservices strategy
|
|
- [ADR-0030: Service Communication](../adr/0030-service-communication-strategy.md) - Communication patterns
|
|
|