goplt/docs/content/architecture/component-relationships.md

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
• Module to Core Integration
• Service Interaction Patterns
• Data Flow Patterns
• Dependency Graph

Core Component Dependencies

The core kernel components have well-defined dependencies that form the foundation of the platform.

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 "Service Registry"
        Registry[Service Registry<br/>Consul]
    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 --> Metrics
    DI --> Health
    DI --> Tracer
    DI --> Registry
    
    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

Service to Service Integration

Feature services integrate with core services through service client interfaces. All communication uses gRPC (primary) or HTTP (fallback). Services discover each other via the service registry (Consul).

graph LR
    subgraph "Feature Service (e.g., Blog)"
        ModuleHandler[Module Handler]
        ModuleService[Module Service]
        ModuleRepo[Module Repository]
    end
    
    subgraph "Service Clients"
        AuthClient[Auth Service Client<br/>gRPC]
        AuthzClient[Authz Service Client<br/>gRPC]
        IdentityClient[Identity Service Client<br/>gRPC]
        AuditClient[Audit Service Client<br/>gRPC]
    end
    
    subgraph "Service Registry"
        Registry[Consul<br/>Service Discovery]
    end
    
    subgraph "Core Services"
        AuthService[Auth Service<br/>:8081]
        AuthzService[Authz Service<br/>:8083]
        IdentityService[Identity Service<br/>:8082]
        AuditService[Audit Service<br/>:8084]
        EventBusService[Event Bus<br/>Kafka]
        CacheService[Cache Service<br/>Redis]
    end
    
    subgraph "Infrastructure"
        DBClient[Database Client]
        CacheClient[Cache Client]
        QueueClient[Message Queue]
    end
    
    ModuleHandler --> ModuleService
    
    ModuleService -->|gRPC| AuthClient
    ModuleService -->|gRPC| AuthzClient
    ModuleService -->|gRPC| IdentityClient
    ModuleService -->|gRPC| AuditClient
    ModuleService --> ModuleRepo
    ModuleService --> EventBusService
    ModuleService --> CacheService
    
    AuthClient -->|Discover| Registry
    AuthzClient -->|Discover| Registry
    IdentityClient -->|Discover| Registry
    AuditClient -->|Discover| Registry
    
    Registry --> AuthService
    Registry --> AuthzService
    Registry --> IdentityService
    Registry --> AuditService
    
    AuthClient --> AuthService
    AuthzClient --> AuthzService
    IdentityClient --> IdentityService
    AuditClient --> AuditService
    
    ModuleRepo --> DBClient
    CacheService --> CacheClient
    EventBusService --> QueueClient
    
    style ModuleService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
    style Registry fill:#50c878,stroke:#2e7d4e,stroke-width:3px,color:#fff
    style AuthService fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
    style DBClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
    style AuthClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
    style AuthzClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
    style IdentityClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
    style AuditClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff

Service Interaction Patterns

Authentication Flow

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

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

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

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

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.

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 --> ModuleService
    ModuleService --> ModuleRepo
    ModuleService -->|gRPC| Auth
    ModuleService -->|gRPC| Authz
    ModuleService -->|gRPC| Identity
    ModuleService -->|gRPC| Audit
    ModuleService --> EventBus
    ModuleService --> Cache
    ModuleRepo --> DB
    
    Scheduler --> Cache
    Notifier --> EventBus
    
    ErrorBus --> Logger
    
    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

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-Service Communication

graph LR
    subgraph "Blog Service"
        BlogService[Blog Service]
    end
    
    subgraph "Analytics Service"
        AnalyticsService[Analytics Service]
    end
    
    subgraph "Service Clients"
        AuthzClient[Authz Service Client]
        IdentityClient[Identity Service Client]
    end
    
    subgraph "Core Services"
        EventBus[Event Bus<br/>Kafka]
        AuthzService[Authz Service<br/>:8083]
        IdentityService[Identity Service<br/>:8082]
        Cache[Cache<br/>Redis]
    end
    
    BlogService -->|gRPC| AuthzClient
    BlogService -->|gRPC| IdentityClient
    BlogService -->|Publish Event| EventBus
    EventBus -->|Subscribe| AnalyticsService
    BlogService -->|Cache Access| Cache
    AnalyticsService -->|Cache Access| Cache
    
    AuthzClient --> AuthzService
    IdentityClient --> IdentityService
    
    style BlogService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
    style AnalyticsService fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
    style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
    style AuthzClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
    style IdentityClient fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff

Next Steps

• System Architecture - Overall system architecture
• Module Architecture - Module design and integration
• Module Requirements - Detailed module requirements