Developer Guide · 01

Architecture Overview

text

┌──────────────────────────────────────────────────────────────────┐
│                        Clients                                    │
│  ┌──────────────┐ ┌────────────┐ ┌─────────┐ ┌────────────────┐ │
│  │  Admin SPA   │ │  Service   │ │ WeChat  │ │ Tauri Desktop  │ │
│  │  React 19    │ │ /s/{sid}   │ │ /wc/..  │ │ (Rust + WV)    │ │
│  └──────┬───────┘ └─────┬──────┘ └────┬────┘ └────────┬───────┘ │
└─────────┼───────────────┼─────────────┼───────────────┼─────────┘
          │ /api/*        │ /api/v1/*   │ iLink         │ launcher.py
          ▼               ▼             ▼               ▼
┌──────────────────────────────────────────────────────────────────┐
│  Nginx (:80) — SSL termination + reverse proxy                    │
│  → Express (:3000) — static files (dist/) + /api proxy            │
│  → FastAPI (:8000) — core backend                                  │
├──────────────────────────────────────────────────────────────────┤
│  FastAPI Application (app/)                                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │ routes/  │ │ services/│ │ channels/│ │ storage/ │ │ voice/ │ │
│  │ routing  │ │ business │ │ wechat   │ │ abstraction│S2S WS │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
│       └─────┬──────┴───────┬────┘            │           │      │
│             ▼              ▼                  ▼           ▼      │
│  ┌─────────────────────────────┐  ┌──────────────────┐ ┌──────┐ │
│  │  deepagents + LangGraph     │  │  Local FS / S3   │ │ S2S  │ │
│  │  Agent runtime + AsyncSqlite│  │  + AES key enc.  │ │ Proxy│ │
│  └─────────────────────────────┘  └──────────────────┘ └──────┘ │
└──────────────────────────────────────────────────────────────────┘

External protocols:
  • WeChat iLink Bot: app/channels/wechat/ ⇄ ilinkai.weixin.qq.com
  • OpenAI Realtime:  app/voice/router.py ⇄ wss://api.openai.com/.../realtime
  • CloudsWay / Tavily: app/services/web_tools.py (web search)

Layered Design

Layer	Responsibility	Directory
Route Layer	HTTP request handling, parameter validation, SSE streaming	`app/routes/`
Business Layer	Agent creation/cache, tools, conversations, scheduling, inbox	`app/services/`
Channel Layer	WeChat iLink protocol (Service + Admin dual-stack)	`app/channels/wechat/`
Storage Layer	Local / S3 file storage abstraction	`app/storage/`
Core Layer	Auth, config, path security, encryption, Langfuse	`app/core/`
Voice Layer	S2S WebSocket proxy (OpenAI Realtime)	`app/voice/`

Three Runtime Environments

Environment	Entry Point	Use Case
Local Dev	`python launcher.py --dev` or `uvicorn` + `vite dev`	Development, hot reload
Docker	`docker compose up -d --build`	Server / team deployment
Desktop App	`tauri-launcher/` compiled to `.dmg` / `.exe`	End users, double-click launch

NextTechnology Stack→