goplt/docs/content/architecture/operational-scenarios.md

# Operational Scenarios

## Purpose

This document describes common operational scenarios in the Go Platform, focusing on how different components interact to accomplish specific tasks.

## Overview

Operational scenarios illustrate how the platform handles common use cases such as user authentication, authorization checks, event processing, and background job execution. Each scenario shows the complete flow from initiation to completion.

## Key Concepts

- **Scenario**: A specific operational use case
- **Flow**: Sequence of interactions to accomplish the scenario
- **Components**: Services and modules involved in the scenario
- **State Changes**: How system state changes during the scenario

## Authentication and Authorization Flows

### User Authentication Flow

Complete flow of user logging in and receiving authentication tokens.

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant AuthService
    participant IdentityService
    participant DB
    participant TokenProvider
    participant AuditService
    
    User->>Client: Enter credentials
    Client->>AuthService: POST /api/v1/auth/login
    AuthService->>AuthService: Validate request format
    AuthService->>IdentityService: Verify credentials
    IdentityService->>DB: Query user by email
    DB-->>IdentityService: User data
    IdentityService->>IdentityService: Verify password hash
    IdentityService-->>AuthService: Credentials valid
    
    AuthService->>TokenProvider: Generate access token
    TokenProvider->>TokenProvider: Create JWT claims
    TokenProvider-->>AuthService: Access token
    
    AuthService->>TokenProvider: Generate refresh token
    TokenProvider->>DB: Store refresh token hash
    DB-->>TokenProvider: Token stored
    TokenProvider-->>AuthService: Refresh token
    
    AuthService->>AuditService: Log login
    AuditService->>DB: Store audit log
    AuditService-->>AuthService: Logged
    
    AuthService-->>Client: Access + Refresh tokens
    Client-->>User: Authentication successful
```

### Authorization Check Flow

How the system checks if a user has permission to perform an action.

```mermaid
sequenceDiagram
    participant Handler
    participant AuthzMiddleware
    participant AuthzService
    participant PermissionResolver
    participant Cache
    participant DB
    participant IdentityService
    
    Handler->>AuthzMiddleware: Check permission
    AuthzMiddleware->>AuthzMiddleware: Extract user from context
    AuthzMiddleware->>AuthzService: Authorize(user, permission)
    
    AuthzService->>Cache: Check permission cache
    Cache-->>AuthzService: Cache miss
    
    AuthzService->>PermissionResolver: Resolve permissions
    PermissionResolver->>IdentityService: Get user roles
    IdentityService->>DB: Query user roles
    DB-->>IdentityService: User roles
    IdentityService-->>PermissionResolver: Roles list
    
    PermissionResolver->>DB: Query role permissions
    DB-->>PermissionResolver: Permissions
    PermissionResolver->>PermissionResolver: Aggregate permissions
    PermissionResolver-->>AuthzService: User permissions
    
    AuthzService->>AuthzService: Check permission in list
    AuthzService->>Cache: Store in cache
    AuthzService-->>AuthzMiddleware: Authorized/Unauthorized
    
    alt Authorized
        AuthzMiddleware-->>Handler: Continue
    else Unauthorized
        AuthzMiddleware-->>Handler: 403 Forbidden
    end
```

### Permission Resolution Flow

How user permissions are resolved from roles and cached for performance.

```mermaid
graph TD
    Start[Permission Check] --> Cache{Cache Hit?}
    Cache -->|Yes| Return[Return Cached Permissions]
    Cache -->|No| GetRoles[Get User Roles]
    
    GetRoles --> DB1[(Database)]
    DB1 --> Roles[User Roles]
    
    Roles --> GetPermissions[Get Role Permissions]
    GetPermissions --> DB2[(Database)]
    DB2 --> Permissions[Role Permissions]
    
    Permissions --> Aggregate[Aggregate Permissions]
    Aggregate --> StoreCache[Store in Cache]
    StoreCache --> Return
    
    Return --> Check[Check Permission]
    Check -->|Has Permission| Allow[Allow Access]
    Check -->|No Permission| Deny[Deny Access]
    
    style Cache fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
    style Aggregate fill:#50c878,stroke:#2e7d4e,stroke-width:2px,color:#fff
