12 KiB
12 KiB
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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: How these scenarios fit into overall system behavior
- Service Orchestration: How services coordinate in these scenarios
- Module Integration Patterns: How modules participate in these scenarios
- Data Flow Patterns: Detailed data flow in these scenarios
Related Documentation
- System Behavior Overview - System-level behavior
- Service Orchestration - Service coordination
- Module Integration Patterns - Module integration
- Data Flow Patterns - Data flow details
- Architecture Overview - System architecture