> ## Documentation Index > Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt > Use this file to discover all available pages before exploring further. # Architecture > Zeus System Architecture — Two-tier Backend, Multi-client, Communication Protocols & Data Flow Zeus adopts a **two-tier backend** architecture: the **Web API (Next.js)** serves as the central gateway handling user management, database operations, and request forwarding for all clients; the **AI Backend (FastAPI)** focuses exclusively on AI Agent orchestration, tool execution, and node communication. ## Overview ```mermaid theme={null} graph TB subgraph Clients["Clients"] web["Web App
(Next.js)"] desktop["Desktop App
(Electron)"] ios["iOS App"] android["Android App"] ext["Browser Extension"] feishu["Feishu Bot"] end subgraph WebAPI["Web API (Next.js)"] auth["Authentication
Better Auth + JWT"] api_routes["API Routes
/api/sessions, /api/tools, /api/credits, ..."] db_layer["Database Layer
Drizzle ORM (Service → Model → Schema)"] storage_layer["Storage Layer
Supabase Storage / S3"] forward["Agent Forwarding
/api/agent/invoke → AI Backend"] end subgraph AIBackend["AI Backend (FastAPI)"] agent_api["Agent API
/api/agent/invoke, /api/agent/resume"] gateway["WebSocket Gateway
/ws/extension, /ws/desktop, /ws/web"] service["Agent Service
AgentService, RAGService"] tools["Tool System
Built-in, MCP, OAuth, Connector"] end subgraph Infra["Infrastructure"] pg["PostgreSQL
App DB + pgvector + Checkpointer"] redis["Redis
Cache + Result Backend"] rabbitmq["RabbitMQ
Message Queue"] s3["Supabase Storage / S3 (MinIO)
Workspace Files"] llm["LLM Provider
OpenAI / Custom"] sandbox["Sandbox
E2B / OpenSandbox / Daytona"] end web -->|"HTTP"| api_routes desktop -->|"HTTP"| api_routes ios -->|"HTTP"| api_routes android -->|"HTTP"| api_routes feishu -->|"Webhook"| api_routes ext -->|"WebSocket"| gateway desktop -->|"WebSocket"| gateway api_routes --> db_layer api_routes --> storage_layer forward -->|"HTTP SSE"| agent_api db_layer --> pg storage_layer --> s3 api_routes --> redis agent_api --> service gateway --> service service --> tools service --> pg service --> redis service --> rabbitmq tools --> llm tools --> sandbox tools -->|"JSON-RPC 2.0"| gateway ``` * **Web API** is the single entry point for all clients — it handles auth, user data, session/message persistence, credits, tool configuration, and more * **AI Backend** receives forwarded agent requests from Web API and executes the Agent loop (LLM reasoning + tool calls) * **Extension / Desktop nodes** maintain a direct WebSocket connection to AI Backend's Gateway for real-time tool execution (browser automation, desktop control) * Each user has an independent **cloud workspace** (Supabase Storage / S3) and **session state** (PostgreSQL Checkpointer) *** ## Two-Tier Backend ### Web API (Next.js) — Gateway & Data Layer The Web API is a Next.js application that serves as the **central API gateway** for all clients. It owns the database and handles all non-AI concerns: | Responsibility | Details | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | | **Authentication** | Better Auth (OAuth, email/password, SSO), JWT issuance & verification | | **User Management** | User profiles, avatars, settings, agent preferences | | **Database** | PostgreSQL via Drizzle ORM — sessions, messages, tools, skills, knowledge bases, projects, credits, showcase | | **Storage** | Supabase Storage / S3 (MinIO) — workspace files, skill files, zeus config | | **Credit System** | Usage metering — check & deduct credits before forwarding agent calls | | **Tool Configuration** | CRUD for user tool settings (MCP servers, OAuth tokens, etc.) | | **Skill Management** | Skill CRUD, file upload/download, resource content prefetching | | **Knowledge Base** | KB metadata CRUD, document upload, chunk preview | | **Session Management** | Create/list/delete sessions, message persistence, event tracking | | **Agent Forwarding** | Assemble context (LLM config, tools, skills, env vars) and forward to AI Backend via HTTP SSE | **Key API routes (93 total):** | Route Group | Examples | Description | | ------------------------ | -------------------------------------- | ----------------------------- | | `/api/auth/*` | login, register, JWT, SSO, device-code | Authentication | | `/api/sessions/*` | CRUD, messages, events, checkpoints | Session & message management | | `/api/tools/*` | CRUD, MCP validation | Tool configuration | | `/api/skills/*` | CRUD, files, toggle, import | Skill management | | `/api/knowledge-base/*` | CRUD, documents, search, upload | Knowledge base | | `/api/projects/*` | CRUD, resources, sessions | Project management | | `/api/credits/*` | balance, transactions | Credit system | | `/api/agent/invoke` | POST → forward to AI Backend | Agent invocation (forwarding) | | `/api/agent/resume` | POST → forward to AI Backend | HITL resume (forwarding) | | `/api/config/*` | LLM, embedding, sandbox | User configuration | | `/api/memory/*` | CRUD, search, profile | Memory management | | `/api/scheduled-tasks/*` | CRUD, callbacks | Scheduled task management | | `/api/deploy/*` | deploy, restart-dev | Deployment | | `/api/storage/*` | files, URLs | File storage | ### AI Backend (FastAPI) — Agent Execution Engine The AI Backend is a FastAPI service dedicated to **AI Agent orchestration**. It receives forwarded requests from the Web API and handles all AI-related operations. The Agent Runtime is the **core** of the AI Backend — the other modules provide supporting infrastructure around it: ``` AI Backend (FastAPI) ├── Agent Runtime (Core) │ ├── AgentService / BaseService — invoke/resume entry, context init │ ├── DeepAgents Framework — LangGraph-based Agent loop │ ├── Tool System — Built-in, MCP, OAuth, Connector (4 layers) │ ├── Prompt Assembly — CORE / SOUL / TOOLS / WORKFLOW / MEMORY + dynamic injection │ ├── Session & Checkpointer — state persistence, isolation, HITL recovery │ └── HITL — human approval before sensitive tool execution ├── WebSocket Gateway — real-time communication with Extension / Desktop nodes ├── RAG Service — knowledge base retrieval (vector + BM25 hybrid search) ├── Sandbox — code execution environments (E2B / OpenSandbox / Daytona) ├── Scheduler — scheduled task execution (TaskIQ + RabbitMQ) └── Channels — Feishu and other channel integrations ``` | Responsibility | Details | | --------------------- | --------------------------------------------------------------------------------------------------------- | | **Agent Runtime** | Core Agent loop — LLM reasoning, tool planning, multi-step execution, prompt assembly, session management | | **WebSocket Gateway** | Real-time bidirectional communication with Extension/Desktop nodes | | **RAG Service** | Knowledge base retrieval (vector + BM25 hybrid search) | | **Sandbox** | Code execution environment management (E2B / OpenSandbox / Daytona) | | **Scheduler** | Task scheduling & async execution (via TaskIQ + RabbitMQ) | | **Channels** | Feishu bot and other channel integrations | **AI Backend API routes:** | Route | Description | Protocol | | ----------------------- | ----------------------------- | ---------------------- | | `/api/agent/invoke` | Agent conversation invocation | HTTP POST → SSE Stream | | `/api/agent/resume` | HITL resume execution | HTTP POST → SSE Stream | | `/api/knowledge-base/*` | Knowledge base RAG operations | HTTP REST | | `/api/node/*` | Node device queries | HTTP REST | | `/api/scheduled-task/*` | Scheduled task management | HTTP REST | | `/api/deploy/*` | Coding project deployment | HTTP REST | | `/api/sandbox/*` | Sandbox management | HTTP REST | | `/ws/extension` | Browser extension WebSocket | WebSocket | | `/ws/desktop` | Desktop application WebSocket | WebSocket | | `/ws/web` | Web client WebSocket | WebSocket | *** ## Components & Data Flow ### Request Flow — Agent Invocation ```mermaid theme={null} sequenceDiagram participant Client as Client
(Web / Desktop / iOS / Android) participant WebAPI as Web API
(Next.js) participant DB as PostgreSQL participant AIBackend as AI Backend
(FastAPI) participant Node as Node
(Extension / Desktop) Client->>WebAPI: POST /api/agent/invoke
{message, sessionId, ...} Note over WebAPI: 1. Authenticate (JWT) Note over WebAPI: 2. Check & deduct credits WebAPI->>DB: Query LLM config, tools, skills DB-->>WebAPI: User configurations Note over WebAPI: 3. Assemble context
(LLM config, tools, skills, env vars) WebAPI->>AIBackend: Forward POST /api/agent/invoke
{message, llm_config, tools, session_id, ...} Note over AIBackend: 4. Agent loop starts AIBackend-->>WebAPI: SSE: TextMessage (streaming) WebAPI-->>Client: SSE: TextMessage (pass-through) AIBackend-->>WebAPI: SSE: ToolCallMessage WebAPI-->>Client: SSE: ToolCallMessage opt Connector Tool AIBackend->>Node: JSON-RPC tool call (WebSocket) Node-->>AIBackend: JSON-RPC result end AIBackend-->>WebAPI: SSE: ToolCallResult WebAPI-->>Client: SSE: ToolCallResult AIBackend-->>WebAPI: SSE: CompleteMessage WebAPI-->>Client: SSE: CompleteMessage ``` ### WebSocket Gateway The Gateway manages all WebSocket connections through `ConnectionManager`, supporting three node types: ```mermaid theme={null} graph LR subgraph Gateway["ConnectionManager"] ext_pool["extension_connections
user_id → {node_id → WS}"] desktop_pool["desktop_connections
user_id → {node_id → WS}"] web_pool["web_connections
user_id → {WS Set}"] pending["pending_requests
request_id → Future"] end ext["Browser Extension"] -->|"/ws/extension"| ext_pool desktop["Desktop App"] -->|"/ws/desktop"| desktop_pool web["Web Client"] -->|"/ws/web"| web_pool pending -->|"resolve"| ext_pool pending -->|"resolve"| desktop_pool ``` * **Extension / Desktop nodes**: Each node is uniquely identified by `node_id`; a user can have multiple nodes * **Web clients**: Managed by `user_id`; the same user can have multiple Web connections * **Tool calls**: The Agent initiates JSON-RPC requests via `call_tool()`; the Gateway routes requests to the corresponding node and awaits responses (Future-based) ### Agent Service The Agent Service is the core orchestration layer, built on the **DeepAgents** framework (a higher-level wrapper over LangGraph): ```mermaid theme={null} graph TD invoke["invoke()"] --> init["_init_context()"] init --> load_tools["Load tools"] init --> build_prompt["Assemble System Prompt"] init --> init_llm["Initialize LLM"] load_tools --> mcp["MCP Tools"] load_tools --> oauth["OAuth Tools"] load_tools --> browser["Browser Tools"] load_tools --> desktop_tools["Desktop Tools"] load_tools --> builtin["Built-in Tools
(RAG, Memory, Sandbox, Web Search)"] build_prompt --> core["CORE.md"] build_prompt --> soul["SOUL.md"] build_prompt --> tools_prompt["TOOLS.md"] build_prompt --> workflow["WORKFLOW.md"] build_prompt --> memory_prompt["MEMORY.md"] build_prompt --> dynamic["Dynamic injection
(Profile, Memories, Skills)"] init --> create["_create_deep_agent()"] create --> stream["_astream_events()"] stream --> sse["SSE response stream"] sse --> text["TextMessage"] sse --> tool_call["ToolCallMessage"] sse --> tool_result["ToolCallResultMessage"] sse --> complete["CompleteMessage"] ``` **Service Layer:** | Service | File | Responsibility | | -------------------- | ----------------------- | ------------------------------------------------------------------------------- | | **BaseService** | `services/base.py` | Context initialization, tool assembly, prompt construction, SSE event streaming | | **AgentService** | `services/agent.py` | Agent mode invoke/resume entry point | | **RAGService** | `services/rag.py` | Knowledge base retrieval (vector + BM25 hybrid search) | | **DocumentService** | `services/document.py` | Document processing and chunking | | **FeishuService** | `services/feishu.py` | Feishu channel integration | | **SchedulerService** | `services/scheduler.py` | Scheduled task scheduling | ### Tool System Zeus tools are organized into four layers: ```mermaid theme={null} graph LR subgraph L1["Built-in Tools"] memory["Memory Tools
CRUD operations"] rag["RAG Tools
Knowledge base retrieval"] sandbox["Sandbox Tools
Code execution"] search["Web Search
Tavily / DuckDuckGo"] skill_tool["Skill Tools
Dynamic skill loading"] end subgraph L2["MCP Tools"] mcp_tavily["Tavily MCP"] mcp_custom["Custom MCP Servers"] end subgraph L3["OAuth Tools"] github["GitHub"] gmail["Gmail"] gdrive["Google Drive"] notion["Notion"] slack["Slack"] end subgraph L4["Connector Tools"] browser_ops["Browser Automation
(via Extension Node)"] desktop_ops["Desktop Automation
(via Desktop Node)"] end ``` | Layer | Source | Registration | Execution Location | | ------------- | --------------------------- | -------------------------------- | -------------------------------- | | **Built-in** | `utils/tools/built_in/` | Registered directly in code | AI Backend local | | **MCP** | Passed from frontend config | `langchain_mcp_adapters` | MCP Server (remote) | | **OAuth** | Passed from frontend config | Dynamically built LangChain Tool | AI Backend → OAuth API | | **Connector** | Reported by WebSocket nodes | Bound via SessionManager | Remote nodes (Extension/Desktop) | Connector Tools call chain: Agent → ToolRouter → Gateway → WebSocket → Node → Execute → Return via same path. ### Node Management Node management is handled by three cooperating components: | Component | Description | | ------------------ | ----------------------------------------------------------------------------- | | **NodeManager** | Node registration/deregistration, heartbeat TTL (60s), periodic cleanup (30s) | | **SessionManager** | Binds sessions to specific nodes, supports `preferred_node_id` specification | | **ToolRouter** | Routes tool calls to the appropriate node based on session binding | Each user can have up to **10 nodes**; nodes that miss heartbeats are automatically marked offline and deregistered. ### Storage & State | Storage | Technology | Owner | Purpose | | ------------------ | ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | | **App Database** | PostgreSQL (Drizzle ORM) | Web API | Users, sessions, messages, tools, skills, credits, projects, showcase | | **Checkpointer** | PostgreSQL (`PostgresSaver`) | AI Backend | Session-level Agent state persistence, supports HITL recovery | | **Memory** | PostgreSQL + pgvector | AI Backend | Long-term memory (vectors + metadata), three-tier scoping | | **Knowledge Base** | PostgreSQL + pgvector + BM25 | AI Backend | RAG document storage and hybrid retrieval | | **Workspace** | Supabase Storage / S3 (MinIO) | Web API | User files (outputs, uploads, sandbox results). Auto-selects S3 when `S3_ENDPOINT` is configured | | **Cache** | Redis | Both | Workspace cache (5min), memory cache (10min), TaskIQ result backend | | **Message Queue** | RabbitMQ (TaskIQ) | AI Backend | Async task broker for scheduled tasks, RAG processing, cloud sync | *** ## Communication Protocols ### HTTP SSE (Agent Response Stream) Agent invocations return `text/event-stream`. SSE event types: | Event Type | data Field | Description | | ------------------ | -------------------------------------------- | -------------------------------------- | | `text` | `{type, content}` | Streaming text tokens | | `tool_call` | `{type, tool_name, tool_args, tool_call_id}` | Agent initiates a tool call | | `tool_call_result` | `{type, tool_name, result, ...}` | Tool execution result | | `interrupt` | `{type, tool_calls, ...}` | HITL interrupt, awaiting user approval | | `complete` | `{type, finish_reason}` | Stream ended | | `error` | `{type, error}` | Error message | ### WebSocket JSON-RPC 2.0 (Node Tool Calls) Node tool calls follow the **MCP (Model Context Protocol)** specification: **Request:** ```json theme={null} { "jsonrpc": "2.0", "id": "uuid-string", "method": "tools/call", "params": { "name": "browser_click", "arguments": { "selector": "#submit-btn" }, "session_id": "session_abc123" } } ``` **Response (Success):** ```json theme={null} { "jsonrpc": "2.0", "id": "uuid-string", "result": { "content": [ { "type": "text", "text": "Clicked element successfully" }, { "type": "image", "data": "base64...", "mimeType": "image/jpeg" } ], "isError": false } } ``` **Response (Error):** ```json theme={null} { "jsonrpc": "2.0", "id": "uuid-string", "error": { "code": -32603, "message": "Element not found" } } ``` ### WebSocket Message Types (Non JSON-RPC) | Direction | type | Description | | -------------- | ------------------ | ---------------------------------------------- | | Node → Gateway | `register` | Node registration (capabilities, tools) | | Gateway → Node | `registered` | Registration confirmation | | Node → Gateway | `heartbeat` | Heartbeat report (status, current\_tasks) | | Gateway → Node | `heartbeat_ack` | Heartbeat acknowledgment | | Node ↔ Gateway | `ping` / `pong` | Keepalive | | Web → Gateway | `get_workflows` | Request workflow list (forwarded to Extension) | | Web → Gateway | `execute_workflow` | Execute workflow | | Node → Gateway | `task_complete` | Workflow execution completed | *** ## Startup & Lifecycle ### Web API Startup The Next.js application starts automatically and serves: * All API routes under `/api/*` * Web frontend pages under `/[locale]/*` * Authentication via Better Auth middleware ### AI Backend Startup ```mermaid theme={null} graph TD start["uvicorn startup"] --> env["load_dotenv()"] env --> langsmith["init_langsmith()"] langsmith --> lifespan["lifespan() start"] lifespan --> node_mgr["NodeManager.start()
Start heartbeat cleanup loop"] lifespan --> feishu_init["FeishuService.initialize()
Initialize Feishu"] lifespan --> scheduler_start["TaskScheduler.start()
Start scheduled tasks + sync"] scheduler_start --> ready["Service ready"] ``` ### Key Environment Variables **Web API (Next.js):** | Variable | Description | | ------------------------------------------------- | ---------------------------------------------------------------------- | | `DATABASE_URL` | PostgreSQL connection string (app database) | | `BACKEND_URL` | AI Backend URL for agent forwarding (default: `http://localhost:8000`) | | `BETTER_AUTH_SECRET` | Better Auth secret key | | `SUPABASE_URL` / `SUPABASE_SERVICE_KEY` | Supabase Storage configuration | | `S3_ENDPOINT` / `S3_ACCESS_KEY` / `S3_SECRET_KEY` | S3/MinIO storage (alternative to Supabase, optional) | **AI Backend (FastAPI):** | Variable | Description | | ------------------------------------ | ------------------------------------------------------ | | `DATABASE_URL` | PostgreSQL connection string (Checkpointer + pgvector) | | `NEXTJS_API_URL` | Web API URL for callbacks (user data, config lookups) | | `OPENAI_API_KEY` / `OPENAI_BASE_URL` | Default LLM configuration | | `REDIS_URL` | Redis cache and TaskIQ result backend (optional) | | `RABBITMQ_URL` | RabbitMQ message queue for async tasks (optional) | | `LANGCHAIN_API_KEY` | LangSmith tracing (optional) | ### Health Checks * AI Backend: `GET /health` → `{"status": "ok"}` * AI Backend: `GET /` → `{"name": "Zeus Backend API", "version": "1.0.0", "status": "running"}` *** ## System Invariants * **JWT Authentication**: All Web API routes require a valid JWT Token; AI Backend receives a forwarded token from Web API * **Session Isolation**: Each `session_id` has independent Checkpointer state; different sessions do not interfere * **Node Heartbeat**: Nodes that miss heartbeats for over 60 seconds are automatically marked offline; the Gateway immediately deregisters nodes on disconnect * **Tool Call Timeout**: WebSocket tool calls default to 60-second timeout; workflow execution has a 300-second timeout * **SSE Non-Replay**: Agent invocation SSE streams are one-time; after disconnect, context must be restored via Checkpointer * **Credit Gate**: Web API checks and deducts credits before forwarding any agent request to AI Backend * **Single-Instance Gateway**: The current `ConnectionManager` is a per-process singleton; WebSocket connections are not shared across processes *** ## Directory Structure **Web API (Next.js):** ``` apps/web/src/ ├── app/ │ ├── [locale]/ # Page routes (i18n) │ └── api/ # API routes (93 routes) │ ├── agent/ # Agent forwarding → AI Backend │ ├── auth/ # Authentication │ ├── sessions/ # Session management │ ├── tools/ # Tool configuration │ ├── skills/ # Skill management │ ├── knowledge-base/ # Knowledge base │ ├── projects/ # Project management │ ├── credits/ # Credit system │ ├── memory/ # Memory management │ ├── config/ # LLM / Embedding / Sandbox config │ └── ... ├── db/ │ ├── schema/ # Drizzle ORM table definitions │ ├── model/ # Data access layer (CRUD) │ ├── service/ # Business logic layer │ └── storage/ # Storage operations ├── lib/auth/ # Authentication (Better Auth, JWT) └── ... ``` **AI Backend (FastAPI):** ``` apps/ai-backend/src/ ├── api/ # FastAPI routing layer │ ├── main.py # Entry point & lifecycle │ ├── gateway.py # WebSocket gateway │ ├── agent.py # Agent API (invoke/resume) │ ├── mcp_gateway.py # MCP protocol gateway │ ├── skill.py # Skill API │ ├── tools.py # Tools API │ ├── knowledge_base.py # Knowledge base RAG API │ ├── node.py # Node query API │ ├── scheduled_task.py # Scheduled task API │ ├── deploy.py # Deployment API │ ├── sandbox.py # Sandbox API │ └── channels/ # Channels (Feishu) ├── services/ # Business logic layer │ ├── base.py # BaseService (Agent core) │ ├── agent.py # AgentService │ ├── rag.py # RAG retrieval │ ├── document.py # Document processing │ ├── sandbox.py # Sandbox management │ ├── notification.py # Notification service │ ├── feishu.py # Feishu service │ └── scheduler.py # Scheduled tasks ├── repository/ # Data models & prompts │ ├── models/ # Pydantic Models │ ├── prompts/ # System Prompts (.md) │ └── skills/ # Skill definitions └── utils/ # Utility layer ├── core/ # LLM, Memory, Skills, HITL ├── infra/ # Backend, Checkpoint, Node, Redis, Auth ├── tools/ # Tool implementations │ ├── built_in/ # Built-in tools │ └── plugin/ # Plugin tools (Feishu) ├── sandbox/ # Sandbox providers (E2B, OpenSandbox, Daytona) ├── knowledge_base/ # Vector storage & chunking └── channels/ # Channel integrations ``` Runtime detailed design — Workspace, Session, Modes Channels & Gateway — Feishu, WebSocket node communication Four-layer tool system — Built-in, MCP, OAuth, Connector Storage architecture — CloudDriveBackend, Checkpoint