# liuxiaopai-ai/raphael-publish architecture

> Architecture diagram of the GitHub repository liuxiaopai-ai/raphael-publish, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liuxiaopai-ai/raphael-publish
- Repository: https://github.com/liuxiaopai-ai/raphael-publish

## Overview

##### 项目类型与目的（先定“边界”，决定画什么）
从 README 与文件树看，这是一个 **纯前端静态 Web 应用**（React + Vite + TS + Tailwind），核心目标是：
- 提供一个 **Markdown 编辑 + 实时预览** 的排版工具
- 支持 **富文本/截图粘贴 → 自动转 Markdown**（“魔法粘贴”）
- 提供 **多主题渲染**（30 套主题）
- 输出面向 **微信公众号粘贴环境**的兼容 HTML（`wechatCompat`：DOM 重塑、图片 Base64 等）
- 支持 **导出 PDF/HTML**
部署方式是 **构建 dist 后静态托管（GitHub Pages）**，没有传统后端服务与数据库。

因此系统设计图的主干应是：
- “浏览器端应用内部模块架构 + 关键数据流（粘贴 → Markdown → 渲染 → 兼容处理 → 复制/导出）”
- “CI/CD 与静态托管（GitHub Actions → Pages）”
而不是“前后端/数据库”那种经典图。

##### 从文件结构提炼可画的模块边界（按目录拆组件）
你可以把系统拆成 4 层来画（越上层越接近 UI，越下层越接近引擎/算法）：

##### 交付与运行时边界（Deployment / Runtime）
- `.github/workflows/ci.yml`：CI（lint/test/build）
- `.github/workflows/deploy.yml`：部署到 GitHub Pages（推 dist）
- `public/CNAME`：自定义域名（publish.raphael.app）
- `index.html`、`vite.config.ts`：前端入口与构建配置

##### App Shell / 页面编排层（React 页面与布局）
- `src/main.tsx`：React 挂载入口
- `src/App.tsx`：应用顶层容器（状态提升/子面板组合通常在这里发生）
- `src/index.css`、`tailwind.config.js`、`postcss.config.js`：全局样式与 Tailwind 管线

##### UI 组件层（可直接映射到图中的“子系统”）
- `src/components/EditorPanel.tsx`：编辑器面板（输入 Markdown、粘贴处理入口）
- `src/components/PreviewPanel.tsx`：预览面板（把 Markdown 渲染成 HTML/主题化/微信兼容）
- `src/components/ThemeSelector.tsx`：主题选择器
- `src/components/Toolbar.tsx`：导出/复制/视口切换等动作入口
- `src/components/DeviceFrame.tsx`：多端预览外壳（手机/平板/桌面尺寸）
- `src/components/Header.tsx`：顶部导航/品牌区

##### 核心引擎与适配层（这是“架构图里最该细分”的部分）
- `src/lib/markdown.ts`：Markdown 解析/渲染（markdown-it、highlight.js）
- `src/lib/htmlToMarkdown.ts`：富文本 HTML → Markdown（turndown；“魔法粘贴”核心）
- `src/lib/wechatCompat.ts`：微信兼容引擎（DOM 重塑、表格/列表修复、多图布局、图片处理等）
- `src/lib/themes/*`：主题体系（classic/modern/extra + types + index）
- `src/defaultContent.ts`：默认示例内容（用于初始化）

测试与质量：
- `src/lib/*.test.ts` + `vitest.config.ts`：单元测试（markdown/htmlToMarkdown）
- `e2e/app.spec.ts` + `playwright.config.ts`：端到端测试（关键流程回归）

##### 读 README 提炼“关键数据流/用例”，用于画箭头
README 里最关键的交互流是 4 条，建议每条都在图中用箭头画出来：

##### 魔法粘贴流
Clipboard HTML / 富文本 / 图片 → `EditorPanel` → `htmlToMarkdown` → Markdown state → `PreviewPanel`

##### 主题渲染流
ThemeSelector → 选择 Theme config（`themes/*`）→ PreviewPanel 渲染样式（Tailwind/CSS + theme tokens）

##### 复制到公众号流（最重要的“目标输出”）
Markdown → `markdown.ts` 渲染 HTML → `wechatCompat.ts` 做 DOM/样式/结构兼容处理 → 图片 Base64 内联 → Clipboard 写入（最终粘贴到公众号后台）

##### 导出流
Markdown/HTML → HTML 生成 → `html2pdf.js` 导出 PDF 或导出 HTML 文件 → 下载到本地

这些流决定了图中箭头方向：**输入（用户/剪贴板）→ 转换引擎 → 状态 → 渲染/适配 → 输出（预览/剪贴板/文件）**。

