Imported from arach/arc (docs/AGENTS.md). Install upstream with npx skills add arach/arc --skill docs. Copyright stays with the author.

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 three npm packages: @arach/arc (full editor), @arach/arc-viewer (lightweight viewer), and @arach/arc-iso (isometric renderer)
• 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 @arach/arc (scripts/mcp/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 palettes (default, warm, cool, mono)
• Export - SVG, PNG, JSON, TypeScript

Links

• GitHub Repository
• NPM: @arach/arc

Quickstart

Installation

npm install @arach/arc
npx @arach/arc-editor

Quick Start

import { ArcDiagram } from '@arach/arc'
import type { ArcDiagramData } from '@arach/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 '@arach/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 }
  nodes: Record<string, NodePosition>
  nodeData: Record<string, NodeData>
  connectors: Connector[]
  connectorStyles: Record<string, ConnectorStyle>
}

Node Types

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

interface NodeData {
  icon: string
  name: string
  subtitle?: string
  description?: string
  color: DiagramColor
}

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

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
}

Themes

Theme API

import { getTheme, getThemeList, THEMES } from '@arach/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)
• PNG: Raster image