项目结构
按页面、领域包、部署配置与测试定位实际代码，避免跨层修改。
这份结构来自独立 musemvp-flare 仓库。官网自己的 Next.js 目录不是 Flare 的源码来源。
目录总览
musemvp-flare/
.agents/skills/ # 当前仓库的 agent 工作流
.env.example # 可提交的部署变量清单
apps/web/
components.json # shadcn/Base UI 组件配置
public/logo.png # 产品标志
src/
components/ui/ # 应用 UI 组件
components/brand.tsx # 品牌与语言链接
components/theme.tsx # 系统/浅色/深色菜单
hooks/use-mobile.ts # 移动布局判断
routes/ # TanStack 页面和 API 路由
modules/ # public/auth/workbench/billing/ai
server/ # 绑定、HTTP、文件、队列和限流
content/ # 成对的 en/zh MDX
lib/ # 客户端请求、语言、SEO 和 cn
vite.config.ts
wrangler.jsonc # 本地 Worker 配置
packages/
ai/ auth/ billing/ cli/ config/ db/
i18n/ mail/ shared/ storage/ testing/ ui/
scripts/check-contracts.mjs
tests/api/ tests/e2e/ tests/unit/ tests/fixtures/
docs/ # 架构、部署、支付和发布记录改需求时从哪里开始
| 需求 | 改动入口 | 需要同步检查 |
|---|---|---|
| 名称、支持邮箱、积分、套餐 | packages/config/src/index.ts | 公开页、计费契约和验证规则 |
| 首页/定价布局 | modules/public/page.tsx、preview.tsx | 双语、移动导航、禁用支付状态 |
| 登录注册表单 | modules/auth/page.tsx | 邮箱验证、OAuth、Turnstile、回跳 |
| 工作台功能 | modules/workbench/<feature>.tsx | 查询失效、空态和角色入口 |
| 公用 UI 外观 | components/ui、src/styles.css | Base UI 行为、键盘焦点、深色 |
| 新 HTTP 接口 | routes/api.$.ts → server/api.ts | Zod、身份、Origin、所有权 |
| 数据查询和表结构 | packages/db/src 与 migrations | D1 batch、幂等、迁移风险 |
| 部署名字/本地环境 | target-resources.ts / wrangler.jsonc | 目标隔离、配置优先级 |
表中的应用路径相对 apps/web/src；资源名文件完整路径为 packages/cli/src/target-resources.ts。
包的职责
config：产品配置、额度、网关开关、套餐目录；不保存秘密。db：Drizzle schema、D1 查询、原子账本、迁移；SQL 不进入 React 组件。auth：Better Auth 工厂、插件与适配器；应用绑定在server/platform.ts注入。billing：网关契约、签名、金额与 provider 适配器；modules/billing/service.ts组织业务。ai、storage、mail：模型、文件校验与绑定、消息发送/捕获。cli：本地 init、doctor、plan、deploy、verify 和忽略状态。i18n：基础消息、产品覆盖与 Paraglide 项目。ui：当前只提供cn与 table 工具；实际 shadcn 组件已经位于应用components/ui，不是旧的@musemvp/ui/components。shared、testing：可复用的基础与测试支持。
一条业务请求怎么穿过目录
例如文件上传：工作台 files.tsx 调用 lib/client.ts，进入 server/api.ts 完成认证，再由 server/files.ts 组织 @musemvp/storage 与 queries.addFile。界面不得跳过服务端所有权检查，包也不得反向导入应用模块。
TanStack 内部数据读取以 modules/workbench/functions.ts 的 createServerFn 为例；页面守卫位于 routes/$.tsx，但每个 API 仍需检查身份。
不应手写或提交的目录
路由树、src/paraglide、Wrangler 类型和构建产物由工具生成。.env、.dev.vars、.muse 与 .wrangler 含环境或本地状态，按 ignore 处理。排障分享文件前先检查内容，不要打包整个目录。