##### 建议画 3 张“互补”的架构图（每张目的不同）
为了“最准确+最可维护”，不要试图一张图塞所有细节。建议 3 张：

##### 图 1：Context / Deployment（C4 Level 1-2 风格）
目的：回答“系统部署在哪里、依赖哪些外部东西”。
元素建议：
- 用户浏览器（含剪贴板能力）
- Raphael Publish（静态站点：GitHub Pages / 任意 CDN）
- GitHub Actions（CI + Deploy）
- 外部库（可作为注释：markdown-it, turndown, highlight.js, html2pdf.js）
箭头：
- 用户 ↔ 静态站点（HTTP）
- GitHub Actions → Pages（发布 dist）
- 用户 ↔ Clipboard（读/写）

目的：回答“React 应用内部有哪些子系统，职责如何分”。
建议把应用画成一个大框 `Raphael Publish (React SPA)`，内部拆：
- App Shell（App/main）
- UI：EditorPanel / PreviewPanel / Toolbar / ThemeSelector / DeviceFrame
- Core libs：htmlToMarkdown / markdown renderer / wechatCompat / themes
- Assets/Styles：Tailwind/CSS、defaultContent
箭头体现依赖方向（UI → lib；ThemeSelector → themes；PreviewPanel → markdown + wechatCompat）。

##### 图 3：Sequence / Dataflow（关键路径时序图）
目的：回答“点击/粘贴后到底发生了什么”。
至少画两条时序：
- 粘贴富文本 → Markdown → 预览更新
- 点击“复制到公众号” → HTML 生成 → wechatCompat → 图片 Base64 → clipboard.write

##### 针对该项目（纯前端工具）的“组件划分”画法要点
因为没有后端，架构准确性的关键在于把**浏览器能力与前端引擎**画清楚：

##### 必须显式画出来的“外部/边界能力”
- Clipboard（读：paste 事件、写：复制）
- File Download（导出 HTML/PDF）
- DOM/Rendering（预览区的实际渲染容器）
- 静态托管（GitHub Pages）

##### 必须显式区分的“内部引擎”
- HTML→Markdown（turndown）：输入是富文本 DOM/HTML
- Markdown→HTML（markdown-it + highlight.js）：输入是 Markdown 字符串
- WeChat 兼容处理（wechatCompat）：输入是 HTML DOM/字符串，输出是“可粘贴的兼容 HTML”（含图片 Base64、表格/列表重构、多图布局）

这三者是本项目的“核心差异化”，在图上要比普通 UI 组件更突出（例如用不同颜色或更粗边框）。

##### 清晰标签（建议统一命名）
- 用文件/目录名做括号注释：例如
`WeChat Compatibility Engine (src/lib/wechatCompat.ts)`
- 主题模块：`Theme Pack (src/lib/themes/*)`

##### 箭头（建议标注数据形态）
在箭头旁标注数据类型，会让图“工程上更可信”：
- `Clipboard HTML / Rich Text`
- `Markdown string`
- `HTML string / DOM`
- `Base64 images`
- `PDF blob / HTML file`

##### 颜色/形状（建议约定）
- 蓝色：UI/React components
- 紫色：core conversion engines（htmlToMarkdown/markdown/wechatCompat）
- 绿色：external browser capabilities（Clipboard/Download）
- 灰色：build/test/deploy toolchain（Vite/Vitest/Playwright/GitHub Actions）

##### 把“尽量细分组件”具体化：建议你在图里拆到这个粒度
基于现有目录，不要只画“Editor/Preview”，可以进一步拆“动作”子模块（即使它们在代码里未必是单独文件，也能作为逻辑组件存在于图上）：
- EditorPanel 内部逻辑块（图上可标为子框）：
- Paste Handler（富文本/图片）
- Markdown State Manager（React state）
- PreviewPanel 内部逻辑块：
- Markdown Renderer (markdown-it)
- Syntax Highlight (highlight.js)
- Theme Styler (themes)
- WeChat Compat Post-Processor (wechatCompat)
- Toolbar 动作块：
- Copy-to-WeChat Action
- Export PDF (html2pdf.js)
- Export HTML
- Viewport Switch (DeviceFrame)

测试/质量也建议作为侧边模块列出：
- Unit Tests (Vitest): markdown/htmlToMarkdown
- E2E (Playwright): app.spec.ts
- CI Pipeline: ci.yml runs tests + build

##### 快速可复用的图示骨架（你可以直接照着画）
**最核心的一张“模块+数据流图”**可以按以下布局（从左到右）：

