Skip to content
pmLet’s talk
All projects

Archgraph

AI-generated C4 architecture diagrams from any codebase

Archgraph turns a codebase into an architecture diagram you don't have to draw. Run the /graph skill in Claude Code and it reads the repo: package manifests, external service integrations, data flows, and who-calls-whom. It writes a structured C4 model of the actors, systems, apps, data stores, and the connections between them. A dark-mode web viewer renders that model as an interactive graph with ELK auto-layout, two C4 levels (Context and Container), and a detail panel for every node.

Archgraph: project preview
Role
Product design and engineering
Year
2026
Platform
Software project
Status
live

The problem

Architecture diagrams rot. You draw one in Lucidchart or IcePanel, the code moves on, and six months later the picture is a lie nobody trusts. Archgraph makes the diagram something you regenerate from the actual code with an AI agent, instead of a document you keep patching by hand.

What I built

The work includes archgraph serve, graph, archgraph viewer.

The choices behind it.

Solo · design + engineering

Implementation choice

The /graph Claude Code skill fans out 4 parallel research agents (systems, external services and stores, data flows, actors and user flows) and synthesizes one schema-conforming C4 model JSON, validating that every connection and diagram references a real object ID

Implementation choice

Renders the model on an interactive ReactFlow canvas with ELK layered auto-layout: hierarchical group nesting via INCLUDE_CHILDREN, animated edges for async and event connections, and a selector that switches between C4 Context (L1) and Container (L2) diagrams

Implementation choice

Ships as a web viewer plus an archgraph serve CLI that boots a Vite dev server against any project's .archgraph/model.json, with --model for a custom path (e.g. Nella's .nella/graph/model.json) and --port

Implementation choice

Live-reloads in dev: a 2s poll of the model file diffs its JSON and redraws the graph, so regenerating the model updates the diagram with no manual refresh

Implementation choice

Typed C4 data model (actor, system, app, store, component, plus connections, groups, technologies, and ordered flows) validated on load; the detail panel shows each object's scope, status, tech, links, and both directions of its connections

Implementation choice

Multi-project index: drop a model under public/models/<id>/, register it in projects.json, and it appears on the project picker at its own /<id> route

C4 object types: actor, system, app, store, component
5
parallel research agents per /graph run
4
Build detail
Nella mapped to 20 objects and 35 connections (5 groups, 4 flows)
Build detail
2s model-file poll for live reload in dev

Under the surface.

archgraph serve

cli

The archgraph serve [project] command starts a Vite server that feeds a project's .archgraph/model.json into the viewer and reloads on change, with a --model flag for paths like .nella/graph/model.json.

graph

skill

The /graph Claude Code skill runs four parallel research agents over a codebase (systems, external stores, data flows, actors) and writes the C4 model.json the viewer reads.

archgraph viewer

app

React 19 and ReactFlow 12 single-page app that renders the C4 model as an interactive canvas with actor, system, app, store, and component nodes plus a detail panel and multi-project list.

layout

library

ELK.js layered auto-layout that places nodes and nested group containers left to right, then hands the coordinates back to ReactFlow for rendering.

model

library

The versioned ArchGraphModel schema (objects, connections, groups, technologies, tags, diagrams, flows) that the skill writes and the viewer validates on load.

tech-catalog

library

A registry of about thirty technologies with brand colors and categories that render as tech pills and icons on each node.

Build details Stack, scope, and implementation

Built with

  • React 19
  • TypeScript 5.7
  • ReactFlow 12 (@xyflow/react)
  • ELK.js
  • Zustand 5
  • Tailwind CSS v4
  • Vite 6
  • React Router 7
  • Node CLI

Areas

  • dev tool
  • AI agents
  • C4 model
  • code visualization
  • Claude Code skill
  • architecture-as-code

More about the project

It's an open-source take on IcePanel with one difference: nobody draws the diagram. The model is generated from the code and regenerated whenever the code changes, so the picture stays honest instead of rotting. It ships as a web app and a small archgraph serve CLI, and has already mapped real projects. Running it on Nella produced 20 objects and 35 connections.

Try the product.

Interactive demo · Open full screen