diff --git a/architecture.md b/architecture.md
new file mode 100644
index 0000000..c706cec
--- /dev/null
+++ b/architecture.md
@@ -0,0 +1,59 @@
+# 🧠 Cortex — Agent Swarm Architecture
+
+```mermaid
+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 |