> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magic-resume.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 架构总览

> Magic Resume 代码库的高层地图 —— workspace、数据流，以及"当我要改 X 时该去哪儿"。

Magic Resume 围绕四个反复出现的核心思想构建：

1. **简历是一个带类型的值。** 一份 Zod Schema（在 `@magic-resume/resume-schema` 里）定义了简历的形状。Web 应用、MCP 服务器、AI agent 全都读写这个统一形状。
2. **浏览器即数据库。** 自托管模式下没有服务端持久化。IndexedDB（`MagicResumeDB`）就是真源。云端同步只是一个可选的、单向推送到 Core API 的过程。
3. **鉴权由 feature flag 控制。** `NEXT_PUBLIC_APP_MODE` 在构建时决定 Clerk middleware 和云端同步层是否加载。两种模式跑的是同一套 UI。
4. **编辑就是 Patch。** MCP 工具通过 JSON Patch（`fast-json-patch`）来改简历，写入存储前会先用 Schema 校验。Web 编辑器产生的也是 Patch —— 同一条代码路径。

## 数据流速览

```
                ┌───────────────┐
   用户输入  ─▶│   编辑器 (UI) │
                └───────┬───────┘
                        │ Zustand action
                        ▼
                ┌───────────────┐     写     ┌────────────┐
                │ useResumeStore├──────────▶│ IndexedDB  │
                └───────┬───────┘            └────────────┘
                        │ （仅云端模式）
                        ▼
                ┌───────────────┐    PATCH   ┌────────────┐
                │  httpClient   ├──────────▶│  Core API  │
                └───────────────┘            └────────────┘

   AI 工具 ────▶ @magic-resume/mcp ──▶ Core API（用 PAT 鉴权）
```

## 该去哪里看

<CardGroup>
  <Card title="单仓结构" href="/zh/architecture/monorepo" />

  <Card title="部署模式" href="/zh/architecture/deployment-modes" />

  <Card title="状态管理" href="/zh/architecture/state-management" />

  <Card title="HTTP 客户端" href="/zh/architecture/http-clients" />

  <Card title="简历 Schema" href="/zh/architecture/resume-schema" />

  <Card title="模板系统" href="/zh/architecture/templates" />
</CardGroup>