# 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`。