From zero to a working diagram in five minutes.

Install Archy

Open VS Code and install the extension:

1. Press Cmd+Shift+X (Mac) or Ctrl+Shift+X (Windows/Linux)
2. Search for Archy
3. Click Install

Or from the terminal:

code --install-extension nischalon10.archy

Create your first file

Create a new file anywhere in your workspace and name it with a .archy extension — for example, architecture.archy.

Paste this to start:

{
  "version": "2",
  "name": "My First Diagram",
  "nodes": [
    { "id": "frontend", "type": "frontend", "name": "Web App" },
    { "id": "api",      "type": "service",  "name": "API Service" },
    { "id": "db",       "type": "database", "name": "Database" }
  ],
  "edges": [
    { "id": "e1", "from": "frontend", "to": "api", "type": "calls",  "label": "HTTPS" },
    { "id": "e2", "from": "api",      "to": "db",  "type": "writes", "label": "SQL" }
  ]
}

Save the file. Archy opens it as a diagram automatically.

Explore the canvas

Navigate the canvas:

• Scroll or trackpad pinch to zoom
• Click and drag the background to pan
• Drag any node to reposition it

Toolbar buttons (top-left):

• Fit — fit the diagram to the window
• Lock — prevent nodes from being dragged
• Edit / View — switch between edit and view mode

Click a node or edge — the Detail Panel opens on the right, showing the element's type, description, metadata, and notes.

Activity Bar (Archy icon on the left):

• Minimap — thumbnail of the whole diagram; click to navigate
• Elements — list of all nodes and edges; click any to focus it on the canvas
• Settings — toggle display options and switch modes

Add more nodes and edges

Add a message queue to the diagram. Edit the JSON directly:

{
  "version": "2",
  "name": "My First Diagram",
  "nodes": [
    { "id": "frontend",   "type": "frontend",  "name": "Web App" },
    { "id": "api",        "type": "service",   "name": "API Service" },
    { "id": "task-queue", "type": "queue",     "name": "Task Queue" },
    { "id": "worker",     "type": "batch-job", "name": "Background Worker" },
    { "id": "db",         "type": "database",  "name": "Database" }
  ],
  "edges": [
    { "id": "e1", "from": "frontend", "to": "api",        "type": "calls",     "label": "HTTPS" },
    { "id": "e2", "from": "api",      "to": "task-queue", "type": "publishes", "label": "AMQP" },
    { "id": "e3", "from": "worker",   "to": "task-queue", "type": "consumes" },
    { "id": "e4", "from": "worker",   "to": "db",         "type": "writes",    "label": "SQL" }
  ]
}

Save. The diagram updates instantly.

Add descriptions and metadata

Enrich nodes with context. This appears in the detail panel when you click a node:

{
  "id": "api",
  "type": "service",
  "name": "API Service",
  "description": "Handles authentication and request routing.",
  "_meta": {
    "technology": "Node.js / Express",
    "team": "platform-team",
    "port": 3000
  },
  "notes": "Rate limited at 1000 req/min per client. See runbook for override procedure."
}

• description — shown in the node card on the canvas
• _meta — key-value table in the detail panel (infrastructure detail, not rendered on canvas)
• notes — markdown, shown in the Notes section of the detail panel; click "Edit in editor" to open a full VS Code markdown editor

Group related nodes

Use groups to draw team or network boundaries:

{
  "version": "2",
  "nodes": [ ... ],
  "edges": [ ... ],
  "groups": [
    {
      "id": "internal",
      "label": "Internal VPC",
      "type": "zone",
      "nodes": ["api", "task-queue", "worker", "db"]
    }
  ]
}

Groups render as shaded regions on the canvas. "type": "zone" gives a dashed indigo border (network boundary). "type": "logical" gives a solid teal border (domain or team boundary).