# quinnaho/claudemap architecture

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

- Interactive diagram: https://gitdiagram.com/quinnaho/claudemap
- Repository: https://github.com/quinnaho/claudemap

## Overview

1. **This repo is a monorepo for “ClaudeMap” with three main runtime surfaces:**  
   - an interactive **map UI** in `app/`  
   - a **skill/CLI layer** in `skill/` that runs inside Claude Code or Codex  
   - a set of **build and packaging scripts** in `scripts/` plus a thin CLI entrypoint in `bin/`

2. **The core product flow is: source code → semantic graph → map artifacts → visual exploration.**  
   The skill layer scans a target repository, builds a concept-oriented graph, enriches it with AI-assisted descriptions and health/status data, then writes map/runtime JSON artifacts. The app consumes those artifacts and renders the navigable map. This is the primary data boundary in the system.

3. **`skill/` is the orchestration and analysis engine.**  
   It contains commands like `setup-claudemap`, `refresh`, `show`, `snapshot`, and `create-map`, plus helpers for project-root discovery, file walking, import resolution, manifest/scope resolution, cache, launcher behavior, and MCP integration. This layer is what actually “understands” a repo and produces map state.

4. **The skill layer is designed around assistant command execution.**  
   `skill/lib/command-harness/` wraps slash-command execution, argument parsing, logging, enrichment I/O, and MCP wiring. This is the boundary where Claude Code or Codex invokes ClaudeMap behavior. The `skill/prompts/` directory holds the prompt templates used to drive enrichment and scoped enrichment.

5. **`skill/lib/contracts/` and `app/src/contracts/` define the shared shape of map data.**  
   Both sides have explicit contract modules for graph sources, paths, presentation, tokens/branding, and schema/version handling. This is important architecturally: the skill emits structured graph/runtime data, and the app relies on the same contract vocabulary to render it consistently.

6. **`app/` is a Vite/React frontend specialized for graph visualization and runtime playback.**  
   The root `App.jsx` composes graph canvas, top bar, map selector, status bar, zoom controls, and presentation overlays. The main visual subsystem lives under `app/src/components/graph/`, where node types, custom edges, handles, runtime overlays, and affordances are rendered.

7. **The UI’s state is split into graph, runtime, and UI slices.**  
   `app/src/store/graphSlice.js`, `runtimeSlice.js`, and `uiSlice.js` form the application state boundary, with selectors in `store/selectors.js`. Hooks such as `useRuntimeSync`, `useRuntimePolling`, `useGraphViewModel`, and `useGraphPointerHandlers` connect the visual layer to runtime updates, hover/focus behavior, and layout state.

8. **Graph layout is a distinct subsystem from rendering.**  
   The `app/src/lib/` directory contains graph transforms, layout engines, semantic/top-level/system-tree layout helpers, edge layout, node utilities, and view transforms. This suggests a pipeline where raw map data is normalized into positioned graph structures before React renders them. The diagram should show “layout computation” as a middle layer between data and canvas.

9. **There is a runtime/state loop that keeps the map presentation synchronized.**  
   The app includes runtime assets and polling hooks, and the repo ships `claudemap-runtime*.json` files in `app/public/` and `docs/`. The runtime files appear to drive presentation state, focus/highlight changes, and assistant-guided walkthroughs. This is the mechanism behind `/explain` and `/show` style interactions.

10. **Assistant-facing presentation is part of the product, not just a backend feature.**  
   The `app/src/components/graph/PresentationOverlay.jsx`, `GraphRuntime.jsx`, and `FloatingDescription.jsx` indicate that explanations are rendered directly on top of the graph. The assistant doesn’t just return text; it can steer the viewport and annotate specific nodes/paths in the UI.

11. **Build and distribution are multi-targeted.**  
   `scripts/build-site.js` publishes the standalone site in `docs/`, while other scripts package the skill, generate the seed map, check contracts, and run smoke tests. The repository therefore has at least two deployables: the interactive preview site and the installable assistant skill/package.

