# florianbruniaux/claude-code-ultimate-guide architecture

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

- Interactive diagram: https://gitdiagram.com/florianbruniaux/claude-code-ultimate-guide
- Repository: https://github.com/florianbruniaux/claude-code-ultimate-guide

## Overview

1. This repo is a documentation platform, not a single app. Its core product is the “Claude Code Ultimate Guide,” and the repository is organized around source content, machine-readable indexes, interactive utilities, and publication automation.

2. The primary content layer lives under `guide/`. It is the canonical human-readable knowledge base: the main guide (`guide/ultimate-guide.md`), deep-dive sections (`guide/core/`, `guide/security/`, `guide/ops/`, `guide/workflows/`, `guide/roles/`, `guide/ecosystem/`), and diagram pages (`guide/diagrams/`). These files are the source of truth for the website, PDF/EPUB exports, and the MCP server.

3. The `examples/` tree is the repository’s pattern library. It holds concrete templates for agents, slash commands, hooks, skills, plugins, configs, scripts, and workflow examples. Architecturally, this is the “implementation catalog” that supports the conceptual guide: readers move from theory in `guide/` to copyable patterns in `examples/`.

4. The `quiz/` subsystem is a separate interactive product built from YAML question banks and a small JavaScript CLI app (`quiz/src/`). It turns the guide into a knowledge-checking workflow with scoring, profiles, and topic categories. The quiz depends on the content structure of the guide, but runs independently as a local Node-based app.

5. `machine-readable/` is the indexing layer for automation and AI consumption. `reference.yaml`, `llms.txt`, and the release/content YAML files provide structured pointers into the guide and related artifacts. This layer is important because it is used by the landing-site search and by AI tools that need compact, deterministic context rather than full-text scraping.

6. The `mcp-server/` directory is the main runtime integration boundary. It is a TypeScript MCP server packaged for `npx` use, exposing tools for searching and reading guide content, browsing examples, comparing releases, and querying threats. Internally it uses dedicated modules for content loading, caching, section reading, search, changelog parsing, and URL resolution, so it acts as a query API over the repository’s documentation corpus.

7. The repo’s automation layer sits in `scripts/` and `.github/workflows/`. These scripts generate exports, preprocess guide content, update release data, validate onboarding material, and synchronize indexes/versioning. GitHub Actions then consume those outputs to rebuild exports and trigger the landing-site deployment, making publication a repeatable pipeline rather than a manual copy-paste process.

8. Security is a first-class subsystem rather than a topic buried in the guide. The security model is distributed across `guide/security/`, `machine-readable/threat-db.yaml`, and the security-focused example hooks/commands under `examples/hooks/` and `examples/commands/`. The repo explicitly treats prompt injection, malicious skills, MCP trust, sandboxing, and data leakage as architectural concerns.

9. The `docs/resource-evaluations/` tree is the curation and evidence layer. It contains structured reviews of external articles, tools, and ecosystem signals, which are then folded back into the guide’s recommendations. This creates a feedback loop: external research is evaluated, summarized, and incorporated into the canonical docs.

10. The publishing boundary is split between source and generated artifacts. Source content lives in Markdown/YAML/JS/TS/scripts, while outputs include PDFs, EPUBs, recap cards, exported landing content, and release assets under `exports/` and related generated files. That separation matters for the diagram: content flows from source docs into indexes, exports, and deployment targets.

11. Operationally, the repo is maintained as a living knowledge base with versioning and daily refreshes. Files like `CHANGELOG.md`, `VERSION`, `recap-hashes.json`, and the release-update scripts indicate that the guide is continuously recompiled and re-indexed as Claude Code evolves.

12. The external-facing surfaces are the GitHub Pages landing site, downloadable guide artifacts, the MCP package, and the quiz CLI. In architectural terms, the repo supports three consumption modes: read the guide directly, query it through MCP/CLI automation, or consume generated/exported assets through the website and releases.

