# 架构与边界

## 启动流程

```text
dev.ts / main.ts
  -> parseRuntimeArgs(cli args) — 必须指定 config.yaml
  -> bootstrap({ configPath, mode })
     -> loadServerConfig(configPath) — 加载并校验配置（config.ts）
     -> createRuntimeLogger(config.logging) — 创建 Logger 实例
     -> mkdirSync(dataDir)
     -> 加载 migrations（生产：嵌入 bytes；开发：磁盘 drizzle/）
     -> createDatabase(dataDir)
     -> runMigrations(db, migrations) — pending 时先备份 DB
     -> startServer({ config, logger, db })
  -> SIGINT/SIGTERM -> db.close() -> logger.flush() -> exit
```

## HTTP 请求流程

```text
Request -> Bun.serve routes 声明式匹配 -> routes/*.ts handler -> helpers/ 响应格式化 -> Response
```

- 生产模式：非 API 路径由 fetch fallback 处理，有扩展名返回静态资源或 404，无扩展名返回 SPA index.html。
- 开发模式：Vite proxy 将 /api 转发到 Bun。

## 前后端边界

- 前端只通过 HTTP /api/\* 调用后端。
- 共享类型在 `src/shared/`。
- 前端禁止 import `src/server/` 运行时实现；后端禁止依赖 `src/web/` 运行时代码（HTML import 集成除外）。

## 主要模块

| 模块                      | 职责                                                     |
| ------------------------- | -------------------------------------------------------- |
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化、shutdown 编排                   |
| `src/server/config.ts`    | 配置加载入口：YAML 解析、规范化、契约校验、运行时校验    |
| `src/server/config/`      | 配置子系统：types、variables、issues、normalizer、schema |
| `src/server/logger.ts`    | Logger 接口 + Pino 实现 + 测试替身                       |
| `src/server/server.ts`    | Bun HTTP server + routes 注册                            |
| `src/server/routes/`      | API handler，按资源端点拆分                              |
| `src/server/db/`          | SQLite 连接、schema、migration、data access              |
| `src/server/ai/`          | AI Provider Registry + Agent + 工具                      |
| `src/server/helpers/`     | 响应格式化、URL 工具                                     |
| `src/server/middleware/`  | 参数校验 + 错误处理                                      |
| `src/shared/api.ts`       | 前后端共享 API 类型                                      |
| `src/shared/app.ts`       | 应用全局常量                                             |

## 路由分组

| 资源      | 路径前缀                                        | 文件目录            |
| --------- | ----------------------------------------------- | ------------------- |
| meta      | `/api/meta`                                     | `routes/meta.ts`    |
| providers | `/api/providers`                                | `routes/providers/` |
| models    | `/api/models`                                   | `routes/models/`    |
| projects  | `/api/projects`                                 | `routes/projects/`  |
| chat      | `/api/projects/:id/conversations` 和 `:id/chat` | `routes/chat/`      |

## 更新触发条件

修改项目结构、启动流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。