# qqzhangyanhua/learn-opencode-agent architecture

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

- Interactive diagram: https://gitdiagram.com/qqzhangyanhua/learn-opencode-agent
- Repository: https://github.com/qqzhangyanhua/learn-opencode-agent

## Overview

#### Purpose and Runtime
This is a Chinese AI-agent engineering learning site, not an agent runtime. It publishes structured tutorials, source-code analyses, runnable TypeScript exercises, decision guides, and interactive visualizations. It runs on Bun with VitePress/Vue; production serves the built static site through Caddy on port 3000. Key entry points: `package.json`, `.vitepress/config.mts`, `Caddyfile`.

#### Site Composition and Navigation
VitePress configuration defines routing, navigation, sidebars, search, and page metadata; the documentation tree supplies route-backed Markdown content. The homepage and major hubs direct learners into OpenCode analysis, practice, intermediate topics, selection guidance, animation lab, interviews, and enterprise-agent material. Paths: `docs/index.md`, `docs/discover/index.md`, `docs/learning-paths/index.md`.

#### Theme Application Layer
The custom Vue theme is the client-side presentation and interaction boundary. It registers globally usable educational components, provides layout behavior, and owns site-wide styling and legacy selection-route redirects. Markdown pages embed these components rather than owning application logic. Paths: `.vitepress/theme/index.ts`, `.vitepress/theme/Layout.vue`, `.vitepress/theme/custom.css`, `.vitepress/theme/agent-selection-redirects.ts`.

#### Structured Content Data
Theme data modules are the canonical structured inputs for content-driven experiences: discovery, learning paths, practice catalogs, and animation scenarios. UI hubs consume this data to render cards, routes, progress, and simulations; content additions often require synchronized Markdown, data, and navigation updates. Paths: `.vitepress/theme/data/content-index.data.ts`, `.vitepress/theme/data/learning-paths.data.ts`, `.vitepress/theme/data/practice-projects.ts`.

#### Interactive Simulation System
Interactive teaching demos model Agent workflows in Vue, with scenario/state logic separated from rendering in several features. The animation laboratory is explicitly data-driven: experiment definitions feed a shared canvas/player rather than independent navigation or bespoke pages. Some scenario modules have colocated unit tests, making state transitions a tested boundary. Paths: `.vitepress/theme/components/animation-lab/FlowExperimentCanvas.vue`, `.vitepress/theme/data/animation-lab-experiments.ts`, `.vitepress/theme/components/flowScenario.ts`.

#### Educational Content Domains
Markdown is organized as independently navigable curricula: core OpenCode material, source-analysis series for Claude Code and Hermes, enterprise-agent design, practices, intermediate topics, selection guides, and interview resources. The docs are static source content; references to external Agent systems are explanatory source snapshots, not bundled integrations. Paths: `docs/02-agent-core/index.md`, `docs/new-claude/part-1-主业务流/04-query-主循环如何驱动整个系统.md`, `docs/enterprise-agent/index.md`.

#### Runnable Practice Boundary
Practice scripts are standalone TypeScript learning artifacts paired one-to-one with practice documentation and catalog metadata. They demonstrate concepts such as tool use, RAG, planning, MCP, multi-agent coordination, and deployment, rather than acting as services used by the site. MCP is represented by a dedicated server example. Paths: `practice/p01-minimal-agent.ts`, `practice/p14-mcp-server.ts`, `docs/practice/p14-mcp/index.md`.

#### Quality and Delivery Pipeline
Node/Bun scripts enforce cross-boundary consistency: required content metadata, navigation and hub entry reachability, practice-to-doc mappings, learning data, and animation registrations. `build:strict` sequences these checks before the static build; TypeScript checking focuses on the VitePress theme. Output is `.vitepress/dist/`, then Caddy serves it. Paths: `scripts/check.sh`, `scripts/check-practice-entries.mjs`, `scripts/check-animation-lab.mjs`.

