Arc

Diagrams as code.

Arc turns typed, diffable config into clean, themeable architecture diagrams. Design in the visual editor, render with React, or export as TypeScript, JSON, SVG, PNG, or crisp ASCII. The diagram lives with the system it describes.

Not a screenshot of a drawing tool — that's the config in Example Output, rendered by <ArcDiagram /> in the Engineering theme.

Install

npm install @arach/arc
# or:  bun add @arach/arc  ·  pnpm add @arach/arc  ·  yarn add @arach/arc

react and react-dom are peer dependencies. Arc bundles its icon renderer and has no production dependencies of its own.

Quick Start

Render any diagram config as a polished, interactive component:

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

export function Architecture() {
  return (
    <ArcDiagram
      data={diagram}      // your ArcDiagramData (see below)
      theme="default"     // seven themes, each with light & dark
      mode="dark"         // light · dark
      defaultZoom="fit"   // auto-fit to the container
    />
  )
}

You get pan/zoom, hover highlighting, light/dark modes, and seven color themes out of the box.

Key props

| Prop | Type | Notes | |------|------|-------| | data | ArcDiagramData | The diagram config (required) — see Example Output. | | theme | 'default' \| 'warm' \| 'cool' \| 'mono' \| 'engineering' \| 'workbench' \| 'tactical' | Palette + drafting grammar (grid, frame, type). | | mode | 'light' \| 'dark' | Appearance. | | frame | 'hairline' \| 'inset' \| 'brackets' \| 'ticks' \| 'cropmarks' \| 'corners' \| 'sheet' \| 'none' | Override the theme's edge treatment. | | interactive | boolean | Pan/zoom controls. | | defaultZoom | number \| 'fit' | Initial zoom, or 'fit' to auto-fit (maxFitZoom caps it). | | showControls / showMinimap | boolean | Zoom controls / minimap for read-only chrome. | | hoverEffects | boolean \| { dim, lift, glow, highlightEdges } | Hover highlighting (granular). | | label | string | Override the bottom-left label. |

The Studio

Prefer to design visually? Arc ships a full drag-and-drop studio — infinite canvas, floating toolbar, reusable connector styles, live properties panel, and a minimap. Clone the repo and open it:

git clone https://github.com/arach/arc && cd arc
bun install && bun dev      # → http://localhost:5188/editor

Design on the canvas, then Export to TypeScript, JSON, SVG, PNG, or a shareable link — and drop the result straight into <ArcDiagram />.

Features

• Visual Editor - Drag-and-drop nodes, connect with arrows
• Multiple Node Sizes - Large, medium, small
• Color Themes - Violet, emerald, blue, amber, sky, zinc, rose, orange
• Connector Styles - Solid/dashed lines, labels, curved paths
• Export Options - TypeScript, JSON, SVG, PNG, ASCII, shareable links
• Interactive Canvas - Infinite pan/zoom, grid snapping
• Groups & Images - Visual grouping, background images
• Templates - Quick-start layouts

Native Mermaid Sequences

@arach/arc-viewer turns canonical Mermaid sequenceDiagram source into a typed Arc document and a native, interactive React player—without embedding the generic Mermaid runtime.

npm install @arach/arc-viewer

import { ArcMermaidPlayer } from '@arach/arc-viewer'

const source = `sequenceDiagram
  participant App
  participant API
  App->>API: Load architecture
  API-->>App: Typed diagram`

export function Sequence() {
  return <ArcMermaidPlayer source={source} mode="light" />
}

Existing Mermaid flowcharts and state diagrams can also be projected into ArcDiagramData:

import { importMermaid } from '@arach/arc-viewer'

const { diagram, warnings, unsupported } = importMermaid(source)

This compatibility adapter is intentionally lossy. Use the native Mermaid APIs above when sequence semantics must remain intact. See Mermaid architecture projection for the supported grammar and diagnostic contract.

Themes

One diagram, several drafting grammars. The nodes and palette stay the same — what changes is the grid system, edge treatment, type, and geometry. Here's Arc's own architecture rendered three ways:

Plus default, warm, cool, and mono — seven in all, each with light and dark modes.

Example Output

