# zarazhangrui/codebase-to-course architecture

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

- Interactive diagram: https://gitdiagram.com/zarazhangrui/codebase-to-course
- Repository: https://github.com/zarazhangrui/codebase-to-course

## Overview

#### Purpose and Invocation

This repository is a Claude Code skill that analyzes an arbitrary target repository and produces a self-contained, interactive HTML course explaining it to nontraditional developers. The operational entry point is `SKILL.md`, which directs the agent’s analysis, curriculum planning, and HTML generation process.

#### Skill Orchestration

`SKILL.md` is the primary control layer. It defines how the skill should inspect a codebase, identify its architecture and runtime flows, select exact source snippets, and turn findings into course modules. It is intended to be installed under Claude Code’s skills directory rather than run as a standalone application.

Core path:
- `SKILL.md`

#### Course Generation Pipeline

The skill’s output boundary is one offline-capable HTML document. Its pipeline is conceptually:

1. Analyze the target repository’s structure and primary flows.
2. Build an architecture-focused learning plan.
3. Extract unmodified code from target-project files.
4. Compose visual modules, explanations, interactions, and quizzes.
5. Emit the completed single-page course.

The reusable course page foundation is supplied by:
- `references/_base.html`
- `references/_footer.html`
- `references/build.sh`

#### Presentation Runtime

Generated courses use browser-native HTML, CSS, and JavaScript rather than a framework or hosted backend. The base template establishes the document shell; `references/styles.css` provides the visual system; `references/main.js` supplies client-side behavior for navigation and interactive course elements.

Core paths:
- `references/_base.html`
- `references/styles.css`
- `references/main.js`

#### Content and Pedagogy Constraints

The skill is designed around experiential codebase explanation: tracing what happens during actual app use rather than teaching abstract computer-science concepts. It requires real, verbatim source snippets and favors visual explanations, concise text, and application-oriented quizzes.

The content rules and authoring guidance live in:
- `references/content-philosophy.md`
- `references/gotchas.md`
- `references/module-brief-template.md`

#### Interactive Learning Components

Interactive patterns—such as architecture diagrams, animated data-flow sequences, code-to-plain-English comparisons, and quizzes—are standardized separately from the page runtime. This makes course interactions a composable content layer that generated HTML can implement with the shared browser assets.

Core path:
- `references/interactive-elements.md`

#### Design-System Boundary

Visual consistency is centralized in the reference design system. It governs typography, colors, spacing, layout, and the distinctive non-generic course appearance, while generated course content supplies the codebase-specific modules.

Core path:
- `references/design-system.md`

#### Infrastructure and External Dependencies

There is no application server, database, API integration, package manifest, or deployment infrastructure in this repository. The material runtime is Claude Code for skill execution and the browser for consuming generated courses. The intended generated artifact has no runtime dependency on external services and works offline.

