docs: add mkdocs, update links, add architecture documentation
This commit is contained in:
455
docs/content/component-relationships.md
Normal file
455
docs/content/component-relationships.md
Normal file
@@ -0,0 +1,455 @@
|
||||
# Component Relationships
|
||||
|
||||
This document details how different components of the Go Platform interact with each other, including dependency relationships, data flow, and integration patterns.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Core Component Dependencies](#core-component-dependencies)
|
||||
- [Module to Core Integration](#module-to-core-integration)
|
||||
- [Service Interaction Patterns](#service-interaction-patterns)
|
||||
- [Data Flow Patterns](#data-flow-patterns)
|
||||
- [Dependency Graph](#dependency-graph)
|
||||
|
||||
## Core Component Dependencies
|
||||
|
||||
The core kernel components have well-defined dependencies that form the foundation of the platform.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Foundation Layer"
|
||||
Config[Config Manager]
|
||||
Logger[Logger Service]
|
||||
end
|
||||
|
||||
subgraph "DI Layer"
|
||||
DI[DI Container]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure Layer"
|
||||
DB[Database Client]
|
||||
Cache[Cache Client]
|
||||
EventBus[Event Bus]
|
||||
Scheduler[Scheduler]
|
||||
end
|
||||
|
||||
subgraph "Security Layer"
|
||||
Auth[Auth Service]
|
||||
Authz[Authz Service]
|
||||
Audit[Audit Service]
|
||||
end
|
||||
|
||||
subgraph "Observability Layer"
|
||||
Metrics[Metrics Registry]
|
||||
Health[Health Registry]
|
||||
Tracer[OpenTelemetry Tracer]
|
||||
end
|
||||
|
||||
Config --> Logger
|
||||
Config --> DI
|
||||
Logger --> DI
|
||||
|
||||
DI --> DB
|
||||
DI --> Cache
|
||||
DI --> EventBus
|
||||
DI --> Scheduler
|
||||
DI --> Auth
|
||||
DI --> Authz
|
||||
DI --> Audit
|
||||
DI --> Metrics
|
||||
DI --> Health
|
||||
DI --> Tracer
|
||||
|
||||
Auth --> DB
|
||||
Authz --> DB
|
||||
Authz --> Cache
|
||||
Audit --> DB
|
||||
|
||||
DB --> Tracer
|
||||
Cache --> Tracer
|
||||
EventBus --> Tracer
|
||||
|
||||
style Config fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
||||
style DI fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
|
||||
style Auth fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
## Module to Core Integration
|
||||
|
||||
Modules integrate with core services through well-defined interfaces and dependency injection.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Feature Module"
|
||||
ModuleHandler[Module Handler]
|
||||
ModuleService[Module Service]
|
||||
ModuleRepo[Module Repository]
|
||||
end
|
||||
|
||||
subgraph "Core Services"
|
||||
AuthService[Auth Service]
|
||||
AuthzService[Authz Service]
|
||||
EventBusService[Event Bus]
|
||||
CacheService[Cache Service]
|
||||
AuditService[Audit Service]
|
||||
LoggerService[Logger Service]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure"
|
||||
DBClient[Database Client]
|
||||
CacheClient[Cache Client]
|
||||
QueueClient[Message Queue]
|
||||
end
|
||||
|
||||
ModuleHandler --> AuthService
|
||||
ModuleHandler --> AuthzService
|
||||
ModuleHandler --> ModuleService
|
||||
|
||||
ModuleService --> ModuleRepo
|
||||
ModuleService --> EventBusService
|
||||
ModuleService --> CacheService
|
||||
ModuleService --> AuditService
|
||||
ModuleService --> LoggerService
|
||||
|
||||
ModuleRepo --> DBClient
|
||||
CacheService --> CacheClient
|
||||
EventBusService --> QueueClient
|
||||
|
||||
style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
||||
style AuthService fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
||||
style DBClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
## Service Interaction Patterns
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Router
|
||||
participant AuthMiddleware
|
||||
participant AuthService
|
||||
participant TokenProvider
|
||||
participant UserRepo
|
||||
participant DB
|
||||
|
||||
Client->>Router: POST /api/v1/auth/login
|
||||
Router->>AuthMiddleware: Extract credentials
|
||||
AuthMiddleware->>AuthService: Authenticate(email, password)
|
||||
AuthService->>UserRepo: FindByEmail(email)
|
||||
UserRepo->>DB: Query user
|
||||
DB-->>UserRepo: User data
|
||||
UserRepo-->>AuthService: User entity
|
||||
AuthService->>AuthService: Verify password
|
||||
AuthService->>TokenProvider: GenerateAccessToken(user)
|
||||
AuthService->>TokenProvider: GenerateRefreshToken(user)
|
||||
TokenProvider-->>AuthService: Tokens
|
||||
AuthService->>DB: Store refresh token
|
||||
AuthService-->>AuthMiddleware: Auth response
|
||||
AuthMiddleware-->>Router: Tokens
|
||||
Router-->>Client: JSON response with tokens
|
||||
```
|
||||
|
||||
### Authorization Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Request
|
||||
participant AuthzMiddleware
|
||||
participant Authorizer
|
||||
participant PermissionResolver
|
||||
participant Cache
|
||||
participant UserRepo
|
||||
participant RoleRepo
|
||||
participant DB
|
||||
|
||||
Request->>AuthzMiddleware: HTTP request + permission
|
||||
AuthzMiddleware->>Authorizer: Authorize(ctx, permission)
|
||||
Authorizer->>Authorizer: Extract user from context
|
||||
Authorizer->>PermissionResolver: HasPermission(user, permission)
|
||||
PermissionResolver->>Cache: Check cache
|
||||
Cache-->>PermissionResolver: Cache miss
|
||||
|
||||
PermissionResolver->>UserRepo: GetUserRoles(userID)
|
||||
UserRepo->>DB: Query user_roles
|
||||
DB-->>UserRepo: Role IDs
|
||||
UserRepo-->>PermissionResolver: Roles
|
||||
|
||||
PermissionResolver->>RoleRepo: GetRolePermissions(roleIDs)
|
||||
RoleRepo->>DB: Query role_permissions
|
||||
DB-->>RoleRepo: Permissions
|
||||
RoleRepo-->>PermissionResolver: Permission list
|
||||
|
||||
PermissionResolver->>PermissionResolver: Check if permission in list
|
||||
PermissionResolver->>Cache: Store in cache
|
||||
PermissionResolver-->>Authorizer: Has permission: true/false
|
||||
Authorizer-->>AuthzMiddleware: Authorized or error
|
||||
AuthzMiddleware-->>Request: Continue or 403
|
||||
```
|
||||
|
||||
### Event Publishing Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant ModuleService
|
||||
participant EventBus
|
||||
participant Kafka
|
||||
participant Subscriber1
|
||||
participant Subscriber2
|
||||
|
||||
ModuleService->>EventBus: Publish(topic, event)
|
||||
EventBus->>EventBus: Serialize event
|
||||
EventBus->>Kafka: Send to topic
|
||||
Kafka-->>EventBus: Acknowledged
|
||||
|
||||
Kafka->>Subscriber1: Deliver event
|
||||
Kafka->>Subscriber2: Deliver event
|
||||
|
||||
Subscriber1->>Subscriber1: Process event
|
||||
Subscriber2->>Subscriber2: Process event
|
||||
```
|
||||
|
||||
## Data Flow Patterns
|
||||
|
||||
### Request to Response Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Client[Client] -->|HTTP Request| LB[Load Balancer]
|
||||
LB -->|Route| Server1[Instance 1]
|
||||
LB -->|Route| Server2[Instance 2]
|
||||
|
||||
Server1 --> AuthMW[Auth Middleware]
|
||||
Server1 --> AuthzMW[Authz Middleware]
|
||||
Server1 --> RateLimit[Rate Limiter]
|
||||
Server1 --> Handler[Request Handler]
|
||||
Server1 --> Service[Domain Service]
|
||||
Server1 --> Cache[Cache Check]
|
||||
Server1 --> Repo[Repository]
|
||||
Server1 --> DB[(Database)]
|
||||
|
||||
Service --> EventBus[Event Bus]
|
||||
Service --> Audit[Audit Log]
|
||||
|
||||
Handler -->|Response| Server1
|
||||
Server1 -->|HTTP Response| LB
|
||||
LB -->|Response| Client
|
||||
|
||||
style Server1 fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
||||
style Service fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
### Caching Flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Request[Service Request] --> CacheCheck{Cache Hit?}
|
||||
CacheCheck -->|Yes| CacheGet[Get from Cache]
|
||||
CacheCheck -->|No| DBQuery[Query Database]
|
||||
DBQuery --> DBResponse[Database Response]
|
||||
DBResponse --> CacheStore[Store in Cache]
|
||||
CacheStore --> Return[Return Data]
|
||||
CacheGet --> Return
|
||||
|
||||
style CacheCheck fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
||||
style CacheGet fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
||||
style DBQuery fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
Complete dependency graph showing all components and their relationships.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Application Entry"
|
||||
Main[Main Application]
|
||||
end
|
||||
|
||||
subgraph "Core Kernel"
|
||||
Config[Config]
|
||||
Logger[Logger]
|
||||
DI[DI Container]
|
||||
ModuleLoader[Module Loader]
|
||||
end
|
||||
|
||||
subgraph "Security"
|
||||
Auth[Auth]
|
||||
Authz[Authz]
|
||||
Identity[Identity]
|
||||
Audit[Audit]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure"
|
||||
DB[Database]
|
||||
Cache[Cache]
|
||||
EventBus[Event Bus]
|
||||
Scheduler[Scheduler]
|
||||
BlobStore[Blob Store]
|
||||
Notifier[Notifier]
|
||||
end
|
||||
|
||||
subgraph "Observability"
|
||||
Metrics[Metrics]
|
||||
Health[Health]
|
||||
Tracer[Tracer]
|
||||
ErrorBus[Error Bus]
|
||||
end
|
||||
|
||||
subgraph "Module"
|
||||
ModuleHandler[Module Handler]
|
||||
ModuleService[Module Service]
|
||||
ModuleRepo[Module Repo]
|
||||
end
|
||||
|
||||
Main --> Config
|
||||
Main --> Logger
|
||||
Main --> DI
|
||||
Main --> ModuleLoader
|
||||
|
||||
Config --> Logger
|
||||
Config --> DI
|
||||
|
||||
DI --> Auth
|
||||
DI --> Authz
|
||||
DI --> Identity
|
||||
DI --> Audit
|
||||
DI --> DB
|
||||
DI --> Cache
|
||||
DI --> EventBus
|
||||
DI --> Scheduler
|
||||
DI --> BlobStore
|
||||
DI --> Notifier
|
||||
DI --> Metrics
|
||||
DI --> Health
|
||||
DI --> Tracer
|
||||
DI --> ErrorBus
|
||||
|
||||
Auth --> Identity
|
||||
Auth --> DB
|
||||
Authz --> Identity
|
||||
Authz --> Cache
|
||||
Authz --> Audit
|
||||
Audit --> DB
|
||||
Audit --> Logger
|
||||
|
||||
ModuleLoader --> DI
|
||||
ModuleHandler --> Auth
|
||||
ModuleHandler --> Authz
|
||||
ModuleService --> ModuleRepo
|
||||
ModuleService --> EventBus
|
||||
ModuleService --> Cache
|
||||
ModuleService --> Audit
|
||||
ModuleRepo --> DB
|
||||
|
||||
Scheduler --> Cache
|
||||
Notifier --> EventBus
|
||||
|
||||
ErrorBus --> Logger
|
||||
ErrorBus --> Sentry
|
||||
|
||||
DB --> Tracer
|
||||
Cache --> Tracer
|
||||
EventBus --> Tracer
|
||||
|
||||
style Main fill:#4a90e2,stroke:#2e5c8a,stroke-width:4px,color:#fff
|
||||
style DI fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
|
||||
style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
## Component Interaction Matrix
|
||||
|
||||
| Component | Depends On | Used By |
|
||||
|-----------|-----------|---------|
|
||||
| Config | None | All components |
|
||||
| Logger | Config | All components |
|
||||
| DI Container | Config, Logger | All components |
|
||||
| Auth Service | Identity, DB | Auth Middleware, Modules |
|
||||
| Authz Service | Identity, Cache, Audit | Authz Middleware, Modules |
|
||||
| Identity Service | DB, Cache, Notifier | Auth, Authz, Modules |
|
||||
| Database Client | Config, Logger, Tracer | All repositories |
|
||||
| Cache Client | Config, Logger | Authz, Scheduler, Modules |
|
||||
| Event Bus | Config, Logger, Tracer | Modules, Notifier |
|
||||
| Scheduler | Cache, Logger | Modules |
|
||||
| Error Bus | Logger | All components (via panic recovery) |
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Module Service Integration
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Module Layer"
|
||||
Handler[HTTP Handler]
|
||||
Service[Domain Service]
|
||||
Repo[Repository]
|
||||
end
|
||||
|
||||
subgraph "Core Services"
|
||||
Auth[Auth Service]
|
||||
Authz[Authz Service]
|
||||
EventBus[Event Bus]
|
||||
Cache[Cache]
|
||||
Audit[Audit]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure"
|
||||
DB[(Database)]
|
||||
Redis[(Redis)]
|
||||
Kafka[Kafka]
|
||||
end
|
||||
|
||||
Handler --> Auth
|
||||
Handler --> Authz
|
||||
Handler --> Service
|
||||
|
||||
Service --> Repo
|
||||
Service --> EventBus
|
||||
Service --> Cache
|
||||
Service --> Audit
|
||||
|
||||
Repo --> DB
|
||||
Cache --> Redis
|
||||
EventBus --> Kafka
|
||||
Audit --> DB
|
||||
|
||||
style Service fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
||||
style Auth fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
|
||||
style DB fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
|
||||
```
|
||||
|
||||
### Cross-Module Communication
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Module A"
|
||||
AService[Service A]
|
||||
end
|
||||
|
||||
subgraph "Module B"
|
||||
BService[Service B]
|
||||
end
|
||||
|
||||
subgraph "Core Services"
|
||||
EventBus[Event Bus]
|
||||
Authz[Authz Service]
|
||||
Cache[Cache]
|
||||
end
|
||||
|
||||
AService -->|Direct Call| Authz
|
||||
AService -->|Publish Event| EventBus
|
||||
EventBus -->|Subscribe| BService
|
||||
AService -->|Cache Access| Cache
|
||||
BService -->|Cache Access| Cache
|
||||
|
||||
style AService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
||||
style BService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
|
||||
style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [System Architecture](./architecture.md) - Overall system architecture
|
||||
- [Module Architecture](./architecture-modules.md) - Module design and integration
|
||||
- [Module Requirements](./module-requirements.md) - Detailed module requirements
|
||||
|
||||
Reference in New Issue
Block a user