```

## Data Access Patterns

### Cache-Aside Pattern

How data is accessed with caching to improve performance.

```mermaid
sequenceDiagram
    participant Service
    participant Cache
    participant Repository
    participant DB
    
    Service->>Cache: Get(key)
    Cache-->>Service: Cache miss
    
    Service->>Repository: Find by ID
    Repository->>DB: Query database
    DB-->>Repository: Data
    Repository-->>Service: Domain entity
    
    Service->>Cache: Set(key, entity)
    Cache-->>Service: Cached
    
    Service-->>Service: Return entity
    
    Note over Service,Cache: Next request will hit cache
```

### Write-Through Cache Pattern

How data writes are synchronized with cache.

```mermaid
sequenceDiagram
    participant Service
    participant Cache
    participant Repository
    participant DB
    
    Service->>Repository: Save entity
    Repository->>DB: Insert/Update
    DB-->>Repository: Success
    
    Repository->>Cache: Invalidate(key)
    Cache->>Cache: Remove from cache
    Cache-->>Repository: Invalidated
    
    Repository-->>Service: Entity saved
    
    Note over Service,Cache: Cache invalidated on write
```

## Event Processing Scenarios

### Event Publishing and Consumption

How events are published and consumed across services.

```mermaid
sequenceDiagram
    participant Publisher
    participant EventBus
    participant Kafka
    participant Subscriber1
    participant Subscriber2
    
    Publisher->>Publisher: Business event occurs
    Publisher->>EventBus: Publish(event)
    EventBus->>EventBus: Serialize event
    EventBus->>EventBus: Add metadata
    EventBus->>Kafka: Send to topic
    Kafka-->>EventBus: Acknowledged
    EventBus-->>Publisher: Event published
    
    Kafka->>Subscriber1: Deliver event
    Subscriber1->>Subscriber1: Deserialize event
    Subscriber1->>Subscriber1: Process event
    Subscriber1->>Subscriber1: Update state
    Subscriber1-->>Kafka: Acknowledge
    
    Kafka->>Subscriber2: Deliver event
    Subscriber2->>Subscriber2: Deserialize event
    Subscriber2->>Subscriber2: Process event
    Subscriber2->>Subscriber2: Update state
    Subscriber2-->>Kafka: Acknowledge
```

### Event-Driven Workflow

How multiple services coordinate through events.

```mermaid
graph LR
    A[Service A] -->|Publish Event A| EventBus[Event Bus]
    EventBus -->|Subscribe| B[Service B]
    EventBus -->|Subscribe| C[Service C]
    
    B -->|Publish Event B| EventBus
    C -->|Publish Event C| EventBus
    
    EventBus -->|Subscribe| D[Service D]
    
    style EventBus fill:#4a90e2,stroke:#2e5c8a,stroke-width:2px,color:#fff
```

## Background Processing Scenarios

### Background Job Scheduling

How background jobs are scheduled and executed.

```mermaid
sequenceDiagram
    participant Scheduler
    participant JobQueue
    participant Worker
    participant Service
    participant DB
    participant EventBus
    
    Scheduler->>Scheduler: Cron trigger
    Scheduler->>JobQueue: Enqueue job
    JobQueue->>JobQueue: Store job definition
    JobQueue-->>Scheduler: Job enqueued
    
    Worker->>JobQueue: Poll for jobs
    JobQueue-->>Worker: Job definition
    
    Worker->>Worker: Lock job
    Worker->>Service: Execute job
    Service->>DB: Update data
    Service->>EventBus: Publish events
    Service-->>Worker: Job complete
    
    Worker->>JobQueue: Mark complete
    JobQueue->>JobQueue: Remove job
    
    alt Job fails
        Worker->>JobQueue: Mark failed
        JobQueue->>JobQueue: Schedule retry
    end
