ArchiGraph Viewer

A desktop + web editor for ArchiGraph — a YAML-based format for describing software architecture as a graph of nodes (services, UIs, datastores, APIs) and edges (calls, reads, contains). The viewer renders the graph with Cytoscape, provides forms for editing nodes/edges under a custom schema, and includes an AI chat panel for talking through architectural decisions.

Runs as a native desktop app (Electron, macOS / Windows / Linux) or as a hosted web app (Vite static build, AWS S3 + CloudFront).

Features

• Schema-driven — Your schema.yaml defines layers, node kinds, edge kinds, custom fields, validation rules, and form layouts. The UI adapts to the schema.
• AI chat — Talk to Claude about your architecture; it has full context of the current graph. Bring your own Anthropic API key.
• Claude Code integration — Built-in terminal panel that launches Claude Code against an implementation folder, scoped to the relevant node.
• Multiple layout engines — dagre, cola, fcose, klay, elk, cose-bilkent.
• Dual deploy — Same codebase ships as a desktop app and a web app.

Requirements

• Node.js (see .nvmrc if present, otherwise 20.x+)
• npm
• For the desktop build: platform-specific signing tooling if you want signed artifacts (not required for unsigned local builds).

Quick start (desktop)

npm install
cp settings.example.yaml settings.yaml   # then add your Anthropic API key
npm run dev                              # launches Electron in dev mode

To produce installers:

npm run build:mac      # .dmg + .zip
npm run build:win      # .exe (NSIS)
npm run build:linux    # AppImage

Output lands in release/.

Quick start (web)

npm install
npm run build:web                        # static build to dist/
npx vite preview                         # serve dist/ locally

The web build has no authentication — it's a single-tenant local-only app. If you want to deploy it, see the Deploy section below.

Settings

settings.yaml (gitignored) holds local user settings — primarily the Anthropic API key. See settings.example.yaml for the full schema.

Get an API key at https://console.anthropic.com/settings/keys.

Deploy (web)

deploy.sh provisions an S3 bucket, ACM certificate, CloudFront distribution, and Route 53 records on first run, then syncs the build and invalidates the cache on every run. Configure via env vars (see .env.example):

export DEPLOY_DOMAIN=example.com
export DEPLOY_BUCKET=example.com
export DEPLOY_CLOUDFRONT_ID=    # only needed if you skip first-run provisioning
npm run deploy:web

You'll need AWS credentials configured (aws configure or env vars) with permissions for S3, CloudFront, ACM, and Route 53.

ArchiGraph format

The format is documented in CLAUDE.md. A real-world example describing this app's own architecture is in archigraph.yaml, with the vocabulary defined in schema.yaml.

MCP server (for Claude Code / Claude Desktop)

The repo ships an MCP server at mcp/ that exposes the same read/write/validate/scaffold surface to any MCP-compatible AI client — so Claude Code can edit your architecture in place without opening the viewer. Build with npm run build:mcp, then register the bundled mcp/dist/index.js as an MCP server pointing at your workspace.

Project layout

src/
  pages/            Route-level screens (HomePage, SchemaEditor, AppShell)
  components/       Reusable React components — graph canvas, forms, dialogs
  stores/           Zustand stores (project, workspace, schema)
  lib/              Pure logic — schema, graph, validation
  data/             Default seed documents
electron/           Electron main + preload (IPC, native menus, node-pty)
agents/             Built-in agent workflow definitions

Contributing

See CONTRIBUTING.md. By participating you agree to the Code of Conduct.

License

MIT