Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
151 lines (117 loc) · 7.36 KB

ARCHITECTURE.md

File metadata and controls

151 lines (117 loc) · 7.36 KB
Raw

ARCHITECTURE.md — Coze Loop

Coze Loop 是一个开源的 LLM 评测与可观测性平台，采用 Go 后端 + TypeScript/React 前端的多语言单体仓库架构。

全景视图

┌─────────────────────────────────────────────────────────────────┐
│                        coze-loop 仓库                           │
│                                                                 │
│  ┌──────────────┐   ┌───────────────┐   ┌────────────────────┐  │
│  │   frontend/   │   │    backend/    │   │     release/       │  │
│  │  Rush.js SPA  │──▶│  Go DDD 服务   │   │  Docker / Helm    │  │
│  │  59 packages  │   │  6 业务模块    │   │  部署配置          │  │
│  └──────┬───────┘   └───────┬───────┘   └────────────────────┘  │
│         │                   │                                    │
│         └───────┬───────────┘                                    │
│                 ▼                                                │
│          ┌────────────┐                                          │
│          │ idl/thrift/ │  Thrift IDL（前后端共享契约）            │
│          └────────────┘                                          │
│                                                                 │
│  ┌──────────────┐   ┌───────────────┐   ┌────────────────────┐  │
│  │   common/     │   │  .github/      │   │    Makefile        │  │
│  │  git-hooks    │   │  workflows/    │   │  image / deploy   │  │
│  └──────────────┘   └───────────────┘   └────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

代码地图

Backend (backend/)

Go 服务，模块路径 github.com/coze-dev/coze-loop/backend。

目录 职责 架构不变量
cmd/ 服务入口（main.go HTTP, consumer.go MQ） 只做启动编排，不含业务逻辑
api/ HTTP 路由 + handler（Hertz 框架） handler 只做参数校验和转发，业务逻辑在 application 层
modules/ 6 个 DDD 业务模块 模块间不直接互调
infra/ 共享基础设施（DB, Redis, ClickHouse, MQ, HTTP, middleware） 被 modules 引用，不引用 modules
pkg/ 共享工具库（errors, JSON, logging, context cache） 纯工具，无业务依赖
kitex_gen/ Kitex/Thrift 生成代码 自动生成，禁止手动修改
loop_gen/ 其他生成代码 自动生成，禁止手动修改
script/ 代码生成脚本（cloudwego, gorm_gen, errorx） 生成结果提交到仓库

Backend DDD 分层

每个 modules/<domain>/ 内部遵循严格的 DDD 分层:

modules/<domain>/
├── application/     # 应用服务（用例编排、Wire DI）
│   ├── wire.go      # DI 定义
│   └── wire_gen.go  # DI 生成代码
├── domain/          # 领域模型（entity, repo 接口, service）
│   ├── entity/
│   ├── repo/        # 仓储接口定义
│   └── service/
├── infra/           # 基础设施实现（repo 实现, RPC, MQ, storage）
│   ├── repo/        # 仓储接口实现
│   ├── mq/  rpc/  storage/
│   └── ...
├── pkg/             # 模块内工具（errno, utils）
└── consts/          # 模块常量

依赖方向: api/ → application/ → domain/ ← infra/。domain 层定义接口，infra 层实现。domain 绝不引用 infra。

Backend 技术栈

  • HTTP: Hertz (CloudWeGo)
  • RPC: Kitex (CloudWeGo) + Thrift
  • ORM: GORM（MySQL, ClickHouse）
  • DI: Wire (Google)
  • LLM: Eino
  • 存储: MySQL（主存储）、ClickHouse（分析查询）、Redis（缓存/锁）、RocketMQ（异步消息）

Frontend (frontend/)

Rush.js 5.172.1 管理的 TypeScript/React 单体仓库，pnpm 10.27.0，59 个包。

层级 目录 包数 职责
Level-6 apps/cozeloop/ 1 主 SPA（React 18, Rsbuild, react-router, zustand）
Level-5 packages/loop-pages/ 5 页面模块（auth, evaluate, observation, prompt, tag）
Level-4 packages/loop-modules/ 1 高阶业务模块（evaluate）
Level-3 packages/loop-components/ 13 UI 组件包 + adapter 模式
Level-2 packages/loop-base/ 20 基础库（account, api-schema, hooks, components, env, i18n, stores, route...）
Level-1 config/ + infra/ 10+ 工具链配置 + ESLint 插件 + IDL 转换

依赖不变量: 高层级只能依赖低层级，禁止反向依赖。

Adapter 模式

用于解耦商业版与开源版差异:

adapter-interfaces/   # 接口定义（Level-3）
    ↑
*-adapter/            # 接口实现（Level-3，按 evaluate/observation 等分）
    ↑
components-with-adapter/  # 消费者（Level-3）

新增商业版/开源版差异必须走 adapter 接口，不可在组件中硬编码条件分支。

IDL (idl/thrift/)

Thrift IDL 定义，是前后端的共享契约。修改 IDL 后需分别运行:

  • 后端: backend/script/cloudwego/ 重新生成 Go 代码
  • 前端: infra/idl/ 工具将 Thrift 转换为 TypeScript 类型

Release (release/)

目录 内容
release/image/ Dockerfile（主服务, debug, python-faas）
release/deployment/docker-compose/ Docker Compose 本地部署
release/deployment/helm-chart/ Helm Chart (Kubernetes 部署)

Makefile 提供 image-*、compose-*、helm-* 等快捷目标。

横切关注点

代码生成

生成物 触发方式 输入
kitex_gen/ backend/script/cloudwego/ idl/thrift/
loop_gen/ 相关脚本 IDL / schema
wire_gen.go 各 module application/ 目录下执行 wire wire.go
router_gen.go Hertz 代码生成 路由定义

CI/CD

.github/workflows/ 共 10 个工作流:

工作流 触发 作用
backend-ci.yaml PR (backend/**) Go test + lint + Codecov
frontend-ci.yaml PR (frontend/**) Rush build + Vitest + lint
frontend-tsc-ci.yaml PR (frontend/**) TypeScript 类型检查
idl.yaml PR (idl/**) IDL 变更检查
mysql-schema-check.yaml PR 数据库 schema 变更检查
semantic-pull-request.yaml PR PR 标题规范检查
license-check.yaml PR License 合规检查

Git Hooks (common/git-hooks/)

由 Rush 管理，包含 pre-commit, commit-msg, pre-push, post-checkout, post-commit, post-merge。详见 CONTRIBUTING.md。