# mr-addict/punch-next architecture

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

- Interactive diagram: https://gitdiagram.com/mr-addict/punch-next
- Repository: https://github.com/mr-addict/punch-next

## Overview

值班笔记是南京工业大学科协技术开发部使用的值班记录与查阅应用。主要流程是填写笔记、由服务端校验值班时间和内容并写入 MongoDB，再按学期、搜索词和分页查阅笔记；非当前学期或不在值班期时可读取归档笔记。应用也提供学期选择、Markdown 编辑与渲染及帮助页面。归档导出和静态 JSON 的说明来自 README；未展示的客户端请求实现及归档文件位置不作推断。

Main entry points: [`src/components/MarkdownRenderer/MarkdownRenderer.tsx`](https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/MarkdownRenderer.tsx) (Markdown 渲染器), [`src/app/api/notes/route.ts`](https://github.com/mr-addict/punch-next/blob/main/src/app/api/notes/route.ts) (笔记 API), [`src/app/form/components/Form/Form.tsx`](https://github.com/mr-addict/punch-next/blob/main/src/app/form/components/Form/Form.tsx) (笔记表单), [`src/app/view/components/Header/Header.tsx`](https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/Header.tsx) (查阅页头部)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_writing["笔记提交"]
  node_form_page["提交页<br/>[Client.tsx]"]
  node_form["笔记表单<br/>[Form.tsx]"]
end

subgraph group_reading["笔记查阅"]
  node_view_client["查阅页客户端<br/>[Client.tsx]"]
  node_view_body["笔记列表<br/>[Body.tsx]"]
  node_view_header["查阅页头部<br/>[Header.tsx]"]
  node_searchbar["笔记搜索<br/>[Searchbar.tsx]"]
  node_term_selector["学期选择<br/>[TermsSelector.tsx]"]
  node_view_provider["查阅状态<br/>[ViewProvider.tsx]"]
end

subgraph group_services["服务与数据"]
  node_add_api["提交请求客户端<br/>[addNoteApi.ts]"]
  node_notes_api["笔记 API<br/>[route.ts]"]
  node_mongo_notes[("Mongo 笔记库<br/>[notes.ts]")]
  node_mongo_client["Mongo 连接<br/>[clientPromise.ts]"]
  node_get_notes_client["笔记查询客户端<br/>[getNotesApi.ts]"]
  node_get_terms_client["学期查询客户端<br/>[getTermsApi.ts]"]
  node_terms_api["学期 API<br/>[route.ts]"]
  node_terms_service["学期汇总<br/>[getAllTerms.ts]"]
  node_archived_notes["归档笔记读取"]
  node_archived_terms["归档学期读取"]
  node_archive_export["归档导出<br/>[archiveNotes.ts]"]
end

subgraph group_markdown["Markdown 内容"]
  node_markdown_editor["Markdown 编辑器<br/>[MarkdownEditor.tsx]"]
  node_renderer["Markdown 渲染器"]
  node_preview["代码块预览<br/>[Preview.tsx]"]
  node_image["图片渲染<br/>[Img.tsx]"]
  node_anchor["链接渲染<br/>[Anchor.tsx]"]
  node_help["帮助页面<br/>[page.tsx]"]
end

node_visitor(("值班成员"))

node_visitor -->|"打开提交"| node_form_page
node_form_page -->|"显示表单"| node_form
node_form -->|"提交请求"| node_add_api
node_form -->|"编辑内容"| node_markdown_editor
node_add_api -.->|"发送请求"| node_notes_api
node_notes_api -->|"查询或写入"| node_mongo_notes
node_mongo_notes -->|"获取连接"| node_mongo_client
node_notes_api -->|"校验学期"| node_terms_service
node_notes_api -->|"读取归档"| node_archived_notes
node_terms_api -->|"列出学期"| node_terms_service
node_terms_service -->|"读取归档学期"| node_archived_terms
node_view_client -->|"显示列表"| node_view_body
node_view_client -->|"显示筛选"| node_view_header
node_view_header -->|"呈现搜索"| node_searchbar
node_view_header -->|"呈现学期选择"| node_term_selector
node_view_body -->|"读取查阅状态"| node_view_provider
node_view_provider -->|"请求笔记"| node_get_notes_client
node_view_provider -->|"请求学期"| node_get_terms_client
node_get_notes_client -.->|"请求笔记 API"| node_notes_api
node_get_terms_client -.->|"请求学期 API"| node_terms_api
node_markdown_editor -->|"预览内容"| node_renderer
node_renderer -->|"渲染代码块"| node_preview
node_renderer -->|"渲染图片"| node_image
node_renderer -->|"渲染链接"| node_anchor
node_preview -->|"预览 Markdown"| node_renderer
node_help -->|"渲染帮助内容"| node_renderer
node_visitor -->|"查阅笔记"| node_view_client
node_archive_export -.->|"导出归档"| node_mongo_notes

click node_form_page "https://github.com/mr-addict/punch-next/blob/main/src/app/form/Client.tsx"
click node_form "https://github.com/mr-addict/punch-next/blob/main/src/app/form/components/Form/Form.tsx"
click node_markdown_editor "https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownEditor/MarkdownEditor.tsx"
click node_add_api "https://github.com/mr-addict/punch-next/blob/main/src/lib/api/notes/addNoteApi.ts"
click node_notes_api "https://github.com/mr-addict/punch-next/blob/main/src/app/api/notes/route.ts"
click node_mongo_notes "https://github.com/mr-addict/punch-next/blob/main/src/lib/mongodb/notes.ts"
click node_mongo_client "https://github.com/mr-addict/punch-next/blob/main/src/lib/mongodb/clientPromise.ts"
click node_view_client "https://github.com/mr-addict/punch-next/blob/main/src/app/view/Client.tsx"
click node_view_body "https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Body/Body.tsx"
click node_view_header "https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/Header.tsx"
click node_searchbar "https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/components/Searchbar/Searchbar.tsx"
click node_term_selector "https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/components/TermsSelector/TermsSelector.tsx"
click node_view_provider "https://github.com/mr-addict/punch-next/blob/main/src/contexts/View/ViewProvider.tsx"
click node_get_notes_client "https://github.com/mr-addict/punch-next/blob/main/src/lib/api/notes/getNotesApi.ts"
click node_get_terms_client "https://github.com/mr-addict/punch-next/blob/main/src/lib/api/terms/getTermsApi.ts"
click node_terms_api "https://github.com/mr-addict/punch-next/blob/main/src/app/api/terms/route.ts"
click node_terms_service "https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/getAllTerms.ts"
click node_archived_notes "https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/getArchivedNotes.ts"
click node_archived_terms "https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/getArchivedTerms.ts"
click node_renderer "https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/MarkdownRenderer.tsx"
click node_preview "https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/components/Preview/Preview.tsx"
click node_image "https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/components/Img/Img.tsx"
click node_anchor "https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/components/Anchor/Anchor.tsx"
click node_help "https://github.com/mr-addict/punch-next/blob/main/src/app/help/page.tsx"
click node_archive_export "https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/archiveNotes.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_form_page,node_form toneBlue
class node_view_client,node_view_body,node_view_header,node_searchbar,node_term_selector,node_view_provider toneAmber
class node_add_api,node_notes_api,node_mongo_notes,node_mongo_client,node_get_notes_client,node_get_terms_client,node_terms_api,node_terms_service,node_archived_notes,node_archived_terms,node_archive_export toneMint
class node_markdown_editor,node_renderer,node_preview,node_image,node_anchor,node_help toneRose
class node_visitor toneIndigo
```

## Components

### 笔记提交

- [提交页](https://github.com/mr-addict/punch-next/blob/main/src/app/form/Client.tsx): `src/app/form/Client.tsx`
- [笔记表单](https://github.com/mr-addict/punch-next/blob/main/src/app/form/components/Form/Form.tsx): `src/app/form/components/Form/Form.tsx`

### 笔记查阅

- [查阅页客户端](https://github.com/mr-addict/punch-next/blob/main/src/app/view/Client.tsx): `src/app/view/Client.tsx`
- [笔记列表](https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Body/Body.tsx): `src/app/view/components/Body/Body.tsx`
- [查阅页头部](https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/Header.tsx): `src/app/view/components/Header/Header.tsx`
- [笔记搜索](https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/components/Searchbar/Searchbar.tsx): `src/app/view/components/Header/components/Searchbar/Searchbar.tsx`
- [学期选择](https://github.com/mr-addict/punch-next/blob/main/src/app/view/components/Header/components/TermsSelector/TermsSelector.tsx): `src/app/view/components/Header/components/TermsSelector/TermsSelector.tsx`
- [查阅状态](https://github.com/mr-addict/punch-next/blob/main/src/contexts/View/ViewProvider.tsx): `src/contexts/View/ViewProvider.tsx`

### 服务与数据

- [提交请求客户端](https://github.com/mr-addict/punch-next/blob/main/src/lib/api/notes/addNoteApi.ts): `src/lib/api/notes/addNoteApi.ts`
- [笔记 API](https://github.com/mr-addict/punch-next/blob/main/src/app/api/notes/route.ts): `src/app/api/notes/route.ts`
- [Mongo 笔记库](https://github.com/mr-addict/punch-next/blob/main/src/lib/mongodb/notes.ts): `src/lib/mongodb/notes.ts`
- [Mongo 连接](https://github.com/mr-addict/punch-next/blob/main/src/lib/mongodb/clientPromise.ts): `src/lib/mongodb/clientPromise.ts`
- [笔记查询客户端](https://github.com/mr-addict/punch-next/blob/main/src/lib/api/notes/getNotesApi.ts): `src/lib/api/notes/getNotesApi.ts`
- [学期查询客户端](https://github.com/mr-addict/punch-next/blob/main/src/lib/api/terms/getTermsApi.ts): `src/lib/api/terms/getTermsApi.ts`
- [学期 API](https://github.com/mr-addict/punch-next/blob/main/src/app/api/terms/route.ts): `src/app/api/terms/route.ts`
- [学期汇总](https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/getAllTerms.ts): `src/lib/notes/getAllTerms.ts`
- [归档笔记读取](https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/getArchivedNotes.ts): `src/lib/notes/getArchivedNotes.ts`
- [归档学期读取](https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/getArchivedTerms.ts): `src/lib/notes/getArchivedTerms.ts`
- [归档导出](https://github.com/mr-addict/punch-next/blob/main/src/lib/notes/archiveNotes.ts): `src/lib/notes/archiveNotes.ts`

### Markdown 内容

- [Markdown 编辑器](https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownEditor/MarkdownEditor.tsx): `src/components/MarkdownEditor/MarkdownEditor.tsx`
- [Markdown 渲染器](https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/MarkdownRenderer.tsx): `src/components/MarkdownRenderer/MarkdownRenderer.tsx`
- [代码块预览](https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/components/Preview/Preview.tsx): `src/components/MarkdownRenderer/components/Preview/Preview.tsx`
- [图片渲染](https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/components/Img/Img.tsx): `src/components/MarkdownRenderer/components/Img/Img.tsx`
- [链接渲染](https://github.com/mr-addict/punch-next/blob/main/src/components/MarkdownRenderer/components/Anchor/Anchor.tsx): `src/components/MarkdownRenderer/components/Anchor/Anchor.tsx`
- [帮助页面](https://github.com/mr-addict/punch-next/blob/main/src/app/help/page.tsx): `src/app/help/page.tsx`

### Other components

- **值班成员**

## Connections

- 值班成员 → 提交页: 打开提交
- 提交页 → 笔记表单: 显示表单 (evidence: `src/app/form/Client.tsx`)
- 笔记表单 → 提交请求客户端: 提交请求 (evidence: `src/app/form/components/Form/Form.tsx`)
- 笔记表单 → Markdown 编辑器: 编辑内容 (evidence: `src/app/form/components/Form/Form.tsx`)
- 提交请求客户端 → 笔记 API: 发送请求
- 笔记 API → Mongo 笔记库: 查询或写入 (evidence: `src/app/api/notes/route.ts`)
- Mongo 笔记库 → Mongo 连接: 获取连接 (evidence: `src/lib/mongodb/notes.ts`)
- 笔记 API → 学期汇总: 校验学期 (evidence: `src/app/api/notes/route.ts`)
- 笔记 API → 归档笔记读取: 读取归档 (evidence: `src/app/api/notes/route.ts`)
- 学期 API → 学期汇总: 列出学期 (evidence: `src/app/api/terms/route.ts`)
- 学期汇总 → 归档学期读取: 读取归档学期 (evidence: `src/lib/notes/getAllTerms.ts`)
- 查阅页客户端 → 笔记列表: 显示列表 (evidence: `src/app/view/Client.tsx`)
- 查阅页客户端 → 查阅页头部: 显示筛选 (evidence: `src/app/view/Client.tsx`)
- 查阅页头部 → 笔记搜索: 呈现搜索 (evidence: `src/app/view/components/Header/Header.tsx`)
- 查阅页头部 → 学期选择: 呈现学期选择 (evidence: `src/app/view/components/Header/Header.tsx`)
- 笔记列表 → 查阅状态: 读取查阅状态 (evidence: `src/app/view/components/Body/Body.tsx`)
- 查阅状态 → 笔记查询客户端: 请求笔记 (evidence: `src/contexts/View/ViewProvider.tsx`)
- 查阅状态 → 学期查询客户端: 请求学期 (evidence: `src/contexts/View/ViewProvider.tsx`)
- 笔记查询客户端 → 笔记 API: 请求笔记 API
- 学期查询客户端 → 学期 API: 请求学期 API
- Markdown 编辑器 → Markdown 渲染器: 预览内容 (evidence: `src/components/MarkdownEditor/MarkdownEditor.tsx`)
- Markdown 渲染器 → 代码块预览: 渲染代码块 (evidence: `src/components/MarkdownRenderer/MarkdownRenderer.tsx`)
- Markdown 渲染器 → 图片渲染: 渲染图片 (evidence: `src/components/MarkdownRenderer/MarkdownRenderer.tsx`)
- Markdown 渲染器 → 链接渲染: 渲染链接 (evidence: `src/components/MarkdownRenderer/MarkdownRenderer.tsx`)
- 代码块预览 → Markdown 渲染器: 预览 Markdown (evidence: `src/components/MarkdownRenderer/components/Preview/Preview.tsx`)
- 帮助页面 → Markdown 渲染器: 渲染帮助内容 (evidence: `src/app/help/page.tsx`)
- 值班成员 → 查阅页客户端: 查阅笔记
- 归档导出 → Mongo 笔记库: 导出归档