```

### Job Retry Flow

How failed jobs are retried with exponential backoff.

```mermaid
stateDiagram-v2
    [*] --> Pending: Job created
    Pending --> Running: Worker picks up
    Running --> Success: Job completes
    Running --> Failed: Job fails
    
    Failed --> RetryScheduled: Schedule retry
    RetryScheduled --> Waiting: Wait (exponential backoff)
    Waiting --> Pending: Retry time reached
    
    Failed --> MaxRetries: Max retries reached
    MaxRetries --> DeadLetter: Move to dead letter
    
    Success --> [*]
    DeadLetter --> [*]
```

## Configuration Management Scenarios

### Configuration Reload Flow

How configuration is reloaded without service restart.

```mermaid
sequenceDiagram
    participant Admin
    participant ConfigService
    participant ConfigManager
    participant Services
    participant SecretStore
    
    Admin->>ConfigService: Update configuration
    ConfigService->>SecretStore: Fetch secrets (if needed)
    SecretStore-->>ConfigService: Secrets
    
    ConfigService->>ConfigManager: Reload configuration
    ConfigManager->>ConfigManager: Validate configuration
    ConfigManager->>ConfigManager: Merge with defaults
    
    ConfigManager->>Services: Notify config change
    Services->>Services: Update configuration
    Services-->>ConfigManager: Config updated
    
    ConfigManager-->>ConfigService: Reload complete
    ConfigService-->>Admin: Configuration reloaded
```

## Audit Logging Flow

How all security-sensitive actions are logged.

```mermaid
sequenceDiagram
    participant Service
    participant AuditClient
    participant AuditService
    participant DB
    
    Service->>Service: Security-sensitive action
    Service->>AuditClient: Record audit log
    AuditClient->>AuditClient: Extract context
    AuditClient->>AuditClient: Build audit entry
    
    AuditClient->>AuditService: Store audit log
    AuditService->>AuditService: Validate audit entry
    AuditService->>DB: Insert audit log
    DB-->>AuditService: Log stored
    AuditService-->>AuditClient: Audit logged
    
    AuditClient-->>Service: Continue
    
    Note over Service,DB: Audit logs are immutable
```

## Database Migration Flow

How database migrations are executed during module initialization.

```mermaid
sequenceDiagram
    participant Main
    participant ModuleRegistry
    participant Module
    participant MigrationRunner
    participant DB
    
    Main->>ModuleRegistry: Get modules (dependency order)
    ModuleRegistry-->>Main: Ordered modules
    
    loop For each module
        Main->>Module: Get migrations
        Module-->>Main: Migration list
    end
    
    Main->>MigrationRunner: Run migrations
    MigrationRunner->>DB: Check migration table
    DB-->>MigrationRunner: Existing migrations
    
    loop For each pending migration
        MigrationRunner->>DB: Start transaction
        MigrationRunner->>DB: Execute migration
        DB-->>MigrationRunner: Migration complete
        MigrationRunner->>DB: Record migration
        MigrationRunner->>DB: Commit transaction
    end
    
    MigrationRunner-->>Main: Migrations complete
```

## Integration Points

This operational scenarios document integrates with:

- **[System Behavior Overview](system-behavior.md)**: How these scenarios fit into overall system behavior
- **[Service Orchestration](service-orchestration.md)**: How services coordinate in these scenarios
- **[Module Integration Patterns](module-integration-patterns.md)**: How modules participate in these scenarios
- **[Data Flow Patterns](data-flow-patterns.md)**: Detailed data flow in these scenarios

## Related Documentation

- [System Behavior Overview](system-behavior.md) - System-level behavior
- [Service Orchestration](service-orchestration.md) - Service coordination
- [Module Integration Patterns](module-integration-patterns.md) - Module integration
- [Data Flow Patterns](data-flow-patterns.md) - Data flow details
- [Architecture Overview](architecture.md) - System architecture