agent-swarm-docs/architecture.md

🧠 Cortex — Agent Swarm Architecture

graph TB
    subgraph MacMini["🖥️ Mac Mini (24/7)"]
        Cortex["🧠 Cortex<br/>OpenClaw Orchestrator"]
        Cortex --> Codex1["Codex Agent 1"]
        Cortex --> Codex2["Codex Agent 2"]
        Cortex --> Codex3["Codex Agent 3"]
        Cortex --> Claude1["Claude Code 1"]
        Cortex --> Gemini1["Gemini Agent 1"]
    end

    subgraph VPS["🖧 VPS Dokploy (51.75.248.225)"]
        Gitea["Gitea<br/>Source of Truth"]
        Runner["Act Runner<br/>Docker CI"]
        Gitea --> Runner
        Runner --> Lint["Lint"]
        Runner --> TypeCheck["Typecheck"]
        Runner --> Tests["Tests"]
        Runner --> E2E["E2E"]
        Runner --> AIReview["AI Review x3"]
        Gitea -->|Push Mirror| GitHub["GitHub<br/>(mirror)"]
        Gitea -->|Webhook| Cortex
    end

    Codex1 -->|git push| Gitea
    Codex2 -->|git push| Gitea
    Codex3 -->|git push| Gitea
    Claude1 -->|git push| Gitea
    Gemini1 -->|git push| Gitea

    Ayoub["👤 Ayoub<br/>Telegram/WhatsApp"] <-->|commands & notifications| Cortex

    style MacMini fill:#1a1a2e,color:#fff
    style VPS fill:#16213e,color:#fff
    style Cortex fill:#e94560,color:#fff
    style Gitea fill:#85c88a,color:#000
    style GitHub fill:#333,color:#fff
    style Ayoub fill:#f5a623,color:#000

Flow

1. Ayoub (Telegram/WhatsApp) → Cortex → spawn agent on Mac Mini/VPS
2. Agent codes in git worktree → git push to Gitea (VPS)
3. Gitea triggers CI (Act Runner on VPS)
4. Gitea push mirror → GitHub (auto-sync)
5. CI completes → webhook → Cortex
6. Cortex → notification to Ayoub

Agent Routing

Task	Agent
Backend / billing / auth / API	Codex
Frontend / React / styling	Claude Code
Strapi / CMS	Claude Code
Design / prototyping	Gemini
Migrations / refactors	Codex
Bugfix Sentry	Codex