Alfred/docs/development/architecture.md

架构与边界

启动流程

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 请求流程

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 请求流程、前后端边界或主要模块职责时，必须更新本文档。