# andyhuo520/aetherviz-master architecture

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

- Interactive diagram: https://gitdiagram.com/andyhuo520/aetherviz-master
- Repository: https://github.com/andyhuo520/aetherviz-master

## Overview

##### 项目类型与目的（从 README + 文件树推断）
**AetherViz Master** 本质上不是传统“有后端/有数据库”的 Web App，而是一个 **AI 驱动的教学可视化 HTML 生成器（Claude Skill / 模板化生成工具）**：

- **生成阶段（Design-time / Build-time）**：用户在 *Claude Code*（或 Claude 的 Skill 机制）里输入“教学主题”，LLM 根据 `SKILL.md` 的规则/提示词，把主题“编译”为一个**完整可运行的单页 HTML**（包含 Three.js + SVG + UI + 控件逻辑）。
- **运行阶段（Run-time）**：用户用任意静态服务器（`python -m http.server` / `npx serve` / `php -S`）打开生成的 HTML；所有交互与渲染都在浏览器端完成（WebGL + DOM/SVG）。

> 关键点：**AI 是外部依赖（Claude/LLM）**，仓库本身更像“Skill 定义 + 文档”，而不是完整源代码工程。你的系统设计图要把“生成系统”和“运行系统”分开画，否则会误导读者以为有后端服务。

##### 文件结构解读（如何映射到架构图）
从你给的完整文件树来看，仓库只有：
- `README.md`：产品/能力说明、运行方式、技术栈与渲染策略（关键词→渲染模式）
- `SKILL.md`：**最关键的“架构驱动文件”**（定义 Claude 如何把主题生成 HTML；相当于编译器的规格/提示词/规则）
- `LICENSE`

README 中提到 `docs/skill.md`，但在你提供的 file tree 里并不存在；因此图中可以标注为：
- “可选文档（README 提及，但仓库当前未包含）”，避免画出不存在的组件。

##### 你应该画的“最准确”架构图：建议分 4 张（C4 风格）
为了“最细 + 不过度脑补”，建议你产出 4 个视图：**Context → Container → Component → Sequence**。这对 Principal 读者最清晰。

**目标**：说明谁在用它、依赖谁、输出是什么。

建议组件拆分（尽量多拆）：
##### Third-party Libraries（通常来自 CDN 或内联）
- Three.js r134
- OrbitControls（内联简化版）
- Tailwind CSS v3.4+
- KaTeX 0.16.11
- D3.js v7（可选）
##### GPU/WebGL（浏览器依赖的渲染能力）

关系/箭头（务必画方向）：
- User → Claude Code：输入“主题”
- Claude Code ↔ Skill Definition：读取规则/提示词（SKILL.md）
- Claude Code → Generated HTML：产出 HTML
- User → Static Server：启动静态服务并访问
- Static Server → Browser：提供 HTML
- Browser → GPU/WebGL：WebGL 渲染调用
- Browser → CDN（可选）：拉取 Three.js/Tailwind/KaTeX/D3（若生成物引用外链）

> 这一张图要明确：**AI 平台是“生成阶段依赖”，不是运行时后端。**

**目标**：把“生成端”和“运行端”的部署边界画清楚。

建议容器分组（用边框框起来）：

##### “生成端”（AI/工具链侧）
- **Claude Code Client（用户本地或云端）**
- **Claude LLM Service（外部）**
- **Skill Spec（本仓库：SKILL.md）**
- **Output: HTML file（生成物，落地到用户本地文件系统）**

数据流：
- Topic text → Subject/Keyword analysis → Render mode decision → HTML templating/codegen → HTML 文件输出

##### “运行端”（纯前端）
- **Static Server**（仅文件服务）
- **Browser SPA（生成的 HTML/JS/CSS）**
- **Rendering Subsystems**
- WebGL/Three.js pipeline
- SVG overlay pipeline
- KaTeX math rendering
- UI (Tailwind) + Panels/HUD

> 容器图里不要画数据库/后端 API（除非 SKILL.md 明确生成的页面会调用某 API）。从 README 看它是离线可运行的教学页面。

**目标**：即使没有源代码，也能基于 README 的功能承诺，画出运行时组件拆分；这是最有价值的一张。

你可以把“Generated HTML App”当作一个容器，然后拆组件（建议按职责分层）：

##### UI Layer（界面层）
- Sidebar / Control Panel（参数滑块、播放控制、速度控制）
- HUD Overlay（实时数据展示）
- Quiz Panel（可折叠）
- Learning Objectives Checklist

##### Orchestration / State（状态与编排）
- App State Store（当前主题、参数、播放状态、语言）
- Mode Controller（渲染模式：Three-only / SVG-only / Hybrid）
- Time Controller（播放/暂停/单步/速度）

