Architecture & Data Model

flowchart TD
    Internet["Internet"] --> Nginx["Nginx :443"]

    subgraph Hub ["Orchestratia Hub"]
        Nginx --> Backend["FastAPI :8000"]
        Nginx --> Frontend["Next.js :3000"]
        Backend --> DB["PostgreSQL :5432"]
        Backend --> Telegram["Telegram Bots"]
    end

    Backend -.->|"REST + WS"| AD1["Agent Daemon"] --> AI1["Claude Code"]
    Backend -.->|"REST + WS"| AD2["Agent Daemon"] --> AI2["Gemini CLI"]
    Backend -.->|"REST + WS"| AD3["Agent Daemon"] --> AI3["Codex CLI"]

    style Hub fill:#F0F9F7,stroke:#2A9D88
    style Internet fill:#F3F0EA,stroke:#B8AFA2
    style Nginx fill:#2A9D88,stroke:#186B5D,color:#fff
    style Backend fill:#F0F9F7,stroke:#2A9D88
    style Frontend fill:#F0F9F7,stroke:#2A9D88
    style DB fill:#F0F9F7,stroke:#2A9D88
    style Telegram fill:#F0F9F7,stroke:#2A9D88
    style AD1 fill:#F0F9F7,stroke:#2A9D88
    style AD2 fill:#F0F9F7,stroke:#2A9D88
    style AD3 fill:#F0F9F7,stroke:#2A9D88
    style AI1 fill:#F3F0EA,stroke:#918A80
    style AI2 fill:#F3F0EA,stroke:#918A80
    style AI3 fill:#F3F0EA,stroke:#918A80

flowchart LR
    Dashboard["Dashboard<br/>(Browser)"]
    Agent["Agent<br/>Daemon"]
    TG["Telegram<br/>Bots"]

    subgraph HubBack ["Hub Backend (FastAPI)"]
        REST["REST API<br/>/api/v1/*"]
        WS["WebSocket<br/>/ws/*"]
        EB["Event Bus<br/>(pub/sub)"]
    end

    Dashboard -->|"REST HTTPS<br/>JWT (24h)"| REST
    Dashboard <-->|"WSS /ws/dashboard<br/>JWT first msg"| WS
    Agent -->|"REST HTTPS<br/>API Key header"| REST
    Agent <-->|"WSS /ws/server<br/>API Key first msg"| WS
    TG <-->|"Pub/Sub<br/>per project"| EB

    style HubBack fill:#F0F9F7,stroke:#2A9D88
    style Dashboard fill:#F3F0EA,stroke:#918A80
    style Agent fill:#F3F0EA,stroke:#918A80
    style TG fill:#F3F0EA,stroke:#918A80
    style REST fill:#F0F9F7,stroke:#2A9D88
    style WS fill:#2A9D88,stroke:#186B5D,color:#fff
    style EB fill:#F0F9F7,stroke:#2A9D88

