# luongnv89/claude-howto architecture

> Architecture diagram of the GitHub repository luongnv89/claude-howto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luongnv89/claude-howto
- Repository: https://github.com/luongnv89/claude-howto

## Overview

#### Purpose and Entry Points
This is a versioned, multilingual learning repository for Claude Code. Its primary product is Markdown-based tutorials and copyable configuration templates, not a deployed application. Start at `README.md`, follow the ordered curriculum in `LEARNING-ROADMAP.md`, or locate installable artifacts through `CATALOG.md` and `INDEX.md`.

#### Curriculum Content Model
Ten numbered modules are the canonical English curriculum, progressing from commands and persistent instructions to automation and extensibility. Core content boundaries are:
- User-invoked command templates: `01-slash-commands/optimize.md`, `01-slash-commands/pr.md`
- Persistent Claude context examples: `02-memory/project-CLAUDE.md`, `02-memory/directory-api-CLAUDE.md`
- Auto-invoked skills with instructions, templates, and optional scripts: `03-skills/code-review-specialist/SKILL.md`, `03-skills/doc-generator/generate-docs.py`
- Specialized delegated-agent definitions: `04-subagents/code-reviewer.md`, `04-subagents/secure-reviewer.md`

Consumers copy these artifacts into Claude Code’s project or user directories; the repository itself does not execute them as one runtime.

#### Claude Code Integration Boundaries
The guide models the major Claude Code extension surfaces:
- MCP configurations expose external tools such as GitHub, databases, and filesystem access: `05-mcp/github-mcp.json`, `05-mcp/database-mcp.json`, `05-mcp/multi-mcp.json`.
- Shell/Python hooks provide event-driven validation, formatting, logging, scanning, and notifications: `06-hooks/pre-tool-check.sh`, `06-hooks/security-scan.sh`, `06-hooks/context-tracker.py`.
- Advanced operational modes—planning, background tasks, permissions, and headless CLI—are documented/configured in `09-advanced-features/config-examples.json`, `09-advanced-features/planning-mode-examples.md`, and `10-cli/README.md`.

These are examples and installation inputs for the Claude Code runtime; credentials and services remain external.

#### Composed Plugin Workflows
Three distributable plugin examples bundle commands, agents, MCP configuration, lifecycle hooks, and operational scripts into higher-level workflows:
- PR review: `07-plugins/pr-review/.claude-plugin/plugin.json`, `07-plugins/pr-review/commands/review-pr.md`
- DevOps automation: `07-plugins/devops-automation/.claude-plugin/plugin.json`, `07-plugins/devops-automation/scripts/deploy.sh`, `07-plugins/devops-automation/mcp/kubernetes-config.json`
- Documentation generation: `07-plugins/documentation/.claude-plugin/plugin.json`, `07-plugins/documentation/agents/api-documenter.md`

A typical flow is command/request → project memory and skill selection → isolated subagent delegation → MCP tool access → hooks/scripts for guardrails → synthesized response or external action. Kubernetes, GitHub, databases, filesystem servers, and team notification endpoints are optional external dependencies configured by adopters.

#### Assessment and Learning Feedback
Repository-local Claude skills implement guided self-assessment and lesson quizzes, producing learning-gap and next-step feedback rather than application state:
- `.claude/skills/self-assessment/SKILL.md`
- `.claude/skills/lesson-quiz/SKILL.md`
- `.claude/skills/lesson-quiz/references/question-bank.md`

Checkpoints are a related Claude Code session capability explained separately in `08-checkpoints/README.md`; state is managed by Claude Code, not stored by this repository.

#### Publishing, Localization, and Quality Pipeline
Python build tooling converts the Markdown corpus into distributable documentation artifacts. `scripts/build_website.py` renders site pages using `scripts/website_templates/page.html.j2`; `scripts/build_epub.py` produces an offline EPUB and can render Mermaid diagrams. Content is translated into parallel language trees including `ja/`, `uk/`, `vi/`, and `zh/`; synchronization support is in `scripts/sync_translations.py`.

