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 集成除外）。

配置定位

配置类型	来源	内容	可变性
启动配置	CLI 传入的 config.yaml	监听地址、端口、日志、数据目录	进程内只读
业务设置	管理台 /settings 页面 → GET/PUT /api/settings → SQLite settings 表	主题偏好等 UI/业务开关	运行时可变

启动配置由 src/server/config.ts 的 loadServerConfig() 在启动时加载并校验，运行时不可更改。业务设置通过独立 API 持久化，与启动配置在存储和生命周期上完全解耦。

主要模块

模块	职责
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/web/layouts/	前端布局组件（AdminLayout / WorkbenchLayout）
src/web/features/	前端功能模块（dashboard / projects / models / chat / settings）
src/web/shared/	前端共享代码（components / hooks / utils）
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/
settings	/api/settings	routes/settings.ts

更新触发条件

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