Archy

Architecture diagrams that live in your editor.

Archy is a VS Code extension that renders interactive architecture diagrams from a simple JSON file. Open any .archy file and see your system visualized instantly — no accounts, no cloud sync, no separate diagramming tool.

What it does

You write a .archy file. Archy renders a live, interactive diagram inside VS Code.

{
  "version": "2",
  "nodes": [
    { "id": "orders-api",           "type": "service",     "name": "Orders API" },
    { "id": "order-created",        "type": "kafka-topic", "name": "order-created" },
    { "id": "inventory-service",    "type": "service",     "name": "Inventory Service" },
    { "id": "notification-service", "type": "service",     "name": "Notification Service" },
    { "id": "orders-db",            "type": "database",    "name": "Orders DB" }
  ],
  "edges": [
    { "id": "e1", "from": "orders-api",         "to": "order-created",        "type": "publishes", "label": "AMQP" },
    { "id": "e2", "from": "inventory-service",  "to": "order-created",        "type": "consumes" },
    { "id": "e3", "from": "notification-service","to": "order-created",       "type": "consumes" },
    { "id": "e4", "from": "orders-api",         "to": "orders-db",            "type": "writes",    "label": "PostgreSQL" }
  ]
}

Every edge has a semantic type — calls, publishes, consumes, writes, reads, streams, triggers — so the diagram tells a story, not just a topology.

Features

Interactive canvas

• Pan, zoom, and drag nodes to arrange your diagram
• Click any node or edge to open a detail panel with metadata and notes
• Fit view, lock canvas, and copy controls built in

Activity Bar sidebar

• Minimap — live viewport of the full diagram, click to navigate
• Elements — searchable list of all nodes and edges, click to focus
• Settings — toggle data flow animation, edge labels, compact mode, and switch between view/edit mode

Detail panel

• Three sections: Basics (type, id, name, description), Metadata (key-value pairs, editable), Notes (markdown, opens in VS Code editor)
• In Edit mode, all fields are inline-editable — changes write directly back to the .archy file

Canvas display options

• Data flow animation — edges animate to show data direction
• Always show edge labels — type chips visible on all edges
• Compact nodes — hide description text on node cards

Group boundaries

• Define logical or zone groups in your .archy file; they render as shaded boundaries on the canvas
• Groups reflow automatically when you drag nodes

Getting started

1. Install Archy from the VS Code Marketplace
2. Create a file named architecture.archy anywhere in your workspace
3. Open it — Archy opens automatically as the editor for .archy files
4. Start with this template:

{
  "version": "2",
  "name": "My Architecture",
  "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" }
  ]
}

Node types

Edge types

The reads and consumes edge types use a reversed arrowhead to show that data flows toward the consumer — from the data source, not from the service.

The .archy format

Every node needs an id and a type. Everything else is optional.

{
  "id": "payment-service",
  "type": "service",
  "name": "Payment Service",
  "description": "Processes payments via Stripe.",
  "_meta": {
    "technology": "Python / FastAPI",
    "team": "payments-team",
    "compliance": "PCI-DSS Level 1"
  },
  "notes": "Card data never stored — tokenised via Stripe."
}

_meta is a free-form object for infrastructure details (team, technology, compliance) that shouldn't clutter the diagram structure. It appears in the detail panel but doesn't affect rendering.

notes accepts markdown and opens in a full VS Code editor panel when you click the edit button in the detail panel.

Edit mode vs View mode

Switch between modes in the Archy Settings sidebar panel (Activity Bar → Archy icon → Settings).

• View mode — Read-only canvas. Click nodes and edges to inspect them. Default for opening files.
• Edit mode — Drag nodes, edit names, descriptions, and metadata inline in the detail panel. Changes auto-save to the .archy file.

Requirements

• VS Code 1.85 or later
• No other dependencies

Contributing

See CONTRIBUTING or the project documentation site.

License

MIT