# cchhaan/next-mdx-blog architecture

> Architecture diagram of the GitHub repository cchhaan/next-mdx-blog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cchhaan/next-mdx-blog
- Repository: https://github.com/cchhaan/next-mdx-blog

## Overview

这是一个可配置的 Next.js MDX 个人博客：访客浏览四类内容及分类、标签、归档，并可搜索和评论；管理员可登录管理内容、设置站点及上传图片。另有练习题生成、判分与历史记录，以及预留的 AI 笔记问答。图中按产品能力归组；README 描述了部分未采样模块，相关内部调用仅在有明确证据时连线。

Main entry points: [`src/lib/admin.ts`](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/admin.ts) (管理员认证), [`src/components/practice/practice-client.tsx`](https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/practice/practice-client.tsx) (练习页面), [`src/app/admin`](https://github.com/cchhaan/next-mdx-blog/tree/main/src/app/admin) (管理界面), [`src/app`](https://github.com/cchhaan/next-mdx-blog/tree/main/src/app) (内容与索引页)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_publishing["内容浏览"]
  node_content_pages["内容与索引页"]
  node_content_store["MDX 内容加载<br/>[content.ts]"]
  node_post_detail["文章详情<br/>[post-detail.tsx]"]
  node_site_config["站点默认配置<br/>[site.config.ts]"]
end

subgraph group_discovery["检索与互动"]
  node_search_ui["搜索弹窗<br/>[search-modal.tsx]"]
  node_search_route["搜索接口<br/>[route.ts]"]
  node_search_logic["加权搜索<br/>[search.ts]"]
  node_giscus["Giscus 评论<br/>[giscus.tsx]"]
end

subgraph group_management["后台管理"]
  node_admin_ui["管理界面"]
  node_login_route["登录接口<br/>[route.ts]"]
  node_admin_auth["管理员认证<br/>[admin.ts]"]
  node_content_route["内容管理接口<br/>[route.ts]"]
  node_content_admin["内容写入管理<br/>[content-admin.ts]"]
  node_settings_ui["站点设置面板<br/>[settings-panel.tsx]"]
  node_settings_route["设置接口<br/>[route.ts]"]
  node_settings_lib["设置读写<br/>[settings.ts]"]
  node_upload_route["图片上传接口<br/>[route.ts]"]
  node_file_api["图片读取接口<br/>[route.ts]"]
  node_file_store[("文件存储<br/>[db.ts]")]
end

subgraph group_practice["练习与问答"]
  node_practice_ui["练习页面"]
  node_practice_generate["题目生成接口<br/>[route.ts]"]
  node_practice_grade["答案判分接口<br/>[route.ts]"]
  node_practice_history["练习记录接口<br/>[route.ts]"]
  node_practice_detail["记录详情接口<br/>[route.ts]"]
  node_practice_ai["练习生成与判分<br/>[practice.ts]"]
  node_practice_db[("练习记录存储<br/>[practice-db.ts]")]
  node_chat_route["问答接口<br/>[route.ts]"]
  node_ai_index["问答入口<br/>[index.ts]"]
  node_ai_retriever["笔记检索预留<br/>[retriever.ts]"]
  node_ai_client["模型客户端<br/>[client.ts]"]
end

node_visitor(("访客"))
node_github_discussions(("GitHub Discussions"))

node_visitor -->|"浏览"| node_content_pages
node_content_pages -->|"读取内容"| node_content_store
node_content_pages -->|"读取默认值"| node_site_config
node_content_pages -->|"呈现详情"| node_post_detail
node_visitor -->|"搜索"| node_search_ui
node_search_ui -->|"请求查询"| node_search_route
node_search_route -->|"加载文章"| node_content_store
node_search_route -->|"执行检索"| node_search_logic
node_post_detail -.->|"呈现评论"| node_giscus
node_giscus -.->|"加载评论"| node_github_discussions
node_admin_ui -->|"提交口令"| node_login_route
node_login_route -->|"验证并设会话"| node_admin_auth
node_admin_ui -->|"保存或删除"| node_content_route
node_content_route -->|"检查登录"| node_admin_auth
node_content_route -->|"写入或删除"| node_content_admin
node_admin_ui -->|"读取或保存"| node_settings_route
node_settings_route -->|"检查登录"| node_admin_auth
node_settings_route -->|"读写设置"| node_settings_lib
node_admin_ui -->|"上传图片"| node_upload_route
node_upload_route -->|"检查登录"| node_admin_auth
node_upload_route -->|"保存文件"| node_file_store
node_file_api -->|"读取文件"| node_file_store
node_visitor -->|"使用练习"| node_practice_ui
node_practice_ui -->|"生成题目"| node_practice_generate
node_practice_generate -->|"检查登录"| node_admin_auth
node_practice_generate -->|"获取今日题目"| node_practice_ai
node_practice_ui -->|"提交答案"| node_practice_grade
node_practice_grade -->|"检查登录"| node_admin_auth
node_practice_grade -->|"提交并判分"| node_practice_ai
node_practice_ui -->|"查看历史"| node_practice_history
node_practice_history -->|"检查登录"| node_admin_auth
node_practice_history -->|"读取记录"| node_practice_db
node_practice_ui -->|"查看记录详情"| node_practice_detail
node_practice_detail -->|"检查登录"| node_admin_auth
node_practice_detail -->|"读取记录与答案"| node_practice_db
node_visitor -.->|"提问"| node_chat_route
node_chat_route -->|"转交问题"| node_ai_index
node_ai_index -.->|"预留检索"| node_ai_retriever
node_ai_index -.->|"预留模型调用"| node_ai_client

click node_content_pages "https://github.com/cchhaan/next-mdx-blog/tree/main/src/app"
click node_content_store "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/content.ts"
click node_post_detail "https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/post-detail.tsx"
click node_site_config "https://github.com/cchhaan/next-mdx-blog/blob/main/src/site.config.ts"
click node_search_ui "https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/search/search-modal.tsx"
click node_search_route "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/search/route.ts"
click node_search_logic "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/search.ts"
click node_giscus "https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/giscus.tsx"
click node_admin_ui "https://github.com/cchhaan/next-mdx-blog/tree/main/src/app/admin"
click node_login_route "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/login/route.ts"
click node_admin_auth "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/admin.ts"
click node_content_route "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/content/route.ts"
click node_content_admin "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/content-admin.ts"
click node_settings_ui "https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/settings/settings-panel.tsx"
click node_settings_route "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/settings/route.ts"
click node_settings_lib "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/settings.ts"
click node_upload_route "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/upload/route.ts"
click node_file_api "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/files/%5Bkey%5D/route.ts"
click node_file_store "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/db.ts"
click node_practice_ui "https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/practice/practice-client.tsx"
click node_practice_generate "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/generate/route.ts"
click node_practice_grade "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/%5Bid%5D/grade/route.ts"
click node_practice_history "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/history/route.ts"
click node_practice_detail "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/%5Bid%5D/route.ts"
click node_practice_ai "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/practice.ts"
click node_practice_db "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/practice-db.ts"
click node_chat_route "https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/chat/route.ts"
click node_ai_index "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/index.ts"
click node_ai_retriever "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/retriever.ts"
click node_ai_client "https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content_pages,node_content_store,node_post_detail,node_site_config toneBlue
class node_search_ui,node_search_route,node_search_logic,node_giscus toneAmber
class node_admin_ui,node_login_route,node_admin_auth,node_content_route,node_content_admin,node_settings_ui,node_settings_route,node_settings_lib,node_upload_route,node_file_api,node_file_store toneMint
class node_practice_ui,node_practice_generate,node_practice_grade,node_practice_history,node_practice_detail,node_practice_ai,node_practice_db,node_chat_route,node_ai_index,node_ai_retriever,node_ai_client toneRose
class node_visitor,node_github_discussions toneIndigo
```

## Components

### 内容浏览

- [内容与索引页](https://github.com/cchhaan/next-mdx-blog/tree/main/src/app): `src/app`
- [MDX 内容加载](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/content.ts): `src/lib/content.ts`
- [文章详情](https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/post-detail.tsx): `src/components/post-detail.tsx`
- [站点默认配置](https://github.com/cchhaan/next-mdx-blog/blob/main/src/site.config.ts): `src/site.config.ts`

### 检索与互动

- [搜索弹窗](https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/search/search-modal.tsx): `src/components/search/search-modal.tsx`
- [搜索接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/search/route.ts): `src/app/api/search/route.ts`
- [加权搜索](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/search.ts): `src/lib/search.ts`
- [Giscus 评论](https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/giscus.tsx): `src/components/giscus.tsx`

### 后台管理

- [管理界面](https://github.com/cchhaan/next-mdx-blog/tree/main/src/app/admin): `src/app/admin`
- [登录接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/login/route.ts): `src/app/api/admin/login/route.ts`
- [管理员认证](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/admin.ts): `src/lib/admin.ts`
- [内容管理接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/content/route.ts): `src/app/api/admin/content/route.ts`
- [内容写入管理](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/content-admin.ts): `src/lib/content-admin.ts`
- [站点设置面板](https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/settings/settings-panel.tsx): `src/components/settings/settings-panel.tsx`
- [设置接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/settings/route.ts): `src/app/api/admin/settings/route.ts`
- [设置读写](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/settings.ts): `src/lib/settings.ts`
- [图片上传接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/admin/upload/route.ts): `src/app/api/admin/upload/route.ts`
- [图片读取接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/files/%5Bkey%5D/route.ts): `src/app/api/files/[key]/route.ts`
- [文件存储](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/db.ts): `src/lib/db.ts`

### 练习与问答

- [练习页面](https://github.com/cchhaan/next-mdx-blog/blob/main/src/components/practice/practice-client.tsx): `src/components/practice/practice-client.tsx`
- [题目生成接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/generate/route.ts): `src/app/api/practice/generate/route.ts`
- [答案判分接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/%5Bid%5D/grade/route.ts): `src/app/api/practice/[id]/grade/route.ts`
- [练习记录接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/history/route.ts): `src/app/api/practice/history/route.ts`
- [记录详情接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/practice/%5Bid%5D/route.ts): `src/app/api/practice/[id]/route.ts`
- [练习生成与判分](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/practice.ts): `src/lib/ai/practice.ts`
- [练习记录存储](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/practice-db.ts): `src/lib/practice-db.ts`
- [问答接口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [问答入口](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/index.ts): `src/lib/ai/index.ts`
- [笔记检索预留](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/retriever.ts): `src/lib/ai/retriever.ts`
- [模型客户端](https://github.com/cchhaan/next-mdx-blog/blob/main/src/lib/ai/client.ts): `src/lib/ai/client.ts`

### Other components

- **访客**
- **GitHub Discussions**

## Connections

- 访客 → 内容与索引页: 浏览
- 内容与索引页 → MDX 内容加载: 读取内容
- 内容与索引页 → 站点默认配置: 读取默认值
- 内容与索引页 → 文章详情: 呈现详情
- 访客 → 搜索弹窗: 搜索
- 搜索弹窗 → 搜索接口: 请求查询
- 搜索接口 → MDX 内容加载: 加载文章
- 搜索接口 → 加权搜索: 执行检索
- 文章详情 → Giscus 评论: 呈现评论
- Giscus 评论 → GitHub Discussions: 加载评论
- 管理界面 → 登录接口: 提交口令
- 登录接口 → 管理员认证: 验证并设会话
- 管理界面 → 内容管理接口: 保存或删除
- 内容管理接口 → 管理员认证: 检查登录
- 内容管理接口 → 内容写入管理: 写入或删除
- 管理界面 → 设置接口: 读取或保存
- 设置接口 → 管理员认证: 检查登录
- 设置接口 → 设置读写: 读写设置
- 管理界面 → 图片上传接口: 上传图片
- 图片上传接口 → 管理员认证: 检查登录
- 图片上传接口 → 文件存储: 保存文件
- 图片读取接口 → 文件存储: 读取文件
- 访客 → 练习页面: 使用练习
- 练习页面 → 题目生成接口: 生成题目
- 题目生成接口 → 管理员认证: 检查登录
- 题目生成接口 → 练习生成与判分: 获取今日题目
- 练习页面 → 答案判分接口: 提交答案
- 答案判分接口 → 管理员认证: 检查登录
- 答案判分接口 → 练习生成与判分: 提交并判分
- 练习页面 → 练习记录接口: 查看历史
- 练习记录接口 → 管理员认证: 检查登录
- 练习记录接口 → 练习记录存储: 读取记录
- 练习页面 → 记录详情接口: 查看记录详情
- 记录详情接口 → 管理员认证: 检查登录
- 记录详情接口 → 练习记录存储: 读取记录与答案
- 访客 → 问答接口: 提问
- 问答接口 → 问答入口: 转交问题
- 问答入口 → 笔记检索预留: 预留检索
- 问答入口 → 模型客户端: 预留模型调用