Main entry points: [`guide/ultimate-guide.md`](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md) (Ultimate Guide), [`examples/README.md`](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/README.md) (Examples), [`mcp-server/src/index.ts`](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/index.ts) (MCP Server), [`machine-readable/reference.yaml`](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/machine-readable/reference.yaml) (Machine Indexes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Canonical content"]
  node_guide_ultimate["Ultimate Guide<br/>canonical guide<br/>[ultimate-guide.md]"]
  node_guide_core["Core Topics<br/>guide section<br/>[architecture.md]"]
  node_guide_security["Security<br/>guide section"]
  node_guide_workflows["Workflows<br/>guide section<br/>[README.md]"]
  node_guide_diagrams["Diagrams<br/>visual index<br/>[README.md]"]
end

subgraph group_patterns["Pattern library"]
  node_examples_root["Examples<br/>pattern library<br/>[README.md]"]
  node_examples_agents["Agents<br/>agent patterns<br/>[planner.md]"]
  node_examples_commands["Commands<br/>command patterns<br/>[security.md]"]
  node_examples_hooks["Hooks<br/>hook patterns<br/>[README.md]"]
  node_examples_skills["Skills<br/>skill patterns<br/>[SKILL.md]"]
end

subgraph group_integrations["Runtime surfaces"]
  node_mcp_server["MCP Server<br/>query API<br/>[index.ts]"]
  node_quiz_app["Quiz CLI<br/>interactive app<br/>[index.js]"]
  node_guide_search_tool["Search Guide<br/>mcp tool<br/>[search-guide.ts]"]
  node_threats_tool["Threats Tool<br/>mcp tool<br/>[threats.ts]"]
  node_quiz_bank["Question Bank<br/>quiz content"]
end

subgraph group_automation["Publication automation"]
  node_machine_indexes["Machine Indexes<br/>structured index<br/>[reference.yaml]"]
  node_release_data["Release Data<br/>content index"]
  node_export_scripts["Export Scripts<br/>build pipeline"]
  node_release_workflows["GitHub Actions<br/>delivery automation"]
end

subgraph group_evidence["Research and curation"]
  node_research_layer["Resource Evaluations<br/>curation corpus<br/>[README.md]"]
end

subgraph group_outputs["Published artifacts"]
  node_exports_bundle["Exports<br/>published artifacts<br/>[README.md]"]
end

node_guide_ultimate -->|"structures"| node_guide_core
node_guide_ultimate -->|"covers"| node_guide_security
node_guide_ultimate -->|"covers"| node_guide_workflows
node_guide_ultimate -->|"navigates"| node_guide_diagrams
node_guide_ultimate -->|"maps to"| node_examples_root
node_examples_root -->|"contains"| node_examples_agents
node_examples_root -->|"contains"| node_examples_commands
node_examples_root -->|"contains"| node_examples_hooks
node_examples_root -->|"contains"| node_examples_skills
node_guide_ultimate -->|"indexed by"| node_machine_indexes
node_machine_indexes -->|"includes"| node_release_data
node_machine_indexes -->|"feeds"| node_mcp_server
node_guide_ultimate -->|"queried via"| node_mcp_server
node_mcp_server -->|"exposes"| node_guide_search_tool
node_mcp_server -->|"exposes"| node_threats_tool
node_quiz_app -->|"loads"| node_quiz_bank
node_quiz_bank -.->|"checks"| node_guide_ultimate
node_research_layer -->|"informs"| node_guide_core
node_research_layer -->|"informs"| node_guide_security
node_export_scripts -->|"builds"| node_exports_bundle
node_export_scripts -->|"updates"| node_machine_indexes
node_release_workflows -->|"runs"| node_export_scripts
node_release_workflows -->|"publishes"| node_exports_bundle
node_release_workflows -->|"deploys"| node_mcp_server
node_guide_security -.->|"anchors"| node_threats_tool
node_examples_hooks -.->|"implements"| node_guide_security
node_examples_commands -.->|"implements"| node_guide_workflows
node_examples_agents -.->|"implements"| node_guide_workflows
node_guide_diagrams -.->|"summarizes"| node_guide_core

click node_guide_ultimate "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md"
click node_guide_core "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md"
click node_guide_security "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md"
click node_guide_workflows "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/README.md"
click node_guide_diagrams "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/diagrams/README.md"
click node_examples_root "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/README.md"
click node_examples_agents "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/agents/planner.md"
click node_examples_commands "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/commands/security.md"
click node_examples_hooks "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/hooks/README.md"
click node_examples_skills "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/skills/guide-recap/SKILL.md"
click node_mcp_server "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/index.ts"
click node_quiz_app "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/quiz/src/index.js"
click node_machine_indexes "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/machine-readable/reference.yaml"
click node_release_data "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/machine-readable/claude-code-releases.yaml"
click node_export_scripts "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/scripts/generate-guide-exports.sh"
click node_release_workflows "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/.github/workflows/rebuild-guide-exports.yml"
click node_research_layer "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/docs/resource-evaluations/README.md"
click node_exports_bundle "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/exports/README.md"
click node_guide_search_tool "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/tools/search-guide.ts"
click node_threats_tool "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/tools/threats.ts"
click node_quiz_bank "https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/quiz/questions/01-quick-start.yaml"

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_guide_ultimate,node_guide_core,node_guide_security,node_guide_workflows,node_guide_diagrams toneBlue
class node_examples_root,node_examples_agents,node_examples_commands,node_examples_hooks,node_examples_skills toneAmber
class node_mcp_server,node_quiz_app,node_guide_search_tool,node_threats_tool,node_quiz_bank toneMint
class node_machine_indexes,node_release_data,node_export_scripts,node_release_workflows toneRose
class node_research_layer toneIndigo
class node_exports_bundle toneTeal
```

## Components

### Canonical content

Human-authored guide source and its main topic sections

- [Ultimate Guide](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md): canonical guide · Main human-readable source of truth for the repo · `guide/ultimate-guide.md`
- [Core Topics](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/core/architecture.md): guide section · Foundational concepts, releases, glossary, and architecture · `guide/core/architecture.md`
- [Security](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/security/production-safety.md): guide section · Safety, sandboxing, privacy, and governance guidance · `guide/security/production-safety.md`
- [Workflows](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/README.md): guide section · Operational patterns and end-to-end usage workflows · `guide/workflows/README.md`
- [Diagrams](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/guide/diagrams/README.md): visual index · Curated diagram pages for navigating the documentation system · `guide/diagrams/README.md`

### Pattern library

Copyable examples for agents, commands, hooks, skills, and workflows

- [Examples](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/README.md): pattern library · Implementation catalog of reusable templates and patterns · `examples/README.md`
- [Agents](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/agents/planner.md): agent patterns · Representative agent templates and role definitions · `examples/agents/planner.md`
- [Commands](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/commands/security.md): command patterns · Slash-command examples for review, security, and workflow automation · `examples/commands/security.md`
- [Hooks](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/hooks/README.md): hook patterns · Event-driven guardrails, checkpoints, and session instrumentation · `examples/hooks/README.md`
- [Skills](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/examples/skills/guide-recap/SKILL.md): skill patterns · Packaged reusable skills and sub-workflows · `examples/skills/guide-recap/SKILL.md`

### Runtime surfaces

MCP server and quiz CLI that query or consume the guide

- [MCP Server](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/index.ts): query API · TypeScript service exposing repository content as tools and resources · `mcp-server/src/index.ts`
- [Quiz CLI](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/quiz/src/index.js): interactive app · Node-based knowledge-checking workflow over the guide · `quiz/src/index.js`
- [Search Guide](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/tools/search-guide.ts): mcp tool · MCP search entrypoint over the guide corpus · `mcp-server/src/tools/search-guide.ts`
- [Threats Tool](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/mcp-server/src/tools/threats.ts): mcp tool · MCP access to the security and threat knowledge layer · `mcp-server/src/tools/threats.ts`
- [Question Bank](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/quiz/questions/01-quick-start.yaml): quiz content · Topic-based YAML questions that mirror the guide structure · `quiz/questions/01-quick-start.yaml`

### Publication automation

Scripts and workflows that preprocess, export, and refresh repo artifacts

- [Machine Indexes](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/machine-readable/reference.yaml): structured index · Deterministic YAML and text indexes for automation and AI tools · `machine-readable/reference.yaml`
- [Release Data](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/machine-readable/claude-code-releases.yaml): content index · Versioned release and changelog metadata used by refresh flows · `machine-readable/claude-code-releases.yaml`
- [Export Scripts](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/scripts/generate-guide-exports.sh): build pipeline · Scripts that preprocess guide content and generate distributable outputs · `scripts/generate-guide-exports.sh`
- [GitHub Actions](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/.github/workflows/rebuild-guide-exports.yml): delivery automation · Workflows that rebuild exports and trigger landing-site deployment · `.github/workflows/rebuild-guide-exports.yml`

### Research and curation

External evaluations folded back into the guide

- [Resource Evaluations](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/docs/resource-evaluations/README.md): curation corpus · Structured external research and evidence folded back into recommendations · `docs/resource-evaluations/README.md`

### Published artifacts

Generated or distributable outputs

- [Exports](https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/main/exports/README.md): published artifacts · Generated guide outputs and distributable assets · `exports/README.md`

## Connections

- Ultimate Guide → Core Topics: structures · Main guide decomposes into core concepts and reference sections
- Ultimate Guide → Security: covers · Security is a first-class topic in the canonical guide
- Ultimate Guide → Workflows: covers · Workflows are documented as repeatable operating patterns
- Ultimate Guide → Diagrams: navigates · Diagram pages provide a visual entry to the guide
- Ultimate Guide → Examples: maps to · Concepts in the guide are grounded in copyable examples
- Examples → Agents: contains · Agent templates form one major example family
- Examples → Commands: contains · Command templates are part of the pattern library
- Examples → Hooks: contains · Hooks provide guardrails and event-driven automation patterns
- Examples → Skills: contains · Skills package reusable sub-workflows and behaviors
- Ultimate Guide → Machine Indexes: indexed by · Structured indexes expose guide content for deterministic lookup
- Machine Indexes → Release Data: includes · Release and changelog metadata are part of the machine-readable layer
- Machine Indexes → MCP Server: feeds · MCP tools consume the structured content indexes
- Ultimate Guide → MCP Server: queried via · The MCP server provides programmatic access to the documentation corpus
- MCP Server → Search Guide: exposes · Search is a primary MCP capability over the guide
- MCP Server → Threats Tool: exposes · Security/threat queries are exposed as a dedicated tool
- Quiz CLI → Question Bank: loads · The CLI runs against topic-based YAML questions
- Question Bank → Ultimate Guide: checks · Quiz content mirrors the guide’s structure and concepts
- Resource Evaluations → Core Topics: informs · Evaluations and external research feed back into recommendations
- Resource Evaluations → Security: informs · Security evaluations shape the repo’s defensive guidance
- Export Scripts → Exports: builds · Scripts generate PDFs, EPUBs, recap cards, and related artifacts
- Export Scripts → Machine Indexes: updates · Build scripts refresh machine-readable indexes and derived data
- GitHub Actions → Export Scripts: runs · GitHub Actions orchestrate the export and refresh scripts
- GitHub Actions → Exports: publishes · Workflows rebuild and deliver generated artifacts
- GitHub Actions → MCP Server: deploys · Automation also packages the MCP integration boundary
- Security → Threats Tool: anchors · Security guidance is surfaced through the threat-query tool
- Hooks → Security: implements · Security-oriented hooks operationalize the safety model
- Commands → Workflows: implements · Commands instantiate workflow patterns from the guide
- Agents → Workflows: implements · Agent templates operationalize collaborative workflows
- Diagrams → Core Topics: summarizes · Visual pages synthesize the core architecture