Arc stores diagrams as plain, typed data — the same config that renders the diagram at the top of this README:

const diagram: ArcDiagramData = {
  layout: { width: 850, height: 340 },
  nodes: {
    client:  { x: 40,  y: 130, size: 'm' },
    gateway: { x: 220, y: 130, size: 'l' },
    auth:    { x: 460, y: 40,  size: 'm' },
    api:     { x: 460, y: 140, size: 'm' },
    cache:   { x: 460, y: 240, size: 's' },
    db:      { x: 680, y: 140, size: 'm' },
  },
  nodeData: {
    client:  { icon: 'Monitor',  name: 'Client',      subtitle: 'React App', color: 'violet' },
    gateway: { icon: 'Server',   name: 'API Gateway', subtitle: 'Express', description: 'Load balanced', color: 'emerald' },
    auth:    { icon: 'Shield',   name: 'Auth',        subtitle: 'JWT', color: 'amber' },
    api:     { icon: 'Code',     name: 'API',         subtitle: 'REST', color: 'blue' },
    cache:   { icon: 'Zap',      name: 'Cache',       color: 'sky' },
    db:      { icon: 'Database', name: 'PostgreSQL',  subtitle: 'Primary', color: 'blue' },
  },
  connectors: [
    { from: 'client',  to: 'gateway', fromAnchor: 'right',       toAnchor: 'left', style: 'https' },
    { from: 'gateway', to: 'auth',    fromAnchor: 'right',       toAnchor: 'left', style: 'internal' },
    { from: 'gateway', to: 'api',     fromAnchor: 'right',       toAnchor: 'left', style: 'internal' },
    { from: 'gateway', to: 'cache',   fromAnchor: 'bottomRight', toAnchor: 'left', style: 'cache' },
    { from: 'api',     to: 'db',      fromAnchor: 'right',       toAnchor: 'left', style: 'sql' },
  ],
  connectorStyles: {
    https:    { color: 'violet',  strokeWidth: 2, label: 'HTTPS' },
    internal: { color: 'emerald', strokeWidth: 2 },
    cache:    { color: 'sky',     strokeWidth: 1, dashed: true },
    sql:      { color: 'blue',    strokeWidth: 2, label: 'SQL' },
  },
}

ASCII Renderer

The same diagram renders as precise monospace text — for READMEs, CLI output, or anywhere you can't embed a React component:

                                                     ┌──────────────────┐
                                                     │ ◆ Auth           │
                                                   ┌▶│ JWT              │
                                                   │ └──────────────────┘
                                                   │
┌──────────────────┐   ╔═════════════════════════╗ │
│ ◆ Client         │   ║ ◆ API Gateway           ║ │ ┌──────────────────┐       ┌──────────────────┐
│ React App        │─┐ ║ Express                 ║ │ │ ◆ API            │ SQL   │ ◆ PostgreSQL     │
│                  │ └▶║ Load balanced           ║─┴▶│ REST             │──────▶│ Primary          │
└──────────────────┘   ║                         ║╌┐ └──────────────────┘       └──────────────────┘
                       ╚═════════════════════════╝ ╎
                                                   ╎
                                                   ╎ ┌───────────┐
                                                   └▶│ ◆ Cache   │
                                                     └───────────┘

Programmatic

import { renderAscii } from '@arach/arc'

const ascii = renderAscii(diagram)                          // Unicode box-drawing
const plain = renderAscii(diagram, { charset: 'ascii' })    // +-- style
const narrow = renderAscii(diagram, { maxWidth: 80 })       // Auto-scale to 80 cols

CLI

bunx tsx bin/arc-ascii.mjs diagram.json
cat diagram.json | bunx tsx bin/arc-ascii.mjs
bunx tsx bin/arc-ascii.mjs diagram.json --charset ascii --max-width 80

Requirements

The ArcDiagram player component requires:

• Tailwind CSS v3+ - Component uses Tailwind utility classes for styling
• Default color palette - The following colors must be available: violet, emerald, blue, amber, sky, zinc, rose, orange

If you're using a custom Tailwind config that restricts the color palette, ensure these colors are included.

Tech Stack

• React 19
• Vite 7
• TailwindCSS 4
• Lucide React (icons)

License

MIT