Archgraph

AI-managed C4 architecture diagrams for any codebase. An open-source IcePanel alternative.

Live demo: open the viewer and click around at archgraph.vercel.app.

---

Archgraph turns a codebase into a C4 architecture model and draws it in an interactive viewer. You run the /graph skill inside Claude Code, it reads the repo and writes one model.json, and the viewer renders the actors, systems, apps, data stores, and components, plus the connections between them. Auto-layout with ELK, a detail panel for every object, and diagram levels from system context down to containers.

The model is a single plain JSON file (ArchGraphModel, version 1.0.0). Generate it with the skill, write it by hand, or emit it from your own tool. The viewer only needs the file.

Highlights

• Generated from source. The /graph skill runs four research agents in parallel (structure and systems, external services and stores, data flows and connections, actors and user flows) and merges their findings into one model.
• The C4 model, kept simple. Five object types (actor, system, app, store, component), typed connections (sync, async, event, data), groups, technologies, tags, diagrams, and flows.
• Interactive viewer. Pan and zoom on a React Flow canvas, click any node for a detail panel (type, scope, status, groups, technologies, tags, links, docs, and its connections), switch diagram levels from the breadcrumb, and toggle a minimap.
• Automatic layout. ELK layered layout positions nodes and nests groups inside their parents. Saved positions win when a diagram already has them, otherwise the graph lays out from scratch and fits to view.
• Live reload while you edit. In dev the viewer polls model.json every two seconds and repaints when it changes, so a re-run of /graph shows up without a refresh.
• Multi-project. Drop one model per project under public/models/<id>/ and they all list on the home page.

How it works

codebase  --[ /graph skill: 4 parallel agents ]-->  .archgraph/model.json  -->  archgraph viewer

1. Run /graph in Claude Code at the root of any project. It analyzes the repo and writes .archgraph/model.json.
2. Serve it. Run npx archgraph serve /path/to/project to open the viewer against that model, or copy the model into public/ and run pnpm dev.
3. Explore. Switch diagram levels, click nodes to open the detail panel, read the connections.

The viewer is a small React app. Here is the shape of it:

src/
  pages/
    ProjectList.tsx        home page, lists projects from public/projects.json
    ProjectViewer.tsx      canvas shell (top bar, sidebar, canvas, detail panel)
  components/
    Canvas.tsx             React Flow canvas: dot grid, controls, optional minimap
    bars/                  TopBar (breadcrumb + diagram switcher), LeftSidebar, BottomBar
    nodes/                 one renderer per C4 type: actor, system, app, store, component, group
    edges/LabeledEdge.tsx  labeled edges, animated for async and event connections
    panels/                DetailPanel (details + connections tabs), ConnectionsList, TechPill
  lib/
    load-model.ts          fetch and validate a model (version 1.0.0)
    model-to-reactflow.ts  turn a model into React Flow nodes and edges
    layout.ts              ELK layered auto-layout with group nesting
    tech-catalog.ts        known technologies and their brand colors
  hooks/
    useAutoLayout.ts       re-run layout on demand
    useFileWatcher.ts      poll model.json during dev
  store/useGraphStore.ts   Zustand store: model, selection, active diagram
  types/model.ts           the ArchGraphModel contract

Data model

Based on the C4 model:

Type	C4 level	What it is
actor	L1 Context	A person or external entity
system	L1 Context	A high-level system boundary
app	L2 Container	A deployable service or client
store	L2 Container	A data store
component	L3 Component	A module inside an app

Plus connections (sync, async, event, data), groups, technologies, tags, diagrams (levels 1 to 3), and flows. The full contract lives in src/types/model.ts.

Tech stack

• React 19 + TypeScript 5.7
• React Flow 12 (@xyflow/react) for the canvas
• ELK.js 0.9 for auto-layout
• Zustand 5 for state
• Tailwind CSS v4
• React Router 7 for the project routes
• Vite 6, plus a small Node CLI in bin/

Getting started

Prerequisites: Node 20+ and pnpm.

git clone https://github.com/pablomanjarresneg/archgraph.git
cd archgraph
pnpm install

# run the viewer with the bundled sample model (Nella)
pnpm dev
# open http://localhost:4321

Generate from your own codebase

# 1) inside your project, in Claude Code:
/graph                    # analyzes the repo, writes .archgraph/model.json

# 2) serve that model in the viewer:
npx archgraph serve /path/to/your/project
# open http://localhost:4321

The CLI reads <project>/.archgraph/model.json by default. Point it at another file or change the port:

npx archgraph serve . --model .nella/graph/model.json --port 4321

Add a project to the home page

mkdir -p public/models/<project-id>
cp /path/to/model.json public/models/<project-id>/model.json
# then add { "id": "<project-id>", "name": "...", "description": "..." } to public/projects.json

Build

pnpm build      # tsc -b && vite build
pnpm preview    # serve the production build locally

What's inside

Archgraph is one Vite app plus a small CLI. No monorepo, no build steps to learn.

Path	What it is
src/	The React + Vite viewer (pages, canvas, nodes, panels, store, hooks).
src/types/model.ts	The ArchGraphModel contract every model.json follows.
src/lib/layout.ts	ELK layered auto-layout, with group nesting and a grid fallback.
src/lib/model-to-reactflow.ts	Turns a model into typed React Flow nodes and edges.
bin/archgraph.js	The archgraph serve CLI that serves a project's model.json into the viewer.
public/sample-model.json	The bundled Nella sample (12 objects, 11 connections, 3 groups).
public/models/<id>/model.json	One model per project for the multi-project home page.
public/projects.json	The project index the home page reads.
/graph skill	The Claude Code skill that analyzes a repo and writes the model.

License

MIT.

---

Landing  ·  Portfolio write-up  ·  Built by Pablo Manjarres