##### Domain Logic（教学/仿真逻辑）
- Simulation Engine（物理运动、粒子、天体等）
- Scenario/Scene Builder（根据“主题类别”构建场景对象）
- Subject Theme Resolver（学科识别→配色主题/文案风格）

##### Rendering Layer（渲染层：强烈建议画成 2 条管线）
- **Three.js Renderer**
- Scene / Camera / Lights
- Meshes/Particles/Helpers
- OrbitControls（输入控制）
- **SVG Renderer**
- Axes/Function plots/Flow charts
- D3-driven charts（可选）
- **Sync Bridge（3D-2D 坐标同步机制）** ← README 强调“实时同步”，这是架构关键点

##### Content Rendering
- KaTeX Renderer（公式）
- Localization（中/英语言适配）

关键交互箭头（要画清）：
- UI events → State Store → Simulation/Render updates
- Time Controller → Simulation tick → Three.js frame render
- Simulation state → Sync Bridge → SVG overlay update

> 你要把“混合渲染模式”画成显式分支：Mode Controller 决定走 Three、SVG 或两者并行，并通过 Sync Bridge 保证一致性。

建议至少两条序列：

##### LLM 依据 `SKILL.md` 进行：
- 学科识别（Physics/Math/…）
- 关键词检测
- 渲染方案选择（Three / SVG / Hybrid）
- 输出 HTML（内联或引用依赖）

##### requestAnimationFrame 循环：
- Time Controller 更新 dt
- Simulation 更新状态
- Three.js 渲染
- Sync Bridge 更新 SVG

##### 图中必须强调的架构模式/设计原则（贴合本项目）
- **Two-phase architecture（生成阶段 vs 运行阶段）**：这是本项目最大结构特征。
- **Strategy Pattern（渲染策略选择）**：根据关键词选择 Three/SVG/Hybrid。
- **Dual pipeline rendering（3D WebGL + 2D SVG）**：并通过 **Sync Bridge** 保证坐标/状态一致。
- **Client-only deployment（无后端）**：静态托管即可；性能与兼容性取决于浏览器 WebGL。

##### 标签建议（统一命名）
- 用明确名词：`Mode Controller`, `Simulation Engine`, `SVG Overlay`, `3D-2D Sync Bridge`, `KaTeX Renderer`
- 用括号标技术栈：`Three.js Renderer (WebGL)`, `UI (Tailwind)`

##### 箭头建议（区分数据流 vs 控制流）
- 实线箭头：控制调用（init/update/render）
- 虚线箭头：数据流/状态同步（state → svg, theme → ui）

##### 颜色/形状建议（强制区分）
- 蓝色：运行时前端组件（Browser App）
- 橙色：生成端（Claude/Skill）
- 绿色：第三方依赖（Three.js/KaTeX/D3/CDN）
- 灰色：基础设施（Static server / GPU / WebGL）

##### 不要过度脑补的边界（保持“最准确”）
- **不要画数据库、后端 API、消息队列**：README 没有任何证据表明存在。
- **AI/LLM 画成外部系统**：不是本仓库提供的服务。
- **docs/skill.md**：README 提及但 file tree 不含；可以用“(optional / mentioned in README)”标注，或在图注中说明缺失。

##### 每个箭头标注：`topic text`、`render mode`、`scene graph updates`、`svg sync`、`user input events`

