arc

Diagrams as Code - Visual editor for architecture diagrams that live in your codebase

Critical Context

IMPORTANT: Read these rules before making any changes:

• Arc exports four npm packages: @hudsonkit/arc (full editor), @hudsonkit/arc-viewer (lightweight viewer), @hudsonkit/arc-iso (isometric renderer), and @hudsonkit/arc-mcp (MCP server)
• Diagrams are stored as declarative JSON/TypeScript configs, not binary files
• The editor uses useReducer + Context for state management (EditorProvider)
• Never modify diagram configs without understanding the schema in src/types/
• Exports should be deterministic - same input = same output for diffability

Project Structure

Quick Navigation

• Entry point: src/main.tsx
• Routes: src/App.tsx
• Editor shell: src/apps/arc-editor/createArcApp.tsx
• Canvas + reducer: src/components/editor/
• Diagram schema: src/types/diagram.ts
• Example diagrams: src/components/diagrams/*.diagram.ts
• Contributor guide: CLAUDE.md (repo root)

MCP Support

Shipped as the arc-mcp bin on @hudsonkit/arc-mcp (packages/mcp/src/server.ts). See docs/agent/mcp.agent.md.

Package Decision Tree

Details: docs/agent/packages.agent.md

Overview

Arc is a React component library for rendering beautiful, interactive architecture diagrams. It provides a declarative JSON format for defining diagrams and multiple built-in themes.

Why Arc?

Architecture diagrams typically live in design tools, disconnected from the code they describe. Arc keeps diagrams as declarative configs that:

• Version with your code - Diffs show exactly what changed
• Render anywhere - Use the lightweight player or export to SVG/PNG
• Stay consistent - Templates enforce color palettes and sizing rules

Packages

Key Features

• Declarative Format - Diagrams are data structures
• Templates - Structural presets for layout
• Themes - Color and decor palettes (default, warm, cool, mono, engineering, workbench, tactical, command, spacex, claude, codex)
• Export - SVG, PNG, JSON, TypeScript

Links

• GitHub Repository
• NPM: @hudsonkit/arc
• NPM: @hudsonkit/arc-mcp

Quickstart

Installation

npm install @hudsonkit/arc

Quick Start

import { ArcDiagram } from '@hudsonkit/arc'
import type { ArcDiagramData } from '@hudsonkit/arc'

const diagram: ArcDiagramData = {
  layout: { width: 600, height: 300 },
  nodes: {
    frontend: { x: 50, y: 100, size: 'm' },
    backend: { x: 250, y: 100, size: 'm' },
    database: { x: 450, y: 100, size: 'm' },
  },
  nodeData: {
    frontend: { icon: 'Monitor', name: 'Frontend', color: 'violet' },
    backend: { icon: 'Server', name: 'Backend', color: 'emerald' },
    database: { icon: 'Database', name: 'Database', color: 'blue' },
  },
  connectors: [
    { from: 'frontend', to: 'backend', fromAnchor: 'right', toAnchor: 'left', style: 'api' },
    { from: 'backend', to: 'database', fromAnchor: 'right', toAnchor: 'left', style: 'db' },
  ],
  connectorStyles: {
    api: { color: 'violet', strokeWidth: 2, label: 'REST' },
    db: { color: 'blue', strokeWidth: 2, label: 'SQL' },
  },
}

function App() {
  return <ArcDiagram data={diagram} mode="light" theme="default" />
}

Vanilla JavaScript

<script type="module">
  import { renderDiagram } from '@hudsonkit/arc-iso'
  renderDiagram(document.getElementById('diagram'), diagramConfig)
</script>

Development

bun run dev      # Start dev server (http://localhost:5188/editor)
bun run build    # Production build
bun run lint     # Run ESLint
bun run typecheck

Architecture

Major Modules

State Model

{
  diagram: { layout, nodes, nodeData, connectors, connectorStyles },
  editor: { selectedNodeIds, selectedConnectorIndex, mode, pendingConnector, isDragging, viewMode, themeId, colorMode },
  meta: { filename, isDirty, lastSaved },
  history: { past, future }
}

Data Flow

1. User Action → Dispatch action to reducer
2. Reducer → Updates state immutably, pushes to history
3. Context → Propagates new state to components
4. Canvas → Re-renders affected nodes/connectors

Diagram Config

{
  "layout": { "width": 700, "height": 340 },
  "nodes": { "nodeId": { "x": 25, "y": 15, "size": "m" } },
  "nodeData": { "nodeId": { "icon": "Monitor", "name": "...", "color": "violet" } },
  "connectors": [{ "from": "a", "to": "b", "fromAnchor": "right", "toAnchor": "left", "style": "http" }],
  "connectorStyles": { "http": { "color": "amber", "strokeWidth": 2, "label": "HTTP" } }
}

API Reference

ArcDiagram Component

interface ArcDiagramProps {
  data: ArcDiagramData     // Diagram configuration
  mode?: 'light' | 'dark'  // Color mode (default: 'light')
  theme?: ThemeId          // Theme preset (default: 'default')
  interactive?: boolean    // Enable zoom/pan (default: true)
  className?: string       // Additional CSS classes
}

ArcDiagramData Schema

interface ArcDiagramData {
  id?: string
  layout: { width: number; height: number }
  legend?: 'auto' | 'all' | 'hidden'  // authored legend policy
  _meta?: FileMeta                    // viewer/editor state; `locale` is BCP-47
  nodes: Record<string, NodePosition>
  nodeData: Record<string, NodeData>
  connectors: Connector[]
  connectorStyles: Record<string, ConnectorStyle>
  focusTargets?: Record<string, FocusTarget>
  flows?: DiagramFlow[]              // animated message routes — docs/api.md
  views?: DiagramView[]              // ordered guided chapters — docs/views.md
}

Node Types

interface NodePosition {
  x: number
  y: number
  size: 'xs' | 's' | 'm' | 'l'
}

interface NodeData {
  icon?: string          // Lucide name; omit when `kind` supplies it
  name: string
  subtitle?: string
  description?: string
  color?: DiagramColor   // omit when `kind` supplies it; overrides the kind default
  kind?: NodeKind        // semantic role — supplies default icon + color
  shape?: NodeShape      // per-node silhouette override
  source?: DiagramSource // { path, line?, endLine?, commit? } — code evidence link
}

type DiagramColor = 'violet' | 'emerald' | 'blue' | 'amber' | 'sky' | 'zinc' | 'rose' | 'orange'

// Semantic roles — `src/utils/nodeKinds.ts` maps each to a default palette
// color + Lucide icon, resolved at render time.
type NodeKind = 'frontend' | 'backend' | 'service' | 'database' | 'cache' | 'queue' |
                'storage' | 'gateway' | 'security' | 'user' | 'external' | 'observability'

Connector Types

interface Connector {
  from: string
  to: string
  fromAnchor: AnchorPosition
  toAnchor: AnchorPosition
  style: string
  curve?: 'natural' | 'step'
}

type AnchorPosition = 'left' | 'right' | 'top' | 'bottom' |
                      'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight'

interface ConnectorStyle {
  color: DiagramColor
  strokeWidth: number
  label?: string
  labelAlign?: 'left' | 'right' | 'center'
  dashed?: boolean
}

interface DiagramFlow {
  id: string
  legs: Array<{ id?: string; from?: string; to?: string; direction?: 'forward' | 'reverse'; pause?: number }>
  direction?: 'forward' | 'reverse'
  speed?: number                    // px/s; ignored when duration is set
  duration?: number                 // total seconds including pauses
  delay?: number; hold?: number
  repeat?: number | 'indefinite'
  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out'
  marker?: 'dot' | 'packet' | 'pulse' | 'arrow'
  color?: DiagramColor
  size?: number
  trail?: 'none' | 'fade' | 'wake'
}

Themes

Theme API

import { getTheme, getThemeList, THEMES } from '@hudsonkit/arc'

const theme = getTheme('warm')
const themes = getThemeList()
const palette = theme.light.palette.violet

Available Icons

Arc uses Lucide React icons:

• Infrastructure: Server, Database, Cloud, CloudCog, HardDrive, Network, Cpu
• Interfaces: Monitor, Smartphone, Laptop, Globe, Terminal
• Services: MessageSquare, Mail, Bell, Shield, Lock, Key
• Data: FileText, Folder, Package, Archive, Layers
• Connectivity: Wifi, Radio, Plug, Cable, Router
• Actions: RefreshCw, Download, Upload, Send, Zap

Export Formats

• JSON: Full diagram configuration
• TypeScript: Type-safe diagram constant
• SVG: Vector graphic (light or dark; flows animate via SMIL)
• PNG: Raster image sampled at flowTime
• GIF/MP4: Animated flow artifacts via Chrome frames + ffmpeg