12. **`docs/` is a generated/static distribution, not the source of truth.**  
   It contains built JS/CSS assets, deployed JSON map/runtime files, and a static `index.html` for the hosted demo. The source lives in `app/` and `skill/`; `docs/` is the published artifact for the public preview.

13. **`claudemap-maps.json` and the seed-map contract provide initial navigation metadata.**  
   The repo includes a seed map in `contracts/claudemap-seed-map.json` plus generated map manifests at the root, in `app/public/`, and under `docs/`. These artifacts seed the visualization so the UI can load a repo’s conceptual map before or alongside assistant-driven refinement.

14. **The important architectural boundaries to show in a diagram are:**  
   - source repository being analyzed  
   - skill/CLI analysis and enrichment pipeline  
   - shared contracts/schemas  
   - generated map/runtime artifacts  
   - React/Vite graph UI and its runtime state loop  
   - packaging/build scripts that publish the app and skill  
   - external assistant runtimes: Claude Code, Codex, and MCP where applicable

Main entry points: [`skill/lib`](https://github.com/quinnaho/claudemap/tree/main/skill/lib) (Analysis engine), [`app/src/components/graph`](https://github.com/quinnaho/claudemap/tree/main/app/src/components/graph) (Graph canvas), [`skill`](https://github.com/quinnaho/claudemap/tree/main/skill) (Skill CLI), [`docs/claudemap-runtime.json`](https://github.com/quinnaho/claudemap/blob/main/docs/claudemap-runtime.json) (Map artifacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime surfaces"]
  node_app_shell["App shell<br/>react frontend<br/>[App.jsx]"]
  node_graph_canvas["Graph canvas<br/>visualization layer"]
  node_layout_engine["Layout engine<br/>positioning pipeline"]
  node_state_store["State store<br/>ui runtime state"]
  node_runtime_sync["Runtime sync<br/>polling and hooks"]
end

subgraph group_group_skill["Skill pipeline"]
  node_skill_cli["Skill CLI<br/>assistant skill"]
  node_command_harness["Command harness<br/>slash command runtime"]
  node_analysis_pipeline["Analysis engine<br/>scan and enrich"]
  node_manifest_scope["Manifest scope<br/>repo state"]
  node_prompt_pack["Prompt pack<br/>enrichment prompts"]
  node_mcp_bridge["MCP bridge<br/>assistant integration<br/>[mcp-client.js]"]
end

subgraph group_group_build["Build and distribution"]
  node_bin_entry["CLI entry<br/>node launcher<br/>[claudemap.js]"]
  node_docs_site["Docs site<br/>static demo"]
  node_packaging_scripts["Packaging scripts<br/>build pipeline"]
end

subgraph group_group_data["Shared data"]
  node_shared_contracts["Shared contracts<br/>schema vocabulary"]
  node_app_contracts["App contracts<br/>frontend schema vocabulary"]
  node_generated_artifacts["Map artifacts<br/>generated json"]
end

node_source_repo[("Target repo<br/>input repository")]

node_source_repo -->|"analyzed by"| node_skill_cli
node_skill_cli -->|"executes"| node_command_harness
node_command_harness -->|"drives"| node_analysis_pipeline
node_analysis_pipeline -->|"resolves"| node_manifest_scope
node_analysis_pipeline -->|"emits"| node_shared_contracts
node_analysis_pipeline -->|"uses"| node_prompt_pack
node_analysis_pipeline -->|"integrates"| node_mcp_bridge
node_shared_contracts -->|"mirrors"| node_app_contracts
node_analysis_pipeline -->|"writes"| node_generated_artifacts
node_generated_artifacts -->|"loads into"| node_app_shell
node_app_shell -->|"composes"| node_graph_canvas
node_graph_canvas -->|"uses"| node_layout_engine
node_layout_engine -->|"reads"| node_state_store
node_state_store -->|"updates"| node_runtime_sync
node_runtime_sync -->|"steers"| node_graph_canvas
node_packaging_scripts -->|"builds"| node_docs_site
node_packaging_scripts -->|"packages"| node_skill_cli
node_bin_entry -->|"launches"| node_skill_cli
node_generated_artifacts -->|"published in"| node_docs_site
node_app_contracts -->|"drives"| node_graph_canvas

click node_skill_cli "https://github.com/quinnaho/claudemap/tree/main/skill"
click node_command_harness "https://github.com/quinnaho/claudemap/tree/main/skill/lib/command-harness"
click node_analysis_pipeline "https://github.com/quinnaho/claudemap/tree/main/skill/lib"
click node_manifest_scope "https://github.com/quinnaho/claudemap/tree/main/skill/lib/manifest"
click node_shared_contracts "https://github.com/quinnaho/claudemap/tree/main/skill/lib/contracts"
click node_prompt_pack "https://github.com/quinnaho/claudemap/tree/main/skill/prompts"
click node_mcp_bridge "https://github.com/quinnaho/claudemap/blob/main/skill/lib/mcp-client.js"
click node_bin_entry "https://github.com/quinnaho/claudemap/blob/main/bin/claudemap.js"
click node_app_shell "https://github.com/quinnaho/claudemap/blob/main/app/src/App.jsx"
click node_graph_canvas "https://github.com/quinnaho/claudemap/tree/main/app/src/components/graph"
click node_layout_engine "https://github.com/quinnaho/claudemap/tree/main/app/src/lib"
click node_state_store "https://github.com/quinnaho/claudemap/tree/main/app/src/store"
click node_runtime_sync "https://github.com/quinnaho/claudemap/tree/main/app/src/hooks"
click node_app_contracts "https://github.com/quinnaho/claudemap/tree/main/app/src/contracts"
click node_generated_artifacts "https://github.com/quinnaho/claudemap/blob/main/docs/claudemap-runtime.json"
click node_docs_site "https://github.com/quinnaho/claudemap/tree/main/docs"
click node_packaging_scripts "https://github.com/quinnaho/claudemap/tree/main/scripts"

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_app_shell,node_graph_canvas,node_layout_engine,node_state_store,node_runtime_sync toneBlue
class node_skill_cli,node_command_harness,node_analysis_pipeline,node_manifest_scope,node_prompt_pack,node_mcp_bridge toneAmber
class node_bin_entry,node_docs_site,node_packaging_scripts toneMint
class node_shared_contracts,node_app_contracts,node_generated_artifacts toneRose
class node_source_repo toneNeutral
```

## Components

### Runtime surfaces

Interactive app and assistant-facing CLI runtime.

- [App shell](https://github.com/quinnaho/claudemap/blob/main/app/src/App.jsx): react frontend · Vite/React entry that composes the map experience. · `app/src/App.jsx`
- [Graph canvas](https://github.com/quinnaho/claudemap/tree/main/app/src/components/graph): visualization layer · Renders nodes, edges, affordances, overlays, and node-specific views. · `app/src/components/graph`
- [Layout engine](https://github.com/quinnaho/claudemap/tree/main/app/src/lib): positioning pipeline · Transforms semantic graph data into positioned graph structures. · `app/src/lib`
- [State store](https://github.com/quinnaho/claudemap/tree/main/app/src/store): ui runtime state · Holds graph, runtime, and UI slices plus selectors. · `app/src/store`
- [Runtime sync](https://github.com/quinnaho/claudemap/tree/main/app/src/hooks): polling and hooks · Keeps presentation state and graph focus synchronized. · `app/src/hooks`

### Skill pipeline

Repo analysis, enrichment, contracts, and command orchestration.

- [Skill CLI](https://github.com/quinnaho/claudemap/tree/main/skill): assistant skill · Command surface invoked inside Claude Code or Codex. · `skill`
- [Command harness](https://github.com/quinnaho/claudemap/tree/main/skill/lib/command-harness): slash command runtime · Runs slash commands, parses args, logs, and wires MCP. · `skill/lib/command-harness`
- [Analysis engine](https://github.com/quinnaho/claudemap/tree/main/skill/lib): scan and enrich · Walks files, resolves imports, builds graphs, and adds health and descriptions. · `skill/lib`
- [Manifest scope](https://github.com/quinnaho/claudemap/tree/main/skill/lib/manifest): repo state · Resolves scope, fingerprints, and active-map metadata. · `skill/lib/manifest`
- [Prompt pack](https://github.com/quinnaho/claudemap/tree/main/skill/prompts): enrichment prompts · Prompt templates that drive assistant-assisted enrichment. · `skill/prompts`
- [MCP bridge](https://github.com/quinnaho/claudemap/blob/main/skill/lib/mcp-client.js): assistant integration · Connects skill execution to MCP-enabled assistant runtimes. · `skill/lib/mcp-client.js`

### Build and distribution

Packaging scripts and published artifacts.

- [CLI entry](https://github.com/quinnaho/claudemap/blob/main/bin/claudemap.js): node launcher · Thin executable entrypoint for the package. · `bin/claudemap.js`
- [Docs site](https://github.com/quinnaho/claudemap/tree/main/docs): static demo · Published static preview and hosted demo output. · `docs`
- [Packaging scripts](https://github.com/quinnaho/claudemap/tree/main/scripts): build pipeline · Builds the site, packages the skill, and checks contracts. · `scripts`

### Shared data

Schemas and generated map/runtime files used across surfaces.

- [Shared contracts](https://github.com/quinnaho/claudemap/tree/main/skill/lib/contracts): schema vocabulary · Common graph, path, presentation, and version contracts used by skill and app. · `skill/lib/contracts`
- [App contracts](https://github.com/quinnaho/claudemap/tree/main/app/src/contracts): frontend schema vocabulary · Frontend-side contract modules for map, presentation, paths, tokens, and zoom. · `app/src/contracts`
- [Map artifacts](https://github.com/quinnaho/claudemap/blob/main/docs/claudemap-runtime.json): generated json · Runtime and map JSON consumed by the app and published for distribution. · `docs/claudemap-runtime.json`

### Other components

- **Target repo**: input repository · Repository being scanned and mapped by ClaudeMap.

## Connections

- Target repo → Skill CLI: analyzed by · The target repository is scanned from the skill surface.
- Skill CLI → Command harness: executes · Assistant commands are routed through the harness.
- Command harness → Analysis engine: drives · Command execution triggers scanning, enrichment, and map generation.
- Analysis engine → Manifest scope: resolves · Analysis is constrained by project scope and manifest state.
- Analysis engine → Shared contracts: emits · Produces structured graph and runtime data using shared contracts.
- Analysis engine → Prompt pack: uses · Prompt templates guide enrichment passes.
- Analysis engine → MCP bridge: integrates · MCP wiring supports assistant-driven operations.
- Shared contracts → App contracts: mirrors · Frontend and skill share the same map vocabulary.
- Analysis engine → Map artifacts: writes · Map and runtime JSON artifacts are produced from the analysis pipeline.
- Map artifacts → App shell: loads into · The UI consumes generated map/runtime state.
- App shell → Graph canvas: composes · Shell assembles the graph visualization experience.
- Graph canvas → Layout engine: uses · Rendering depends on computed layout and transforms.
- Layout engine → State store: reads · Layout and view state are coordinated through the store.
- State store → Runtime sync: updates · Runtime hooks observe store slices and synchronize presentation.
- Runtime sync → Graph canvas: steers · Focus, hover, and presentation updates affect the graph view.
- Packaging scripts → Docs site: builds · Scripts publish the static demo and bundled assets.
- Packaging scripts → Skill CLI: packages · Scripts also package and install the assistant skill.
- CLI entry → Skill CLI: launches · The executable entrypoint boots the skill surface.
- Map artifacts → Docs site: published in · Runtime and map JSON are included in the public demo output.
- App contracts → Graph canvas: drives · Presentation and motion contracts shape the UI components.