See any codebase as a map, not a maze.
ArchMap turns a repository into an interactive architecture map — entry points, routes, services, data layer, external dependencies — computed from the real import graph, in your browser. Every wire carries file:line evidence, every question is answered by graph computation, every map is editable, and a Designer turns a plain-language product idea into a proposed architecture. One static page, zero backend: code never leaves your machine.
Live: https://0-uddeshya-0.github.io/archmap/ · Demo: the specimen on the landing page is ArchMap mapping its own source — open it full-screen with one click.
The interface is a light-first "flight plan": numbered mission phases, checklist rows, and computed GO/NO-GO verification stamps (dark mode included, one toggle away). See DESIGN.md for the design system.
| Source | How | Privacy |
|---|---|---|
| GitHub URL | Paste https://github.com/owner/repo (private repos: add a token in Settings) |
Fetched client-side from the GitHub API |
| Local folder | Drag-and-drop or folder picker | Files never leave your machine |
| archmap.json | Import a map generated by the bundled Claude Code skill or exported earlier | Pure data, shareable |
| Deployed website | Best-effort surface map (pages, scripts, form endpoints) | Limited by CORS; real architecture needs source |
- Real dependency graph for ten languages: JS/TS and Python (path-resolved imports, tsconfig aliases, monorepo packages) plus C#, Go, Java, Kotlin, Rust, Ruby, PHP, and C/C++ via a two-pass symbol table — each file's namespace/package declarations are matched against imports, the approach proven by emerge
- Cluster inference: client / entry / routes / services / data / external / tests
- HTTP route extraction (Express-style
app.get(...), Flask/FastAPI decorators, Spring/ASP.NET attributes,urls.py) - Critical path from the entry point to the data/external layer
- Dead code: files whose exports have zero live callers anywhere in the repo (drawn dashed)
- Circular imports: strongly-connected components, flagged on the map and in findings
- Layering violations: data-layer files that import upward into routes/UI
- Hot paths (fan-in), oversized files, multiple-datastore warnings, framework detection
- A full inventory: files kept off the map for readability stay listed, searchable, and expandable — nothing is hidden, only de-emphasized
Click any wire to see exactly why it exists: the file:line of the import statement that created it, the import specifier, and (for GitHub repos) a link straight to that line. Comments are blanked, not removed, during parsing, so line numbers are exact. The sidebar's self-check line reports the map's own validation — nodes, wires, evidence coverage, inconsistencies — computed live, never asserted.
Type a question in the top bar. A deterministic query engine parses it and answers by graph computation — the answer can never be hallucinated because no model writes it:
who imports store.js/what does api.js import→ transitive reach with a receiptpath from index.js to db/how does app reach pg→ shortest real import chaindead code·circular imports·biggest files·most imported·critical path·endpoints·external·stats·show the data layer·explain store.js
With an Anthropic key set, questions the local parser can't handle are translated by Claude into one of those structured queries — translation only; the answer is still computed from the graph. Misses are reported honestly ("No file on this map matches…").
✎ Design a new system takes a plain-language product description, asks a short round of sharp clarifying questions (the grill), and generates a complete proposed architecture in the same map format — critical path marked, every assumption listed in the findings.
- Without an API key: a six-question form composes a starter blueprint deterministically from vetted patterns — clearly labeled as such, never pretending to be tailored AI.
- With a key: Claude asks questions specific to your idea and generates the design. Every candidate is machine-validated before it renders; invalid output is sent back with the exact errors for up to two repair rounds. A design that fails validation is refused, not patched over.
The result opens in edit mode: drag nodes (cluster boxes follow), click a node or wire to edit it in the inspector, add components, draw wires, delete, undo (⌘/Ctrl+Z) — or type an instruction like "add a Redis cache between the API and the database". Instructions become checked patch operations applied through the same validated engine as manual edits; ops referencing things that don't exist are rejected and reported, never guessed at. Drafts autosave to your browser; resume from the landing page.
Editing works on analyzed maps too (annotate, correct, extend) — the map is marked "manually edited" for honesty.
Every wire is an import that exists in the code — exploration never invents topology.
| Action | Control |
|---|---|
| Spotlight a file's wires · pin it · zoom to it | hover · click · double-click |
| Guided tour — short chapters in plain English | g or ▶ Tour · [ ] to change chapter |
| Trace upstream (what feeds this file) / downstream (what it reaches) | select a file → u / d — receipt shows files · imports · hops |
| Route probe: shortest real import chain between two files | r, then click origin and destination |
| Search any file — including ones grouped off the map | / |
| Play the critical-path trace | p |
| Fit · zoom · minimap · theme · help | f/0 · +/− · m · t · ? |
| Expand a "+N more files" group | click it → expand one file or the whole cluster |
Deep links restore state: #focus=<node>, #focus=<node>&reach=up, #route=<a>~<b>, #view=<chapter> — the ⧉ Copy link button builds them for you. They work in exported HTML files too.
- Interactive HTML — one self-contained file embedding the data and the complete viewer: tour, reach, route probe, minimap, keyboard, deep links, the ask-the-map engine, and the manual editor. Openable anywhere, no server.
- archmap.json — portable data, re-importable on the site (validated on import).
- SVG / PNG — the full map in the current theme, free of viewer state, for docs and PRs.
Add an Anthropic API key in Settings:
- ✦ AI enrich — Claude (
claude-opus-5) reads excerpts of the most important files and writes plain-English descriptions per node, a system overview, and maintainer findings. - ✦ Find bugs — Claude scans the most important files and reports only problems it can actually see, each with
path:lineevidence. Requests that trip the model's safety classifiers automatically fall back toclaude-opus-4-8server-side.
The key is stored only in your browser's localStorage; requests go directly to api.anthropic.com.
Turn the map into a debugging view: nodes with open bugs glow red, nodes with planned repairs glow green, and clicking any node opens a structured panel — known bugs (severity + file:line evidence), planned fixes, what the file does, and what feeds it.
Load bugs three ways: ✦ Find bugs with AI, paste/import your own JSON ({ "bugs": { "<node-id>": [...] }, "fixes": {...} }), or ship them in an archmap.json from the Claude Code skill. Toggle with the 🐛 Bugs & repairs chip or b. Bugs and fixes round-trip through both the JSON and the HTML export.
skill/architecture-map/SKILL.md runs inside Claude Code on any repo for the deepest analysis (the model actually reads every file). It emits an archmap.json this site can open and a self-contained HTML built from the same viewer runtime as the site — so skill users and site users share one format and one viewer.
Install: copy skill/architecture-map/ to ~/.claude/skills/.
No build step. Serve the directory statically:
python3 -m http.server 4747
# → http://localhost:4747Vanilla ES modules: js/analyze.js (static analysis + evidence), js/query.js (deterministic query engine), js/validate.js (map validation + checked patch engine), js/designer.js (idea → architecture: grill, generate, compose, iterate), js/ingest.js (GitHub/local/website loaders), js/render.js (SVG renderer + interaction runtime + editor, embedded in HTML exports along with query.js and validate.js), js/ai.js (Anthropic calls), js/export.js, js/main.js.
node --test tools/analyze.test.mjs tools/validate.test.mjs tools/query.test.mjs # unit tests
node tools/gen-demo.mjs # regenerate demo/self.archmap.json