# 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