GitHub Actions provide the automation boundary: `.github/workflows/test.yml` validates Python tooling, `.github/workflows/docs-check.yml` checks documentation quality, `.github/workflows/pages.yml` publishes site output, and `.github/workflows/release.yml` governs releases. The material local runtime is Python (managed through `scripts/pyproject.toml` and requirements files), with Node/Tailwind assets only for website styling.

Main entry points: [`07-plugins/devops-automation/.claude-plugin/plugin.json`](https://github.com/luongnv89/claude-howto/blob/main/07-plugins/devops-automation/.claude-plugin/plugin.json) (DevOps plugin), [`scripts/build_website.py`](https://github.com/luongnv89/claude-howto/blob/main/scripts/build_website.py) (Website and EPUB builds), [`README.md`](https://github.com/luongnv89/claude-howto/blob/main/README.md) (Repository entry), [`07-plugins/pr-review/.claude-plugin/plugin.json`](https://github.com/luongnv89/claude-howto/blob/main/07-plugins/pr-review/.claude-plugin/plugin.json) (PR review plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_curriculum["Curriculum"]
  node_readme["Repository entry<br/>Markdown guide<br/>[README.md]"]
  node_roadmap["Learning roadmap<br/>ordered curriculum"]
  node_catalog["Artifact catalog<br/>install index<br/>[CATALOG.md]"]
  node_core_modules["Core modules<br/>tutorial templates<br/>[optimize.md]"]
  node_assessment["Learning assessment<br/>Claude skills<br/>[SKILL.md]"]
end

subgraph group_integration["Claude Code surfaces"]
  node_mcp["MCP configurations<br/>tool integration config<br/>[multi-mcp.json]"]
  node_hooks["Hooks and scripts<br/>event guardrails<br/>[pre-tool-check.sh]"]
  node_advanced["Advanced modes and CLI<br/>operational guidance"]
  node_checkpoints["Checkpoints guide<br/>session capability<br/>[README.md]"]
  node_claude_runtime{{"Claude Code runtime<br/>consumer runtime"}}
  node_external_services{{"External services<br/>optional dependencies"}}
end

subgraph group_plugins["Plugin workflows"]
  node_pr_plugin["PR review plugin<br/>plugin bundle<br/>[plugin.json]"]
  node_devops_plugin["DevOps plugin<br/>plugin bundle<br/>[plugin.json]"]
  node_docs_plugin["Documentation plugin<br/>plugin bundle<br/>[plugin.json]"]
end

subgraph group_publishing["Publishing pipeline"]
  node_markdown_corpus["Markdown corpus<br/>source content"]
  node_translation_sync["Translation sync<br/>Python tooling"]
  node_doc_build["Website and EPUB builds<br/>Python build tooling<br/>[build_website.py]"]
  node_github_actions["GitHub Actions<br/>CI and release workflows<br/>[pages.yml]"]
  node_published_docs["Published artifacts<br/>documentation output"]
end

node_readme -->|"guides learners to"| node_roadmap
node_readme -->|"links installable artifacts"| node_catalog
node_roadmap -->|"orders"| node_core_modules
node_core_modules -->|"copied into"| node_claude_runtime
node_assessment -->|"runs as repository-local skills"| node_claude_runtime
node_mcp -->|"installed for tool access"| node_claude_runtime
node_hooks -->|"installed as lifecycle guardrails"| node_claude_runtime
node_advanced -->|"documents operation"| node_claude_runtime
node_checkpoints -.->|"explains session feature"| node_claude_runtime
node_claude_runtime -->|"uses configured tools"| node_external_services
node_pr_plugin -->|"installs workflow"| node_claude_runtime
node_devops_plugin -->|"installs workflow"| node_claude_runtime
node_docs_plugin -->|"installs workflow"| node_claude_runtime
node_pr_plugin -.->|"may bundle tool config"| node_mcp
node_devops_plugin -->|"bundles operational scripts"| node_hooks
node_devops_plugin -->|"configures Kubernetes access"| node_external_services
node_markdown_corpus -->|"synchronized across languages"| node_translation_sync
node_translation_sync -->|"supplies localized content"| node_doc_build
node_markdown_corpus -->|"renders"| node_doc_build
node_doc_build -->|"validated and executed by"| node_github_actions
node_github_actions -->|"publishes"| node_published_docs

click node_readme "https://github.com/luongnv89/claude-howto/blob/main/README.md"
click node_roadmap "https://github.com/luongnv89/claude-howto/blob/main/LEARNING-ROADMAP.md"
click node_catalog "https://github.com/luongnv89/claude-howto/blob/main/CATALOG.md"
click node_core_modules "https://github.com/luongnv89/claude-howto/blob/main/01-slash-commands/optimize.md"
click node_assessment "https://github.com/luongnv89/claude-howto/blob/main/.claude/skills/self-assessment/SKILL.md"
click node_mcp "https://github.com/luongnv89/claude-howto/blob/main/05-mcp/multi-mcp.json"
click node_hooks "https://github.com/luongnv89/claude-howto/blob/main/06-hooks/pre-tool-check.sh"
click node_advanced "https://github.com/luongnv89/claude-howto/blob/main/09-advanced-features/config-examples.json"
click node_checkpoints "https://github.com/luongnv89/claude-howto/blob/main/08-checkpoints/README.md"
click node_pr_plugin "https://github.com/luongnv89/claude-howto/blob/main/07-plugins/pr-review/.claude-plugin/plugin.json"
click node_devops_plugin "https://github.com/luongnv89/claude-howto/blob/main/07-plugins/devops-automation/.claude-plugin/plugin.json"
click node_docs_plugin "https://github.com/luongnv89/claude-howto/blob/main/07-plugins/documentation/.claude-plugin/plugin.json"
click node_markdown_corpus "https://github.com/luongnv89/claude-howto/blob/main/LEARNING-ROADMAP.md"
click node_translation_sync "https://github.com/luongnv89/claude-howto/blob/main/scripts/sync_translations.py"
click node_doc_build "https://github.com/luongnv89/claude-howto/blob/main/scripts/build_website.py"
click node_github_actions "https://github.com/luongnv89/claude-howto/blob/main/.github/workflows/pages.yml"

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_readme,node_roadmap,node_catalog,node_core_modules,node_assessment toneBlue
class node_mcp,node_hooks,node_advanced,node_checkpoints,node_claude_runtime,node_external_services toneAmber
class node_pr_plugin,node_devops_plugin,node_docs_plugin toneMint
class node_markdown_corpus,node_translation_sync,node_doc_build,node_github_actions,node_published_docs toneRose
```

## Components

### Curriculum

Canonical learning content and navigation.

- [Repository entry](https://github.com/luongnv89/claude-howto/blob/main/README.md): Markdown guide · `README.md`
- [Learning roadmap](https://github.com/luongnv89/claude-howto/blob/main/LEARNING-ROADMAP.md): ordered curriculum · `LEARNING-ROADMAP.md`
- [Artifact catalog](https://github.com/luongnv89/claude-howto/blob/main/CATALOG.md): install index · `CATALOG.md`
- [Core modules](https://github.com/luongnv89/claude-howto/blob/main/01-slash-commands/optimize.md): tutorial templates · Commands, memory, skills, and delegated-agent examples. · `01-slash-commands/optimize.md`
- [Learning assessment](https://github.com/luongnv89/claude-howto/blob/main/.claude/skills/self-assessment/SKILL.md): Claude skills · Self-assessment and lesson quizzes produce learning feedback. · `.claude/skills/self-assessment/SKILL.md`

### Claude Code surfaces

Copyable extension examples consumed by Claude Code.

- [MCP configurations](https://github.com/luongnv89/claude-howto/blob/main/05-mcp/multi-mcp.json): tool integration config · Configures optional external tool servers. · `05-mcp/multi-mcp.json`
- [Hooks and scripts](https://github.com/luongnv89/claude-howto/blob/main/06-hooks/pre-tool-check.sh): event guardrails · Validation, scanning, tracking, and notifications. · `06-hooks/pre-tool-check.sh`
- [Advanced modes and CLI](https://github.com/luongnv89/claude-howto/blob/main/09-advanced-features/config-examples.json): operational guidance · Planning, background work, permissions, and headless CLI. · `09-advanced-features/config-examples.json`
- [Checkpoints guide](https://github.com/luongnv89/claude-howto/blob/main/08-checkpoints/README.md): session capability · Claude Code manages checkpoint state. · `08-checkpoints/README.md`
- **Claude Code runtime**: consumer runtime · Adopters install repository artifacts into user or project scope.
- **External services**: optional dependencies · GitHub, databases, filesystem, Kubernetes, and notifications.

### Plugin workflows

Composable distributable workflow examples.

- [PR review plugin](https://github.com/luongnv89/claude-howto/blob/main/07-plugins/pr-review/.claude-plugin/plugin.json): plugin bundle · `07-plugins/pr-review/.claude-plugin/plugin.json`
- [DevOps plugin](https://github.com/luongnv89/claude-howto/blob/main/07-plugins/devops-automation/.claude-plugin/plugin.json): plugin bundle · `07-plugins/devops-automation/.claude-plugin/plugin.json`
- [Documentation plugin](https://github.com/luongnv89/claude-howto/blob/main/07-plugins/documentation/.claude-plugin/plugin.json): plugin bundle · `07-plugins/documentation/.claude-plugin/plugin.json`

### Publishing pipeline

Build, localization, and GitHub Actions automation.

- [Markdown corpus](https://github.com/luongnv89/claude-howto/blob/main/LEARNING-ROADMAP.md): source content · Tutorials, templates, and parallel translations. · `LEARNING-ROADMAP.md`
- [Translation sync](https://github.com/luongnv89/claude-howto/blob/main/scripts/sync_translations.py): Python tooling · Synchronizes parallel language trees. · `scripts/sync_translations.py`
- [Website and EPUB builds](https://github.com/luongnv89/claude-howto/blob/main/scripts/build_website.py): Python build tooling · Renders site pages and offline EPUB artifacts. · `scripts/build_website.py`
- [GitHub Actions](https://github.com/luongnv89/claude-howto/blob/main/.github/workflows/pages.yml): CI and release workflows · Validates tooling and docs, publishes pages, and governs releases. · `.github/workflows/pages.yml`
- **Published artifacts**: documentation output · Website and offline EPUB distributions.

## Connections

- Repository entry → Learning roadmap: guides learners to
- Repository entry → Artifact catalog: links installable artifacts
- Learning roadmap → Core modules: orders
- Core modules → Claude Code runtime: copied into
- Learning assessment → Claude Code runtime: runs as repository-local skills
- MCP configurations → Claude Code runtime: installed for tool access
- Hooks and scripts → Claude Code runtime: installed as lifecycle guardrails
- Advanced modes and CLI → Claude Code runtime: documents operation
- Checkpoints guide → Claude Code runtime: explains session feature
- Claude Code runtime → External services: uses configured tools
- PR review plugin → Claude Code runtime: installs workflow
- DevOps plugin → Claude Code runtime: installs workflow
- Documentation plugin → Claude Code runtime: installs workflow
- PR review plugin → MCP configurations: may bundle tool config
- DevOps plugin → Hooks and scripts: bundles operational scripts
- DevOps plugin → External services: configures Kubernetes access
- Markdown corpus → Translation sync: synchronized across languages
- Translation sync → Website and EPUB builds: supplies localized content
- Markdown corpus → Website and EPUB builds: renders
- Website and EPUB builds → GitHub Actions: validated and executed by
- GitHub Actions → Published artifacts: publishes