erDiagram
    projects {
        uuid id PK
        string name
        string status
    }
    servers {
        uuid id PK
        string name
        string status
        jsonb repos
        jsonb capabilities
        uuid owner_id FK
    }
    tasks {
        uuid id PK
        string title
        string status
        string priority
        jsonb structured_spec
        uuid assigned_server_id FK
        jsonb result
    }
    sessions {
        uuid id PK
        uuid server_id FK
        uuid project_id FK
        uuid task_id FK
        string status
    }
    task_dependencies {
        uuid id PK
        uuid task_id FK
        uuid depends_on_task_id FK
        string dependency_type
        string contract_key
    }
    interventions {
        uuid id PK
        uuid task_id FK
        string status
    }
    activity_log {
        uuid id PK
        string event_type
        jsonb details
    }
    task_output {
        uuid id PK
        uuid task_id FK
        text content
    }
    task_notes {
        bigint id PK
        uuid task_id FK
        string author
        boolean urgent
    }
    admin_users {
        uuid id PK
        string email
        string role
    }
    telegram_bots {
        uuid id PK
        uuid project_id FK
    }
    registration_tokens {
        uuid id PK
        uuid project_id FK
    }

    projects ||--o{ servers : "registers"
    projects ||--o{ sessions : "contains"
    projects ||--o{ telegram_bots : "configures"
    projects ||--o{ registration_tokens : "generates"
    servers ||--o{ sessions : "runs"
    tasks ||--o{ sessions : "uses"
    tasks ||--o{ task_output : "produces"
    tasks ||--o{ task_notes : "has notes"
    tasks ||--o{ interventions : "triggers"
    tasks ||--o{ activity_log : "logs"
    tasks ||--o{ task_dependencies : "has"
    task_dependencies }o--|| tasks : "depends on"

stateDiagram-v2
    [*] --> Pending: created
    Pending --> Assigned: assign
    Assigned --> Running: start
    Assigned --> Planning: plan mode

    Planning --> PlanReview: submit plan
    Planning --> Failed: fail

    PlanReview --> Running: approve plan
    PlanReview --> Planning: revise plan

    Running --> Review: submit
    Running --> Done: complete
    Running --> Failed: fail
    Running --> NeedsHuman: help

    NeedsHuman --> Running: respond

    Review --> Done: approve
    Review --> Running: revise

    Done --> [*]: cascade

    note right of Done
        Resolve deps
        Unblock downstream
        Auto-assign next
    end note

flowchart TD
    subgraph blocks ["BLOCKS — B waits for A"]
        direction LR
        A1["Task A"] ==>|"blocks"| B1["Task B"]
    end

    subgraph input ["INPUT — B needs A's contract data"]
        direction LR
        A2["Task A"] -->|"input"| B2["Task B"]
    end

    subgraph related ["RELATED — informational only"]
        direction LR
        A3["Task A"] -.-|"related"| B3["Task B"]
    end

    blocks ~~~ input
    input ~~~ related

    style blocks fill:#F0F9F7,stroke:#2A9D88
    style input fill:#FAF8F5,stroke:#E8E3DA
    style related fill:#F3F0EA,stroke:#B8AFA2
    style A1 fill:#2A9D88,stroke:#186B5D,color:#fff
    style B1 fill:#F0F9F7,stroke:#2A9D88
    style A2 fill:#2A9D88,stroke:#186B5D,color:#fff
    style B2 fill:#F0F9F7,stroke:#2A9D88
    style A3 fill:#F3F0EA,stroke:#918A80
    style B3 fill:#F3F0EA,stroke:#918A80

sequenceDiagram
    participant A as Task A
    participant Hub as Hub
    participant B as Task B

    Note over A: 1. DECLARE contracts<br/>in structured_spec
    Note over B: 2. DEPEND on A<br/>type: input, key: api_schema

    A->>Hub: Complete with result.contracts.api_schema
    Note over A,Hub: 3. FULFILL

    Hub->>Hub: Validate → resolve deps → unblock → auto-assign

    Hub->>B: Push resolved_inputs.api_schema
    Note over Hub,B: 4. RESOLVE

    Note over B: Receives: resolved_inputs.api_schema<br/>{endpoints: [], schemas: {}}

flowchart TD
    Start(["Task A completes with result"]) --> Check

    Check["1. CHECK CONTRACTS<br/>Compare expected vs actual contracts"]
    Check --> Resolve

    Resolve["2. RESOLVE DEPENDENCIES<br/>blocks/input/related → mark resolved"]
    Resolve --> Downstream

    Downstream["3. CHECK DOWNSTREAM<br/>All blocking deps resolved? → UNBLOCK"]
    Downstream --> AutoAssign

    AutoAssign["4. AUTO-ASSIGN<br/>Score servers → pick best → assign via WS"]
    AutoAssign --> Broadcast

    Broadcast["5. BROADCAST<br/>WS → dashboards, Event Bus → Telegram, Log → DB"]

    style Start fill:#2A9D88,stroke:#186B5D,color:#fff
    style Check fill:#F0F9F7,stroke:#2A9D88
    style Resolve fill:#F0F9F7,stroke:#2A9D88
    style Downstream fill:#F0F9F7,stroke:#2A9D88
    style AutoAssign fill:#F0F9F7,stroke:#2A9D88
    style Broadcast fill:#FAF8F5,stroke:#E8E3DA

flowchart TD
    L1["**NETWORK**<br/>TLS + HSTS, ports 80/443 only<br/>PostgreSQL on internal network"]
    L2["**AUTHENTICATION**<br/>JWT (24h) + Argon2id for admins<br/>API keys (SHA-256) for agents<br/>WS auth in first message"]
    L3["**AUTHORIZATION**<br/>Agents scoped to own tasks<br/>One-time registration tokens<br/>Admin roles: admin / viewer"]
    L4["**INFRASTRUCTURE**<br/>SSH key-only, Docker non-root<br/>Secrets in .env, not in git"]

    L1 --> L2 --> L3 --> L4

    style L1 fill:#F0F9F7,stroke:#2A9D88
    style L2 fill:#F0F9F7,stroke:#2A9D88
    style L3 fill:#FAF8F5,stroke:#E8E3DA
    style L4 fill:#F3F0EA,stroke:#B8AFA2

flowchart TD
    subgraph Server ["Single Server (4 vCPU, 8GB RAM)"]
        Nginx["Nginx :443 — TLS + WS upgrade"]
        Backend["FastAPI Backend :8000"]
        Frontend["Next.js Frontend :3000"]
        Postgres["PostgreSQL :5432 (internal only)"]

        Nginx -->|"/api/*, /ws/*"| Backend
        Nginx -->|"/*"| Frontend
        Backend --> Postgres
    end

    style Server fill:#FAF8F5,stroke:#E8E3DA
    style Nginx fill:#2A9D88,stroke:#186B5D,color:#fff
    style Backend fill:#F0F9F7,stroke:#2A9D88
    style Frontend fill:#F0F9F7,stroke:#2A9D88
    style Postgres fill:#F3F0EA,stroke:#918A80