Architecture¶

Orion follows a microservices architecture with an event-driven communication model. A Go gateway acts as the single entry point, handling OAuth authentication and JWT validation before routing HTTP requests to seven Python FastAPI services that communicate through Redis pub/sub.

System Layers¶

graph LR
    subgraph Clients["Client Layer"]
        CLI["Python CLI"]
        Dash["Next.js Dashboard"]
        WS["WebSocket Clients"]
    end

    subgraph Edge["Edge Layer"]
        GW["Go Gateway\n:8000"]
    end

    subgraph App["Application Layer"]
        SC["Scout"]
        DR["Director"]
        MD["Media"]
        ED["Editor"]
        PL["Pulse"]
        PB["Publisher"]
        ID["Identity"]
    end

    subgraph Infra["Infrastructure Layer"]
        PG[("PostgreSQL")]
        RD[("Redis")]
        MV[("Milvus")]
        OL["Ollama"]
        CU["ComfyUI"]
    end

    Clients --> Edge
    Edge --> App
    App --> Infra

Design Principles¶

Communication Model¶

• External to Platform -- All traffic enters through the Go gateway on port 8000
• Service to Service -- Redis pub/sub events (never direct HTTP between services)
• Service to Data -- Direct connections to PostgreSQL, Redis, and Milvus
• Real-time Updates -- WebSocket hub in the gateway subscribes to Redis channels and delivers per-user targeted notifications

Notification System¶

Domain events are automatically converted into per-user notifications. The notification module lives inside the Identity service (no new service required) and follows a two-hop real-time delivery path:

Domain Event (e.g. orion.content.published)
    ↓ Redis pub/sub
Identity Service: notification_consumer
    ↓ creates Notification row, publishes to orion.notification.created
Gateway: notification_relay.go
    ↓ per-user WebSocket push
Dashboard / CLI

Six event types are mapped to notifications: trend.detected, content.published, content.rejected, media.failed, pipeline.stage_changed, and content.created. Users can configure per-type preferences (enabled/disabled, real-time push on/off).

See Notifications for full API reference and architecture details.

Authentication¶

The gateway implements DB-backed multi-user auth with OAuth (GitHub/Google), short-lived JWT access tokens, and refresh token rotation:

sequenceDiagram
    participant Client
    participant Gateway
    participant Identity
    participant Service

    Client->>Gateway: POST /api/v1/auth/login
    Gateway->>Identity: Validate credentials
    Identity->>Gateway: User + refresh token
    Gateway->>Client: JWT (15-min) + refresh token (30-day)

    Client->>Gateway: API request + Bearer JWT
    Gateway->>Gateway: Validate JWT
    Gateway->>Service: Proxy + X-User-ID/Role/Email headers
    Service->>Client: Response (user-scoped data)

See Security for full details on OAuth flows, token rotation, and theft detection.

Service Responsibilities¶

Further Reading¶