只要按上述拆分画出来，并在图注中说明“仓库只有 SKILL.md/README（生成规则）”，你的系统设计图就会既**细**又**准确**，并且与该项目的真实形态高度一致。

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% AetherViz Master — Two-phase architecture (Generate vs Run)
  %% =========================================================

  %% -------------------------
  %% (A) System Context
  %% -------------------------
  subgraph CTX["A. System Context (Generate-time vs Run-time)"]
    direction TB

    U["User (Teacher/Student/Creator)"]:::external

    subgraph GEN_CTX["Generate-time (AI Platform Side)"]
      direction TB
      CC["Claude Code / Claude Skill Runtime"]:::gen
      LLM["Claude LLM Service (External)"]:::gen
      SK["AetherViz Master Skill Definition\n(SKILL.md + README rules)"]:::repo
      HTML["Generated HTML Artifact\n(Single-page HTML)"]:::artifact
    end

    subgraph RUN_CTX["Run-time (Client-only)"]
      direction TB
      SFS["Static File Server\n(python/npx serve/php)"]:::infra
      BR["Browser Runtime\n(Chrome/Edge)"]:::runtime
      GPU["GPU / WebGL"]:::infra

      subgraph LIBS["Third-party Libraries (CDN or Inline)"]
        direction TB
        THREE["Three.js r134"]:::lib
        ORB["OrbitControls (simplified/inline)"]:::lib
        TW["Tailwind CSS v3.4+"]:::lib
        KX["KaTeX 0.16.11"]:::lib
        D3["D3.js v7 (optional)"]:::lib
      end
    end

    U -->|"topic input"| CC
    CC -->|"prompt/skill execution"| LLM
    CC <-->|"reads rules/spec"| SK
    LLM -->|"generated HTML"| HTML

    U -->|"start server & open page"| SFS
    SFS -->|"serves HTML"| BR

    BR -->|"WebGL calls"| GPU
    BR -.->|"fetch if external refs"| LIBS
  end

  %% -------------------------
  %% (B) Container Diagram
  %% -------------------------
  subgraph CON["B. Container Diagram (Deployment Units)"]
    direction TB

    subgraph GEN["Generate-time Containers"]
      direction TB
      GEN1["Claude Code Client"]:::gen
      GEN2["Claude LLM Service\n(External)"]:::gen
      GEN3["Skill Spec (Repository)\nSKILL.md + README"]:::repo
      GEN4["Output HTML (Local file system)"]:::artifact

      GEN1 -->|"topic text"| GEN2
      GEN1 <-->|"skill rules"| GEN3
      GEN2 -->|"mode decision + templating/codegen"| GEN4
    end

    subgraph RUN["Run-time Containers (Static + Browser)"]
      direction TB
      RUN1["Static Server\n(file hosting only)"]:::infra
      RUN2["Browser SPA\n(Generated HTML/JS/CSS)"]:::runtime

      subgraph RUN3["Rendering Subsystems"]
        direction TB
        R3A["Three.js Pipeline (WebGL)"]:::runtime
        R3B["SVG Overlay Pipeline"]:::runtime
        R3C["KaTeX Math Rendering"]:::runtime
        R3D["UI Panels/HUD (Tailwind)"]:::runtime
      end

      RUN1 -->|"serves files"| RUN2
      RUN2 -->|"initializes"| RUN3
    end
  end

  %% -------------------------
  %% (C) Component Diagram (Generated HTML internal architecture)
  %% -------------------------
  subgraph CMP["C. Component Diagram (Inside Generated HTML App)"]
    direction TB

    APP["Generated HTML App (Single Page)"]:::artifact

    subgraph UIL["UI Layer"]
      direction TB
      UI1["Sidebar / Control Panel"]:::ui
      UI2["HUD Overlay (live metrics)"]:::ui
      UI3["Quiz Panel (collapsible)"]:::ui
      UI4["Learning Objectives Checklist"]:::ui
    end

    subgraph ORCH["Orchestration / State"]
      direction TB
      ST["App State Store"]:::state
      MODE["Mode Controller\n(Three-only / SVG-only / Hybrid)"]:::state
      TIME["Time Controller\n(play/pause/step/speed)"]:::state
    end

    subgraph DOM["Domain Logic"]
      direction TB
      SIM["Simulation Engine"]:::logic
      SCENE["Scenario / Scene Builder"]:::logic
      THEME["Subject Theme Resolver\n(subject->palette/copy style)"]:::logic
    end

    subgraph REND["Rendering Layer (Dual Pipeline)"]
      direction TB

      subgraph P3D["Three.js Renderer (WebGL)"]
        direction TB
        TSC["Scene / Camera / Lights"]:::render
        TM["Meshes / Particles / Helpers"]:::render
        OC["OrbitControls (input)"]:::render
      end

      subgraph P2D["SVG Renderer (Overlay)"]
        direction TB
        SVG1["Axes / Function Plots / Flow Charts"]:::render
        SVG2["D3-driven Charts (optional)"]:::render
      end

      SYNC["3D-2D Sync Bridge\n(coord/state sync)"]:::sync
    end

    subgraph CONT["Content Rendering"]
      direction TB
      KATEX["KaTeX Renderer (math)"]:::content
      L10N["Localization (CN/EN)"]:::content
    end

    %% containment
    APP --> UIL
    APP --> ORCH
    APP --> DOM
    APP --> REND
    APP --> CONT

    %% key interactions
    UIL -->|"UI events"| ST
    ST -->|"drives"| MODE
    ST -->|"drives"| TIME

    TIME -->|"tick(dt)"| SIM
    MODE -->|"select pipeline"| P3D
    MODE -->|"select pipeline"| P2D

    SIM -->|"scene graph updates"| SCENE
    SCENE -->|"build/update objects"| TSC
    SCENE -->|"build/update objects"| TM

    UIL -->|"input gestures"| OC
    OC -->|"camera updates"| TSC

    SIM -.->|"state snapshot"| SYNC
    TSC -.->|"camera/projection"| SYNC
    SYNC -.->|"svg sync"| SVG1
    SYNC -.->|"svg sync"| SVG2

    THEME -.->|"theme/colors/copy"| UIL
    THEME -.->|"materials/colors"| TM

    ST -->|"content needs"| KATEX
    ST -->|"language"| L10N
  end

  %% -------------------------
  %% (D) Sequence Diagram (end-to-end)
  %% -------------------------
  subgraph SEQ["D. Sequence (Generate + Run)"]
    direction TB

    subgraph SEQ1["Generate Sequence: topic -> HTML"]
      direction TB
      S1U["User"]:::external
      S1CC["Claude Code"]:::gen
      S1LLM["Claude LLM"]:::gen
      S1SK["SKILL.md rules"]:::repo
      S1OUT["HTML file saved locally"]:::artifact

      S1U -->|"enter topic"| S1CC
      S1CC -->|"invoke"| S1LLM
      S1LLM -->|"consult spec"| S1SK
      S1LLM -->|"subject detection"| S1LLM
      S1LLM -->|"keyword detection"| S1LLM
      S1LLM -->|"render mode selection"| S1LLM
      S1LLM -->|"emit HTML (inline or CDN refs)"| S1OUT
    end

    subgraph SEQ2["Run Sequence: load -> interact -> render"]
      direction TB
      S2BR["Browser"]:::runtime
      S2UI["Init UI (Tailwind)"]:::ui
      S2TH["Init Three.js (Scene/Camera/Renderer/Controls)"]:::render
      S2SVG["Init SVG Layer (if needed)"]:::render
      S2KX["Init KaTeX (if needed)"]:::content
      S2RAF["requestAnimationFrame loop"]:::runtime
      S2TIME["Time Controller"]:::state
      S2SIM["Simulation Engine"]:::logic
      S2R3D["Three.js Render Frame"]:::render
      S2SYNC["Sync Bridge"]:::sync
      S2R2D["Update SVG Overlay"]:::render
      S2IN["User drag/zoom"]:::external
      S2OC["OrbitControls"]:::render

      S2BR -->|"load HTML/JS/CSS"| S2UI
      S2BR -->|"init"| S2TH
      S2BR -->|"init if hybrid/svg"| S2SVG
      S2BR -->|"init if math"| S2KX
      S2BR -->|"start"| S2RAF

      S2RAF -->|"each frame"| S2TIME
      S2TIME -->|"dt"| S2SIM
      S2SIM -->|"state"| S2R3D
      S2SIM -.->|"state"| S2SYNC
      S2R3D -->|"draw"| S2BR
      S2SYNC -.->|"svg update"| S2R2D

      S2IN -->|"pointer events"| S2OC
      S2OC -->|"camera update"| S2TH
    end
  end

  %% -------------------------
  %% Click events (from component_mapping)
  %% -------------------------
  click SK "https://github.com/andyhuo520/aetherviz-master/blob/master/SKILL.md"
  click GEN3 "https://github.com/andyhuo520/aetherviz-master/blob/master/SKILL.md"
  click S1SK "https://github.com/andyhuo520/aetherviz-master/blob/master/SKILL.md"

  click SK "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"
  click GEN3 "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"

  click HTML "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"
  click CTX "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"
  click CON "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"
  click CMP "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"
  click SEQ "https://github.com/andyhuo520/aetherviz-master/blob/master/README.md"

  click SK "https://github.com/andyhuo520/aetherviz-master/tree/master/LICENSE"

  %% -------------------------
  %% Styles
  %% -------------------------
  classDef external fill:#ffffff,stroke:#374151,stroke-width:1px,color:#111827
  classDef gen fill:#ffedd5,stroke:#c2410c,stroke-width:1px,color:#7c2d12
  classDef repo fill:#fde68a,stroke:#a16207,stroke-width:1px,color:#713f12
  classDef artifact fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#1e3a8a
  classDef infra fill:#e5e7eb,stroke:#4b5563,stroke-width:1px,color:#111827
  classDef runtime fill:#bfdbfe,stroke:#1e40af,stroke-width:1px,color:#0f172a
  classDef lib fill:#d1fae5,stroke:#065f46,stroke-width:1px,color:#064e3b
  classDef ui fill:#c7d2fe,stroke:#4338ca,stroke-width:1px,color:#1e1b4b
  classDef state fill:#bae6fd,stroke:#0369a1,stroke-width:1px,color:#0c4a6e
  classDef logic fill:#bbf7d0,stroke:#15803d,stroke-width:1px,color:#052e16
  classDef render fill:#93c5fd,stroke:#1d4ed8,stroke-width:1px,color:#0b1f4b
  classDef sync fill:#fbcfe8,stroke:#9d174d,stroke-width:1px,color:#500724
  classDef content fill:#fed7aa,stroke:#c2410c,stroke-width:1px,color:#7c2d12
```