Main entry points: [`references/build.sh`](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/build.sh) (Course assembly), [`SKILL.md`](https://github.com/zarazhangrui/codebase-to-course/blob/main/SKILL.md) (Skill orchestration), [`references/styles.css`](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/styles.css) (Visual system), [`references/_base.html`](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/_base.html) (Page shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skill["Claude Code Skill"]
  node_skill_md["Skill orchestration<br/>Claude Code skill<br/>[SKILL.md]"]
  node_target_repo["Target repository<br/>analyzed codebase"]
  node_architecture_plan["Learning plan<br/>course plan"]
  node_source_snippets["Verbatim snippets<br/>source extraction"]
end

subgraph group_references["Course References"]
  node_base_template["Page shell<br/>HTML template<br/>[_base.html]"]
  node_footer_template["Footer template<br/>HTML template<br/>[_footer.html]"]
  node_build_script["Course assembly<br/>shell build script<br/>[build.sh]"]
  node_browser_styles["Visual system<br/>CSS<br/>[styles.css]"]
  node_browser_runtime["Course interactions<br/>browser JavaScript<br/>[main.js]"]
  node_content_rules["Content philosophy<br/>authoring guidance"]
  node_authoring_gotchas["Authoring constraints<br/>guidance<br/>[gotchas.md]"]
  node_module_brief["Module brief<br/>authoring template"]
  node_interaction_patterns["Interactive patterns<br/>component guidance"]
  node_design_system["Design guidance<br/>design system<br/>[design-system.md]"]
end

subgraph group_output["Generated Artifact"]
  node_course_html["Offline HTML course<br/>single-page artifact"]
  node_browser["Browser<br/>runtime"]
end

node_skill_md -->|"inspects"| node_target_repo
node_skill_md -->|"plans"| node_architecture_plan
node_target_repo -->|"architecture and flows"| node_architecture_plan
node_target_repo -->|"provides code"| node_source_snippets
node_content_rules -->|"guides"| node_architecture_plan
node_authoring_gotchas -.->|"constrains"| node_architecture_plan
node_module_brief -.->|"structures modules"| node_architecture_plan
node_interaction_patterns -.->|"selects interactions"| node_architecture_plan
node_design_system -->|"governs"| node_browser_styles
node_base_template -->|"input"| node_build_script
node_footer_template -->|"input"| node_build_script
node_browser_styles -->|"included"| node_build_script
node_browser_runtime -->|"included"| node_build_script
node_architecture_plan -->|"course modules"| node_build_script
node_source_snippets -->|"embedded code"| node_build_script
node_build_script -->|"emits"| node_course_html
node_course_html -->|"runs offline in"| node_browser

click node_skill_md "https://github.com/zarazhangrui/codebase-to-course/blob/main/SKILL.md"
click node_base_template "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/_base.html"
click node_footer_template "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/_footer.html"
click node_build_script "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/build.sh"
click node_browser_styles "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/styles.css"
click node_browser_runtime "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/main.js"
click node_content_rules "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/content-philosophy.md"
click node_authoring_gotchas "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/gotchas.md"
click node_module_brief "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/module-brief-template.md"
click node_interaction_patterns "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/interactive-elements.md"
click node_design_system "https://github.com/zarazhangrui/codebase-to-course/blob/main/references/design-system.md"

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_skill_md,node_target_repo,node_architecture_plan,node_source_snippets toneBlue
class node_base_template,node_footer_template,node_build_script,node_browser_styles,node_browser_runtime,node_content_rules,node_authoring_gotchas,node_module_brief,node_interaction_patterns,node_design_system toneAmber
class node_course_html,node_browser toneMint
```

## Components

### Claude Code Skill

Instructions for analyzing a target repository and authoring its course.

- [Skill orchestration](https://github.com/zarazhangrui/codebase-to-course/blob/main/SKILL.md): Claude Code skill · Directs repository analysis, curriculum planning, and HTML generation. · `SKILL.md`
- **Target repository**: analyzed codebase · Arbitrary project whose architecture and runtime flows become course material.
- **Learning plan**: course plan · Architecture-focused modules built from the target project's real flows.
- **Verbatim snippets**: source extraction · Unmodified code selected from target-project files.

### Course References

Reusable template, runtime, and authoring standards.

- [Page shell](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/_base.html): HTML template · Base document structure for generated courses. · `references/_base.html`
- [Footer template](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/_footer.html): HTML template · `references/_footer.html`
- [Course assembly](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/build.sh): shell build script · Combines reusable HTML page fragments. · `references/build.sh`
- [Visual system](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/styles.css): CSS · Shared typography, layout, colors, and spacing. · `references/styles.css`
- [Course interactions](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/main.js): browser JavaScript · Navigation and interactive learning behavior. · `references/main.js`
- [Content philosophy](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/content-philosophy.md): authoring guidance · Requires experiential explanations and real source snippets. · `references/content-philosophy.md`
- [Authoring constraints](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/gotchas.md): guidance · `references/gotchas.md`
- [Module brief](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/module-brief-template.md): authoring template · `references/module-brief-template.md`
- [Interactive patterns](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/interactive-elements.md): component guidance · Standardizes diagrams, data-flow animations, comparisons, and quizzes. · `references/interactive-elements.md`
- [Design guidance](https://github.com/zarazhangrui/codebase-to-course/blob/main/references/design-system.md): design system · Defines the distinctive course presentation style. · `references/design-system.md`

### Generated Artifact

Offline browser course produced for a target repository.

- **Offline HTML course**: single-page artifact · Self-contained interactive explanation of the target repository.
- **Browser**: runtime · Runs the generated course without external services.

## Connections

- Skill orchestration → Target repository: inspects
- Skill orchestration → Learning plan: plans
- Target repository → Learning plan: architecture and flows
- Target repository → Verbatim snippets: provides code
- Content philosophy → Learning plan: guides
- Authoring constraints → Learning plan: constrains
- Module brief → Learning plan: structures modules
- Interactive patterns → Learning plan: selects interactions
- Design guidance → Visual system: governs
- Page shell → Course assembly: input
- Footer template → Course assembly: input
- Visual system → Course assembly: included
- Course interactions → Course assembly: included
- Learning plan → Course assembly: course modules
- Verbatim snippets → Course assembly: embedded code
- Course assembly → Offline HTML course: emits
- Offline HTML course → Browser: runs offline in