# 架构与边界

本文档说明 alfred 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。

适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。

## 项目结构

```text
src/
  server/
    bootstrap.ts     统一启动引导（loadServerConfig -> DB 初始化 -> startServer）
    config.ts        CLI 参数解析与配置文件加载 facade
    config/          配置解析模块
      index.ts        配置模块导出
      types.ts        配置类型定义
      issues.ts       配置问题收集
      variables.ts    变量解析
      normalizer.ts   配置标准化
      schema/         JSON Schema 生成与校验
        builder.ts
        export.ts
        fragments.ts
        validate.ts
    db/              SQLite 数据库模块
      index.ts        数据库模块导出
      schema.ts       Drizzle ORM schema 定义
      connection.ts   数据库连接与 PRAGMA 设置
      load-migrations.ts  从文件系统加载 migration SQL
      migrate.ts     migration 执行器（备份 + 事务应用）
      projects.ts    项目数据访问函数
      providers.ts   供应商数据访问函数
      models.ts      模型数据访问函数
      conversations.ts 会话与消息数据访问函数
    ai/              AI 服务层
      types.ts        AI 配置类型定义
      registry.ts     AI Provider Registry 构建与连接测试
      agents/         Agent 工厂
        alfred-agent.ts Agent 工厂（ToolLoopAgent + 工具）
      tools/          工具定义
        get-current-time.ts 获取当前时间工具
    dev.ts           开发模式启动入口
    main.ts          生产模式启动入口
    server.ts        HTTP server 启动工厂（Bun.serve routes 声明式路由）
    static.ts        生产模式静态资源服务
    helpers/          共享工具模块
      index.ts        模块导出
      response.ts     响应格式化工具
      url.ts          URL 拼接工具
    middleware/       API 中间件模块
      index.ts        模块导出
      validate.ts     参数校验中间件
      error-handler.ts 错误处理中间件
    logger.ts        结构化日志（基于 pino + pino-roll）
    version.ts       运行时版本号读取
    routes/          API 路由处理器
      meta.ts         应用元信息路由
      providers/      供应商 CRUD 与测试路由
      models/         模型 CRUD 与测试路由
      projects/       项目 CRUD、归档与恢复路由
      chat/           聊天会话与消息路由（含 SSE 流式发送）
  shared/
    api.ts           前后端共享 TypeScript 类型定义
    app.ts           应用全局常量（name、title、subtitle、description）
  web/               React 前端（通过 Vite 构建）
    index.html       HTML 入口
    main.tsx         React 入口（StrictMode + ErrorBoundary + QueryClientProvider + BrowserRouter）
    app.tsx          根组件（设置 document 标题和 meta）
    routes.tsx       路由配置（Admin + Workbench 两大控制台）
    menu.tsx         共享菜单项类型定义
    styles.css       全局样式
    css.d.ts         CSS Modules 类型声明
    pages/           页面组件
      dashboard/      总览页面
      projects/       项目管理页面及其子组件
      models/         模型管理页面及其子组件
      404/            404 页面
    components/      共享 UI 组件
      ErrorBoundary.tsx 错误边界
      ConsoleShell/   通用控制台外壳（ConsoleShell、ConsoleOutlet、types）
      Sidebar/        侧边栏导航组件
    consoles/        控制台入口
      admin/          Admin 管理台（AdminConsoleLayout、菜单配置）
      workbench/      Workbench 工作台（ProjectGate、ConsoleLayout、菜单配置、ChatPage 等）
    hooks/           React Hooks（use-meta、use-projects、use-providers、use-models、use-conversations、主题/侧边栏偏好）
    utils/           前端工具函数（fetch 封装、时间格式化）
scripts/              独立运行脚本
tests/                测试文件（镜像 src 目录结构）
docs/                 项目文档
openspec/             OpenSpec 规格、变更与 fast-drive workflow schema
```

## 启动流程

```text
dev.ts / main.ts
  -> parseRuntimeArgs(cli args)
  -> 必须指定 config.yaml
  -> bootstrap({ configPath, mode })
  -> loadServerConfig(configPath)
  -> createRuntimeLogger(config.logging)
  -> 确保 dataDir 就绪（mkdirSync）
  -> 加载 migrations（生产：嵌入的 bytes；开发：磁盘 drizzle/ 目录）
  -> createDatabase(dataDir)
  -> runMigrations(db, migrations)（pending migration 存在时先备份 DB）
  -> startServer({ config, logger, db })
  -> logger 记录启动成功
  -> 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 API server。

## 前后端边界

- 前端只通过 HTTP 调用后端，API 路径为 /api/\*。
- 共享类型放在 src/shared/。
- 前端不得 import src/server/ 的运行时实现。
- 后端不得依赖 src/web/ 运行时代码，HTML import 集成除外。

## 主要模块职责

| 模块                      | 职责                                                                   |
| ------------------------- | ---------------------------------------------------------------------- |
| `src/server/bootstrap.ts` | 统一启动引导、DB 初始化和 shutdown 编排                                |
| `src/server/server.ts`    | Bun HTTP server 和 routes 注册                                         |
| `src/server/routes/`      | API handler，按资源端点拆分（meta、providers、models、projects、chat） |
| `src/server/db/`          | SQLite 连接、schema、migration 和 data access                          |
| `src/server/ai/`          | AI Provider Registry 构建与 Agent 流式调用                             |
| `src/server/config/`      | 配置解析模块（types、variables、normalizer、schema）                   |
| `src/server/helpers/`     | 共享响应格式化和 URL 工具                                              |
| `src/server/middleware/`  | API 参数校验和错误处理中间件                                           |
| `src/web/`                | React 前端（Admin + Workbench 双控制台架构）                           |
| `src/shared/api.ts`       | 前后端共享 API 类型                                                    |
| `src/shared/app.ts`       | 应用全局常量                                                           |

### 路由按资源分组

| 资源分组  | 路径前缀                                                      | 路由文件                     |
| --------- | ------------------------------------------------------------- | ---------------------------- |
| meta      | `/api/meta`                                                   | `routes/meta.ts`             |
| providers | `/api/providers`                                              | `routes/providers/` (7 文件) |
| models    | `/api/models`                                                 | `routes/models/` (6 文件)    |
| projects  | `/api/projects`                                               | `routes/projects/` (7 文件)  |
| chat      | `/api/projects/:id/conversations` 和 `/api/projects/:id/chat` | `routes/chat/` (7 文件)      |

## 更新触发条件

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