archmap

Turn a small JSON file into an interactive architecture map you can host anywhere.

Describe your system once — entry points, cron jobs, AI agents, models, tools, services, datastores, and third-party APIs — and archmap generates a static, pannable diagram with no runtime dependencies, no account, and no expiry.

▶ Live demo · built from scans/example-helpdesk.json

Why

Architecture screenshots go stale, whiteboard photos die in Slack, and prose buries the structure. Hosted diagram services solve that but put your system map behind someone else's account, quota, and expiry clock.

archmap is the boring alternative: your architecture is a JSON file in your repo, the output is plain HTML that works offline, and the whole thing deploys to GitHub Pages for free.

• No runtime network calls. Brand favicons are fetched once at build time and cached into the repo, so a map renders identically offline, in CI, and in a screenshot.
• Readable at 40+ nodes. Model and tool nodes get absorbed as rows inside the agent that calls them, instead of exploding into a hairball.
• Groups are real structure. Tag nodes with a group and they lay out as one labelled column.
• Static output. One index.html per map plus a gallery index. Host it anywhere that serves files.

Quick start

git clone https://github.com/Fred-In-tech/archmap.git
cd archmap
npm install
node build.mjs

That builds every scans/*.json into <slug>/index.html and writes a gallery index.html. Open one in a browser — no server required.

To add your own system, drop a new file in scans/ and rebuild.

The scan format

A minimal map:

{
  "project": { "name": "My System", "tagline": "One line", "date": "2026-09-01" },
  "topModels": [], "topTools": [], "topIntegrations": [],
  "graph": {
    "nodes": [
      { "id": "api", "label": "API", "kind": "entry", "sub": "/api/*" },
      { "id": "worker", "label": "Ingest worker", "kind": "service", "group": "Ingestion" },
      { "id": "db", "label": "Postgres", "kind": "store", "domain": "postgresql.org" }
    ],
    "edges": [
      { "from": "api", "to": "worker", "kind": "triggers" },
      { "from": "worker", "to": "db", "kind": "writes", "label": "upserts chunks" }
    ]
  }
}

Nodes

Field	Notes
id	Unique; edges reference it
label	Shown on the card
kind	entry · cron · agent · model · tool · service · store · external
sub	Small second line — the route, schedule, or runtime
domain	Favicon domain (stripe.com); omit for internal components
group	Nodes sharing a group render as one labelled column
detail	One sentence, revealed when the node is clicked
sourceRef	Repo path (src/agents/support.ts:42) so teammates can jump to the code

Edges

from and to are node ids. kind is calls · reads · writes · triggers. Add a label when a specific phrase says more than the arrow does — "charges on trial end" beats a bare line.

The panels

topModels, topTools, and topIntegrations populate the sidebar. Each entry is { id, label, domain }.

Deploy to GitHub Pages

Push the built output and turn Pages on for the repository root:

gh api -X POST repos/OWNER/REPO/pages -f "source[branch]=main" -f "source[path]=/"

Maps are then served at https://OWNER.github.io/REPO/<slug>/.

Generating a scan with an AI coding agent

Point Claude Code, Codex, Cursor, or any coding agent at your repository and ask it to produce the JSON above — investigating where AI runs (model calls, tool definitions, agent loops), the internal services, the datastores, and the entry points. Because the format is small and declarative, an agent can build an accurate map of a codebase it has just read, and you commit the result.

Keep the map to architecture only: components, connections, and data flow. No credentials, hostnames, or customer data belong in a scan.

How it works

scans/*.json  →  build.mjs  →  <slug>/index.html + assets/icons/*.png

build.mjs resolves each favicon domain once, vendors the layout engine, and writes a self-contained page per scan. assets/render.js lays the graph out left-to-right with dagre, draws nodes as HTML cards and edges as orthogonal SVG paths, and adds pan, zoom, fit, and click-to-trace.

Roughly 700 lines total, no framework, no build step beyond Node.

Requirements

Node 18+. That's it.

License

MIT — see LICENSE.

---

Built by Godfred Aidoo. If you use it for something interesting, I'd like to hear about it.