- 左侧：User + Clipboard（外部）
- 中间左：EditorPanel（粘贴/输入）
- 中间：Markdown state（App 层状态）
- 中间右：Preview pipeline（markdown renderer → theme → wechatCompat）
- 右侧：Outputs（Preview DOM、Clipboard write、PDF/HTML download）
- 顶部或底部：Tooling lane（Vite build → dist → GitHub Pages；Vitest/Playwright）

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External / Context Layer
  %% =========================
  subgraph "External Context (Browser + Hosting)"
    U["User"]:::external
    B["Browser Runtime"]:::external
    CB[("Clipboard API\n(read paste / write html)")]:::browser
    DL[("File Download\n(PDF / HTML)")]:::browser
    DOM["Preview DOM / Rendering Container"]:::browser

    GH["GitHub Repository"]:::external
    GA["GitHub Actions"]:::tooling
    GHP["GitHub Pages (Static Hosting)"]:::external
    CDN["Custom Domain"]:::external
  end

  %% =========================
  %% Build / Test / Deploy
  %% =========================
  subgraph "CI / CD Toolchain"
    CI["CI Pipeline\n(lint / test / build)"]:::tooling
    DEP["Deploy Pipeline\n(publish dist)"]:::tooling

    VITEST["Vitest Runner"]:::tooling
    PLAY["Playwright Runner"]:::tooling
    VITE["Vite Build"]:::tooling

    VITCFG["vitest.config.ts"]:::tooling
    PLCFG["playwright.config.ts"]:::tooling
    VITECFG["vite.config.ts"]:::tooling
    IDXHTML["index.html"]:::tooling
    CNAME["public/CNAME"]:::tooling
  end

  GH -->|"triggers"| GA
  GA -->|"runs"| CI
  GA -->|"runs"| DEP
  CI -->|"unit_tests"| VITEST
  CI -->|"e2e_tests"| PLAY
  CI -->|"build"| VITE
  VITE -->|"uses"| VITECFG
  VITE -->|"bundles"| IDXHTML
  DEP -->|"deploys_dist"| GHP
  GHP -->|"serves"| B
  GHP -->|"uses"| CNAME
  CNAME -->|"maps_domain"| CDN

  %% =========================
  %% App Runtime (React SPA)
  %% =========================
  subgraph "Raphael Publish (React SPA)"
    MAIN["React Mount Entry"]:::app
    APP["App Shell / Top-level Container"]:::app
    STY["Global Styles (Tailwind entry)"]:::styleCls
    TW["tailwind.config.js"]:::styleCls
    PC["postcss.config.js"]:::styleCls

    DC["Default Initial Content"]:::data

    subgraph "UI Components"
      HDR["Header"]:::ui
      DF["Device Frame\n(viewport shell)"]:::ui

      subgraph "Editor Side"
        EP["Editor Panel"]:::ui
        PH["Paste Handler\n(rich text / images)"]:::ui
        MSM["Markdown State Manager\n(React state)"]:::state
      end

      subgraph "Preview Side"
        PP["Preview Panel"]:::ui
        PR["Preview Pipeline Controller"]:::ui
      end

      TS["Theme Selector"]:::ui
      TB["Toolbar"]:::ui
    end

    subgraph "Core Engines / Adapters"
      H2M["HTML → Markdown Converter\n(Magic Paste)"]:::engine
      M2H["Markdown → HTML Renderer"]:::engine
      HL["Syntax Highlight"]:::engine
      WE["WeChat Compatibility Engine\n(DOM reshape + images)"]:::engine

      subgraph "Theme Pack"
        THDIR["Themes Directory"]:::theme
        THIDX["Theme Registry / Exports"]:::theme
        THT["Theme Types"]:::theme
        THC["Classic Themes"]:::theme
        THM["Modern Themes"]:::theme
        THE["Extra Themes"]:::theme
      end
    end

    subgraph "Quality (Tests)"
      MT["markdown.test.ts"]:::tooling
      HT["htmlToMarkdown.test.ts"]:::tooling
      E2E["e2e/app.spec.ts"]:::tooling
    end
  end

  %% SPA wiring
  B -->|"loads_spa"| MAIN
  MAIN -->|"mounts"| APP
  APP -->|"initializes"| DC
  APP -->|"applies"| STY
  STY -->|"configured_by"| TW
  STY -->|"processed_by"| PC

  APP -->|"composes"| HDR
  APP -->|"composes"| DF
  DF -->|"contains"| EP
  DF -->|"contains"| PP
  APP -->|"composes"| TS
  APP -->|"composes"| TB
  EP -->|"uses"| PH
  EP -->|"updates"| MSM
  PP -->|"reads"| MSM
  PP -->|"drives"| PR
  PR -->|"renders"| DOM

  %% =========================
  %% Key Dataflows
  %% =========================

  %% (1) Magic Paste flow
  U -->|"paste_event"| CB
  CB -->|"Clipboard_HTML/Rich_Text"| PH
  PH -->|"calls"| H2M
  H2M -->|"Markdown_string"| MSM

  %% (2) Theme rendering flow
  TS -->|"selects_theme"| THIDX
  THIDX -->|"resolves"| THC
  THIDX -->|"resolves"| THM
  THIDX -->|"resolves"| THE
  THIDX -->|"uses"| THT
  THDIR -->|"exports"| THIDX
  PR -->|"applies_theme_tokens"| THIDX

  %% (3) Copy-to-WeChat flow (core output)
  PR -->|"Markdown_string"| M2H
  M2H -->|"HTML_string/DOM"| HL
  HL -->|"HTML_string/DOM"| WE
  WE -->|"compat_HTML+Base64_images"| CB
  TB -->|"copy_to_wechat"| WE
  CB -->|"clipboard_write(html)"| U

  %% (4) Export flow
  TB -->|"export_html"| DL
  TB -->|"export_pdf(html2pdf.js)"| DL
  PR -->|"HTML_string"| DL

  %% (Preview rendering flow)
  MSM -->|"Markdown_string"| M2H
  M2H -->|"HTML_string/DOM"| PR
  PR -->|"post_process"| WE
  WE -->|"final_preview_HTML"| DOM

  %% =========================
  %% Test relations
  %% =========================
  VITEST -->|"runs"| MT
  VITEST -->|"runs"| HT
  PLAY -->|"runs"| E2E

  MT -->|"tests"| M2H
  HT -->|"tests"| H2M
  E2E -->|"covers"| APP

  %% =========================
  %% Click Events (from mappings)
  %% =========================
  click CI "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/.github/workflows/ci.yml"
  click DEP "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/.github/workflows/deploy.yml"
  click CNAME "https://github.com/liuxiaopai-ai/raphael-publish/tree/main/public/CNAME"
  click IDXHTML "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/index.html"
  click VITECFG "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/vite.config.ts"
  click MAIN "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/main.tsx"
  click APP "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/App.tsx"
  click STY "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/index.css"
  click TW "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/tailwind.config.js"
  click PC "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/postcss.config.js"
  click EP "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/components/EditorPanel.tsx"
  click PP "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/components/PreviewPanel.tsx"
  click TS "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/components/ThemeSelector.tsx"
  click TB "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/components/Toolbar.tsx"
  click DF "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/components/DeviceFrame.tsx"
  click HDR "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/components/Header.tsx"
  click DC "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/defaultContent.ts"
  click M2H "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/markdown.ts"
  click MT "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/markdown.test.ts"
  click H2M "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/htmlToMarkdown.ts"
  click HT "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/htmlToMarkdown.test.ts"
  click WE "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/wechatCompat.ts"
  click THDIR "https://github.com/liuxiaopai-ai/raphael-publish/tree/main/src/lib/themes/"
  click THC "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/themes/classic.ts"
  click THM "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/themes/modern.ts"
  click THE "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/themes/extra.ts"
  click THIDX "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/themes/index.ts"
  click THT "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/src/lib/themes/types.ts"
  click VITCFG "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/vitest.config.ts"
  click E2E "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/e2e/app.spec.ts"
  click PLCFG "https://github.com/liuxiaopai-ai/raphael-publish/blob/main/playwright.config.ts"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
  classDef browser fill:#D1FAE5,stroke:#059669,color:#064E3B,stroke-width:1px
  classDef tooling fill:#F3F4F6,stroke:#4B5563,color:#111827,stroke-width:1px,stroke-dasharray:4 2
  classDef app fill:#DBEAFE,stroke:#2563EB,color:#0F172A,stroke-width:1px
  classDef ui fill:#BFDBFE,stroke:#1D4ED8,color:#0F172A,stroke-width:1px
  classDef state fill:#93C5FD,stroke:#1D4ED8,color:#0B1220,stroke-width:2px
  classDef engine fill:#E9D5FF,stroke:#7C3AED,color:#2E1065,stroke-width:2px
  classDef theme fill:#DDD6FE,stroke:#6D28D9,color:#1F1147,stroke-width:1px
  classDef styleCls fill:#CFFAFE,stroke:#0891B2,color:#083344,stroke-width:1px
  classDef data fill:#FEF9C3,stroke:#CA8A04,color:#713F12,stroke-width:1px
```
