Architecture Overview

系统架构 / Architecture Overview

中英双语 | Bilingual

---

中文

架构总览

┌──────────────────────────────────────────────────┐
│            React 前端 (SPA)                       │
│   Chat 面板 │ Map 面板 (2D/3D) │ Data 面板 (19 Tab)│
├──────────────────────────────────────────────────┤
│          Chainlit + Starlette 服务端              │
│   134 REST API │ WebSocket │ JWT 认证             │
├──────────────────────────────────────────────────┤
│           意图路由器 (Gemini 2.0 Flash)            │
│    ┌───────────┬────────────┬───────────┐        │
│    │ 优化管道   │  治理管道   │  通用管道  │        │
│    │ Sequential │ Sequential │ Sequential│        │
│    └───────────┴────────────┴───────────┘        │
├──────────────────────────────────────────────────┤
│  28 工具集 │ 18 技能 │ MMFE 融合 │ DRL 引擎       │
│  知识图谱 │ MCP Hub │ A2A 协议 │ 6 连接器        │
├──────────────────────────────────────────────────┤
│  PostgreSQL/PostGIS │ OBS 云存储 │ Redis (可选)   │
└──────────────────────────────────────────────────┘

关键设计决策

决策	方案	原因
Agent 框架	Google ADK	SequentialAgent/LoopAgent 组合，output_key 状态共享
意图路由	Gemini Flash 分类	低延迟，支持中/英/日三语
用户上下文	ContextVar	异步安全的每请求用户身份传播
数据库连接	单例 get_engine()	连接池复用，避免重复创建
Agent 实例	工厂函数 make_planner*()	ADK 单父约束要求独立实例
管道执行	pipeline_runner.py 无头模式	支持 CLI/API/Workflow 调用

代码规模

类别	行数	文件数
Python 生产代码	55,886	176
Python 测试代码	29,346	95
前端源码	9,724	33
文档	24,678	83

详细架构：enterprise-architecture.md | 技术指南：technical-guide.md

---

English

Architecture Overview

┌──────────────────────────────────────────────────┐
│            React Frontend (SPA)                   │
│   Chat Panel │ Map Panel (2D/3D) │ Data Panel(19) │
├──────────────────────────────────────────────────┤
│          Chainlit + Starlette Server              │
│   134 REST APIs │ WebSocket │ JWT Auth            │
├──────────────────────────────────────────────────┤
│           Intent Router (Gemini 2.0 Flash)        │
│    ┌────────────┬─────────────┬──────────┐       │
│    │Optimization│ Governance  │ General  │       │
│    │ Pipeline   │ Pipeline    │ Pipeline │       │
│    └────────────┴─────────────┴──────────┘       │
├──────────────────────────────────────────────────┤
│  28 Toolsets │ 18 Skills │ MMFE Fusion │ DRL     │
│  Knowledge Graph │ MCP Hub │ A2A │ 6 Connectors │
├──────────────────────────────────────────────────┤
│  PostgreSQL/PostGIS │ OBS Cloud │ Redis (opt.)   │
└──────────────────────────────────────────────────┘

Key Design Decisions

Decision	Choice	Rationale
Agent Framework	Google ADK	SequentialAgent/LoopAgent composition, output_key state sharing
Intent Routing	Gemini Flash classification	Low latency, supports Chinese/English/Japanese
User Context	ContextVar	Async-safe per-request user identity propagation
DB Connection	Singleton get_engine()	Connection pool reuse
Agent Instances	Factory functions	ADK single-parent constraint requires separate instances
Pipeline Execution	Headless pipeline_runner.py	Supports CLI/API/Workflow invocation

Codebase Statistics

Category	Lines	Files
Python Production	55,886	176
Python Tests	29,346	95
Frontend Source	9,724	33
Documentation	24,678	83

Full architecture: enterprise-architecture.md | Technical guide: technical-guide.md