Main entry points: [`.vitepress/theme/index.ts`](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/index.ts) (Custom Vue theme), [`docs/index.md`](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/index.md) (Homepage & learning hubs), [`scripts/check.sh`](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check.sh) (Strict consistency checks), [`.vitepress/config.mts`](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/config.mts) (Site configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Learning Content"]
  node_home_hubs["Homepage &amp; learning hubs<br/>Markdown routes<br/>[index.md]"]
  node_discovery_hub["Discovery hub<br/>Markdown route<br/>[index.md]"]
  node_learning_paths_hub["Learning paths hub<br/>Markdown route<br/>[index.md]"]
  node_core_curriculum["OpenCode curriculum<br/>Markdown curriculum<br/>[index.md]"]
  node_source_analysis["Source-analysis curriculum<br/>Markdown curriculum"]
  node_enterprise_curriculum["Enterprise-agent curriculum<br/>Markdown curriculum<br/>[index.md]"]
  node_practice_docs["MCP practice lesson<br/>Markdown lesson<br/>[index.md]"]
  node_practice_scripts["Runnable exercises<br/>TypeScript artifacts"]
  node_mcp_server_example{{"MCP server example<br/>TypeScript exercise<br/>[p14-mcp-server.ts]"}}
end

subgraph group_theme["Theme &amp; Experiences"]
  node_custom_theme["Custom Vue theme<br/>theme entry<br/>[index.ts]"]
  node_layout["Site layout<br/>Vue layout<br/>[Layout.vue]"]
  node_theme_styles["Global styling<br/>CSS<br/>[custom.css]"]
  node_legacy_redirects["Selection redirects<br/>route redirects"]
  node_content_data[("Content catalogs<br/>structured theme data")]
  node_learning_data[("Learning-path data<br/>structured theme data")]
  node_practice_catalog[("Practice catalog<br/>structured theme data")]
  node_animation_data[("Animation experiments<br/>scenario definitions")]
  node_animation_canvas["Flow experiment canvas<br/>Vue simulation player"]
  node_scenario_logic["Flow scenario logic<br/>Vue state logic<br/>[flowScenario.ts]"]
end

subgraph group_quality["Quality &amp; Delivery"]
  node_runtime{{"Bun / VitePress<br/>runtime<br/>[package.json]"}}
  node_site_config["Site configuration<br/>VitePress config<br/>[config.mts]"]
  node_strict_checks{{"Strict consistency checks<br/>Bun validation pipeline<br/>[check.sh]"}}
  node_practice_check["Practice mapping check<br/>validation script"]
  node_animation_check["Animation registration check<br/>validation script"]
  node_static_site["Static site output<br/>VitePress dist"]
  node_caddy{{"Caddy<br/>production server"}}
end

node_runtime -->|"loads"| node_site_config
node_site_config -->|"routes"| node_home_hubs
node_site_config -->|"navigates"| node_core_curriculum
node_home_hubs -->|"links to"| node_discovery_hub
node_home_hubs -->|"links to"| node_learning_paths_hub
node_home_hubs -->|"links to"| node_core_curriculum
node_home_hubs -->|"links to"| node_source_analysis
node_home_hubs -->|"links to"| node_enterprise_curriculum
node_learning_paths_hub -->|"uses"| node_learning_data
node_discovery_hub -->|"uses"| node_content_data
node_practice_docs -.->|"teaches"| node_mcp_server_example
node_practice_catalog -.->|"catalogs"| node_practice_scripts
node_practice_catalog -.->|"maps to"| node_practice_docs
node_custom_theme -->|"provides"| node_layout
node_custom_theme -->|"applies"| node_theme_styles
node_custom_theme -->|"owns"| node_legacy_redirects
node_custom_theme -->|"consumes"| node_content_data
node_custom_theme -->|"consumes"| node_learning_data
node_animation_data -->|"drives"| node_animation_canvas
node_scenario_logic -->|"supplies state"| node_animation_canvas
node_custom_theme -->|"registers"| node_animation_canvas
node_strict_checks -->|"runs"| node_practice_check
node_strict_checks -->|"runs"| node_animation_check
node_strict_checks -->|"gates build"| node_static_site
node_runtime -->|"builds"| node_static_site
node_static_site -->|"served by"| node_caddy

click node_runtime "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/package.json"
click node_site_config "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/config.mts"
click node_home_hubs "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/index.md"
click node_discovery_hub "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/discover/index.md"
click node_learning_paths_hub "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/learning-paths/index.md"
click node_core_curriculum "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/02-agent-core/index.md"
click node_source_analysis "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/new-claude/part-1-%E4%B8%BB%E4%B8%9A%E5%8A%A1%E6%B5%81/04-query-%E4%B8%BB%E5%BE%AA%E7%8E%AF%E5%A6%82%E4%BD%95%E9%A9%B1%E5%8A%A8%E6%95%B4%E4%B8%AA%E7%B3%BB%E7%BB%9F.md"
click node_enterprise_curriculum "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/enterprise-agent/index.md"
click node_practice_docs "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/practice/p14-mcp/index.md"
click node_practice_scripts "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/practice/p01-minimal-agent.ts"
click node_mcp_server_example "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/practice/p14-mcp-server.ts"
click node_custom_theme "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/index.ts"
click node_layout "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/Layout.vue"
click node_theme_styles "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/custom.css"
click node_legacy_redirects "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/agent-selection-redirects.ts"
click node_content_data "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/content-index.data.ts"
click node_learning_data "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/learning-paths.data.ts"
click node_practice_catalog "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/practice-projects.ts"
click node_animation_data "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/animation-lab-experiments.ts"
click node_animation_canvas "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/components/animation-lab/FlowExperimentCanvas.vue"
click node_scenario_logic "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/components/flowScenario.ts"
click node_strict_checks "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check.sh"
click node_practice_check "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check-practice-entries.mjs"
click node_animation_check "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check-animation-lab.mjs"
click node_caddy "https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/Caddyfile"

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_home_hubs,node_discovery_hub,node_learning_paths_hub,node_core_curriculum,node_source_analysis,node_enterprise_curriculum,node_practice_docs,node_practice_scripts,node_mcp_server_example toneBlue
class node_custom_theme,node_layout,node_theme_styles,node_legacy_redirects,node_content_data,node_learning_data,node_practice_catalog,node_animation_data,node_animation_canvas,node_scenario_logic toneAmber
class node_runtime,node_site_config,node_strict_checks,node_practice_check,node_animation_check,node_static_site,node_caddy toneMint
```

## Components

### Learning Content

Route-backed curricula and practice materials.

- [Homepage & learning hubs](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/index.md): Markdown routes · Directs learners into the major curricula and experiences. · `docs/index.md`
- [Discovery hub](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/discover/index.md): Markdown route · `docs/discover/index.md`
- [Learning paths hub](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/learning-paths/index.md): Markdown route · `docs/learning-paths/index.md`
- [OpenCode curriculum](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/02-agent-core/index.md): Markdown curriculum · `docs/02-agent-core/index.md`
- [Source-analysis curriculum](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/new-claude/part-1-%E4%B8%BB%E4%B8%9A%E5%8A%A1%E6%B5%81/04-query-%E4%B8%BB%E5%BE%AA%E7%8E%AF%E5%A6%82%E4%BD%95%E9%A9%B1%E5%8A%A8%E6%95%B4%E4%B8%AA%E7%B3%BB%E7%BB%9F.md): Markdown curriculum · Claude Code and Hermes implementation analyses. · `docs/new-claude/part-1-主业务流/04-query-主循环如何驱动整个系统.md`
- [Enterprise-agent curriculum](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/enterprise-agent/index.md): Markdown curriculum · `docs/enterprise-agent/index.md`
- [MCP practice lesson](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/docs/practice/p14-mcp/index.md): Markdown lesson · Paired documentation for the MCP server exercise. · `docs/practice/p14-mcp/index.md`
- [Runnable exercises](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/practice/p01-minimal-agent.ts): TypeScript artifacts · Standalone learning examples, including agent and MCP concepts. · `practice/p01-minimal-agent.ts`
- [MCP server example](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/practice/p14-mcp-server.ts): TypeScript exercise · Dedicated standalone MCP server learning artifact. · `practice/p14-mcp-server.ts`

### Theme & Experiences

Vue presentation, structured data, and interactive lessons.

- [Custom Vue theme](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/index.ts): theme entry · Registers educational components and the site presentation boundary. · `.vitepress/theme/index.ts`
- [Site layout](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/Layout.vue): Vue layout · Provides global layout behavior. · `.vitepress/theme/Layout.vue`
- [Global styling](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/custom.css): CSS · `.vitepress/theme/custom.css`
- [Selection redirects](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/agent-selection-redirects.ts): route redirects · Preserves legacy selection routes. · `.vitepress/theme/agent-selection-redirects.ts`
- [Content catalogs](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/content-index.data.ts): structured theme data · Canonical discovery and practice catalog input. · `.vitepress/theme/data/content-index.data.ts`
- [Learning-path data](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/learning-paths.data.ts): structured theme data · Defines learning-path progress and route content. · `.vitepress/theme/data/learning-paths.data.ts`
- [Practice catalog](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/practice-projects.ts): structured theme data · Maps practice entries to their learning materials. · `.vitepress/theme/data/practice-projects.ts`
- [Animation experiments](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/data/animation-lab-experiments.ts): scenario definitions · Data-driven experiment definitions for the animation lab. · `.vitepress/theme/data/animation-lab-experiments.ts`
- [Flow experiment canvas](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/components/animation-lab/FlowExperimentCanvas.vue): Vue simulation player · Shared renderer and player for animation experiments. · `.vitepress/theme/components/animation-lab/FlowExperimentCanvas.vue`
- [Flow scenario logic](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/theme/components/flowScenario.ts): Vue state logic · Models interactive workflow state transitions. · `.vitepress/theme/components/flowScenario.ts`

### Quality & Delivery

Validation, static build, and production serving.

- [Bun / VitePress](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/package.json): runtime · Builds the static documentation site. · `package.json`
- [Site configuration](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/.vitepress/config.mts): VitePress config · Defines navigation, sidebars, search, routes, and metadata. · `.vitepress/config.mts`
- [Strict consistency checks](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check.sh): Bun validation pipeline · Checks metadata, reachability, mappings, learning data, and animation registrations. · `scripts/check.sh`
- [Practice mapping check](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check-practice-entries.mjs): validation script · `scripts/check-practice-entries.mjs`
- [Animation registration check](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/scripts/check-animation-lab.mjs): validation script · `scripts/check-animation-lab.mjs`
- **Static site output**: VitePress dist · Production-ready generated site files.
- [Caddy](https://github.com/qqzhangyanhua/learn-opencode-agent/blob/main/Caddyfile): production server · Serves the static site on port 3000. · `Caddyfile`

## Connections

- Bun / VitePress → Site configuration: loads
- Site configuration → Homepage & learning hubs: routes
- Site configuration → OpenCode curriculum: navigates
- Homepage & learning hubs → Discovery hub: links to
- Homepage & learning hubs → Learning paths hub: links to
- Homepage & learning hubs → OpenCode curriculum: links to
- Homepage & learning hubs → Source-analysis curriculum: links to
- Homepage & learning hubs → Enterprise-agent curriculum: links to
- Learning paths hub → Learning-path data: uses
- Discovery hub → Content catalogs: uses
- MCP practice lesson → MCP server example: teaches
- Practice catalog → Runnable exercises: catalogs
- Practice catalog → MCP practice lesson: maps to
- Custom Vue theme → Site layout: provides
- Custom Vue theme → Global styling: applies
- Custom Vue theme → Selection redirects: owns
- Custom Vue theme → Content catalogs: consumes
- Custom Vue theme → Learning-path data: consumes
- Animation experiments → Flow experiment canvas: drives
- Flow scenario logic → Flow experiment canvas: supplies state
- Custom Vue theme → Flow experiment canvas: registers
- Strict consistency checks → Practice mapping check: runs
- Strict consistency checks → Animation registration check: runs
- Strict consistency checks → Static site output: gates build
- Bun / VitePress → Static site output: builds
- Static site output → Caddy: served by