How It Works

Understand how Orchestratia coordinates AI coding agents across your infrastructure.

System Architecture

Orchestratia is a hub-and-spoke system. The hub is the central coordination point — it runs the web dashboard, manages tasks, and relays communication. Agent daemons run on your development servers and manage the AI coding agents.

flowchart TD
    Internet["Internet"] --> Proxy["Secure Proxy (HTTPS)"]

    subgraph Hub ["Orchestratia Hub"]
        Proxy --> Backend["Hub Backend"]
        Proxy --> Frontend["Web Dashboard"]
        Backend --> DB["Database"]
        Backend --> Telegram["Telegram Bots"]
    end

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

    style Hub fill:#F0F9F7,stroke:#2A9D88
    style Internet fill:#F3F0EA,stroke:#B8AFA2
    style Proxy 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

Key principle: AI agents run on your servers, not on the hub. The hub only coordinates, streams output, and provides the dashboard.

Communication Channels

All communication between the hub and your servers is encrypted via HTTPS/WSS. There are two main channels:

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

    subgraph HubBack ["Hub Backend"]
        REST["REST API"]
        WS["WebSocket"]
        EB["Event Bus"]
    end

    Dashboard -->|"HTTPS"| REST
    Dashboard <-->|"WebSocket"| WS
    Agent -->|"HTTPS"| REST
    Agent <-->|"WebSocket"| WS
    TG <-->|"Events"| 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

Channel	Purpose	Latency
REST API	Task management, server registration, heartbeats, file transfers	Request/Response
WebSocket	Live terminal streaming, real-time task events, session control	Sub-100ms
Event Bus	Telegram notifications, cross-service event delivery	~500ms

The dashboard uses both REST (for CRUD) and WebSocket (for live updates and terminal streaming)
Agent daemons use REST for registration and task lifecycle, and WebSocket for live PTY streaming and real-time commands
Telegram bots subscribe to project events via the internal event bus

Task State Machine

Every task flows through a well-defined lifecycle. The diagram below shows all possible states and transitions:

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

Key Transitions

From	To	What Triggers It
Pending	Assigned	Manual assign from dashboard or auto-assignment
Assigned	Running	Agent starts working on the task
Assigned	Planning	Automatic when project requires plan approval
Planning	Plan Review	Agent submits execution plan for review
Plan Review	Running	Admin approves the plan
Plan Review	Planning	Admin requests plan revision with feedback
Running	Done	Agent completes the task successfully
Running	Failed	Agent reports failure
Running	Needs Human	Agent requests help from a human
Needs Human	Running	Admin responds to the intervention

Plan Mode: When enabled on a project, agents must submit an execution plan before they start coding. This prevents scope creep and ensures impact analysis happens before any changes are made.

Dependency & Contract System

Tasks can depend on other tasks. Orchestratia supports three types of dependencies:

Dependency Types

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

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

    subgraph related ["RELATED — informational link 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

Blocks: Task B cannot start until Task A completes. Pure ordering.
Input: Task B needs specific data from Task A's output (contracts). The hub automatically passes the data.
Related: Informational link. No blocking, no data exchange.

Contract Exchange

Contracts let tasks pass structured data to downstream tasks automatically:

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

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

    A->>Hub: Complete with contract data
    Note over A,Hub: 3. FULFILL

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

    Hub->>B: Deliver resolved inputs
    Note over Hub,B: 4. RESOLVE

    Note over B: Receives the data it needs<br/>to start working

When Task A completes, the hub validates its output against the declared contracts, resolves downstream dependencies, and automatically delivers the data to Task B.

Cascade Flow

When a task completes, the hub triggers a cascade that can unblock and start downstream tasks automatically:

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

    Check["1. CHECK CONTRACTS<br/>Validate output matches declared contracts"]
    Check --> Resolve

    Resolve["2. RESOLVE DEPENDENCIES<br/>Mark blocking/input deps as resolved"]
    Resolve --> Downstream

    Downstream["3. CHECK DOWNSTREAM<br/>Are all blockers resolved? Unblock waiting tasks"]
    Downstream --> AutoAssign

    AutoAssign["4. AUTO-ASSIGN<br/>Match unblocked tasks to best available server"]
    AutoAssign --> Broadcast

    Broadcast["5. BROADCAST<br/>Update dashboards, notify Telegram, log activity"]

    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

This means you can define a pipeline of 10+ tasks, and the hub will execute them in the right order, passing data between them, assigning each to the best available server — all automatically.

Capability Matching & Auto-Assignment

When a task needs to be assigned, the hub scores each available server based on how well it matches the task's requirements:

Hard requirements (must match or server is disqualified): target repository, required languages, required environments
Soft requirements (improve the score): matching tools, matching tags, preferred server, online status, available capacity

The highest-scoring server gets the task. If no server meets the hard requirements, the task stays pending until a suitable server comes online.

Auto-Assignment Triggers

Dependency resolution — when a task's last blocking dependency resolves, the hub automatically assigns the now-unblocked task
Server comes online — when an agent daemon reconnects, the hub checks for pending tasks it could handle

Security

Orchestratia uses multiple layers of security to protect your data and infrastructure:

flowchart TD
    L1["**NETWORK**<br/>TLS encryption on all connections<br/>HSTS enforced, database isolated"]
    L2["**AUTHENTICATION**<br/>Token-based auth for users<br/>API keys for agents<br/>OAuth with Google and GitHub"]
    L3["**AUTHORIZATION**<br/>Role-based access (owner/member/viewer)<br/>Project-scoped isolation<br/>One-time registration tokens"]
    L4["**DATA PROTECTION**<br/>Passwords hashed with modern algorithms<br/>Sensitive tokens encrypted at rest<br/>Full audit trail of all actions"]

    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

All connections are encrypted with TLS (HTTPS/WSS)
Users authenticate with email/password or OAuth (Google, GitHub)
Agents authenticate with unique API keys issued during registration
Projects enforce isolation — team members only see resources in their projects
Every action is logged to a comprehensive activity trail