Create and view Archify diagrams inside VS Code. You write a diagram as a .archify file in YAML; clicking it opens the interactive diagram, and the diagram follows your edits as you type.

This is an unofficial extension. It bundles the Archify renderer (MIT, © tt-a1i) and runs it on VS Code's own Node runtime, so nothing else needs to be installed.

Free and open source. If it saves you time, you can buy me a coffee ☕

Supported files

File	Format	What the extension does
`name.archify`	YAML (the main format)	Opens as the interactive diagram. Show Source, live updates, validation, completion, templates.
`name.architecture.json`, `name.workflow.json`, `name.sequence.json`, `name.dataflow.json`, `name.lifecycle.json`	JSON (Archify's own CLI format)	Opens as text, with a preview beside it and validation. For files produced by the Archify CLI or AI agents.
Rendered Archify `.html`	HTML	Read-only viewer instead of a browser.

New diagrams should be .archify files; everything below describes them unless it says otherwise.

Quick start

The fastest start: right-click a folder in the Explorer and choose Archify | New Diagram… (also in File → New File… and the Command Palette). Pick a kind of diagram (Architecture, Workflow, Sequence, Data Flow, Lifecycle or Everyday Plan), give it a name, and a small working .archify file is created and opened. Change its YAML to fit your case.

For a whole set of diagrams, choose Archify | New Model… instead and pick one of the examples (C4 - Standard Web App, C4 - E-Shop, C4 - Event-Based Integration). A model folder with context, container and component diagrams and a shared registry is created and its model page opens. See Models.

To write one by hand:

Create a file ending in .archify, for example hello.archify:

schema_version: 1
diagram_type: architecture
meta:
  title: Hello Archify
  output: hello.html
components:
  - { id: browser, type: frontend, label: Browser, pos: [40, 120], size: [140, 60] }
  - { id: api, type: backend, label: API, pos: [260, 120], size: [140, 60] }
  - { id: db, type: database, label: PostgreSQL, pos: [480, 120], size: [140, 60] }
connections:
  - { from: browser, to: api, label: HTTPS }
  - { from: api, to: db, label: SQL }

Click it in the Explorer: the diagram opens.
To edit, use Show Source in the editor title. The YAML opens beside the diagram, which re-renders as you type.

The same file is in examples/hello.archify.

The `.archify` format

A .archify file is an Archify diagram written in YAML. Its fields are those of Archify's diagram schema; the extension converts the YAML for the renderer, so you never handle JSON yourself. diagram_type selects the kind of diagram: architecture, workflow, sequence, dataflow or lifecycle.

Opening: the Archify Diagram editor is the default for .archify. Use Reopen Editor With… → Text Editor to edit the YAML full-screen.
Completion: with the YAML extension (redhat.vscode-yaml) installed, .archify files get completion and hover from Archify's schemas. The schema follows diagram_type.

.archify files from extension version 0.2.0 were written in JSON. They still open, because JSON is valid YAML, but new files should use YAML.

Archify's JSON files

The Archify CLI and the AI agents that use it write diagrams as JSON, named name.architecture.json, name.workflow.json and so on. The extension supports these too: they open as text with a preview button in the editor title (Cmd/Ctrl+K V to the side, Cmd/Ctrl+Shift+V in place), get validation in Problems, and get schema completion from VS Code's built-in JSON support. Any other .json file that declares an Archify diagram_type previews the same way.

Features

New diagram from a template: Archify | New Diagram… creates a starter .archify file for any of the five diagram kinds, or an everyday plan, in the chosen folder.
New model from an example: Archify | New Model… creates a complete model folder from a C4 example (Standard Web App, E-Shop, Event-Based Integration).
Model graph: the Graph switch on any page of a model shows the whole model as one graph, with a query box (type:database, uses:api, from:web to:db, …), a side panel per element and PNG export. See Models.
Diagram editor: .archify files open as the rendered diagram. Show Source opens the YAML beside it, and edits re-render live.
Live updates: the diagram re-renders as you edit, and keeps the focus and route you selected (#focus=…, #route=…).
HTML viewer: right-click a rendered .html file and choose Archify | Open in HTML Viewer, or use Reopen Editor With… → Archify HTML Viewer. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk.
Problems: YAML syntax errors, plus archify validate's schema, layout and evidence problems, appear at the matching line of the .archify file.
Brand logos: after brand: the editor suggests Archify's built-in brand IDs (PostgreSQL, Redis, Kafka, Docker, …). Typing an alias or product name finds them too, so kafka offers apache-kafka. An unknown brand is reported on its own line.
Schema help: completion and hover from Archify's own schemas, through the YAML extension for .archify files.
Source links: in source-backed diagrams, clicking a source reference opens that file and line range in the editor. If the file is not in the workspace, the web link opens instead.
Export: the diagram's own Export menu (PNG, SVG, share card, …) saves through a VS Code save dialog.
Commands: Archify | New Model…, Archify | New Registry…, Archify | New Diagram…, Archify | New Decision…, Archify | Open Model, Archify | Open Model Graph, Archify | Render to HTML File…, Archify | Open in Browser, Archify | Refresh Preview, Archify | Show Source.

3D view

Every diagram can also be seen in 3D. The 2D | 3D switch next to Export in the diagram's toolbar shows which view you are in; click it to flip.

The 3D view is built from the diagram Archify draws, so it looks the same: each node becomes a raised block whose top is the node as Archify draws it, relationships become pipes along Archify's routes with their colours, dashes and arrowheads, and the canvas, frames, lanes and legend form the floor. It works for all five diagram kinds, in every theme and style (Classic, Signal Flow, Blueprint, Editorial).

While 3D is on, three controls join the bottom-right dock next to PATH and LENS:

STACK lifts nodes into levels by kind: clients and external systems on top, security below them, services in the middle, data on the floor. Click again for the flat layout.
TOP looks straight down, like 2D.
RESET (the middle of the zoom stepper, or 0) flies back to the whole diagram, wherever you have moved to.

Moving around:

Drag to turn, right-drag to move. On a trackpad, scroll with two fingers to move in any direction and pinch to zoom; a mouse wheel zooms. The dock's − and + and the - and + keys work too, beyond the 2D limits.
Click a block to focus it, as in 2D: the Semantic Passport opens and unrelated parts fade. Hover a block to see its one-hop trace. Double-click a block to fly to it, or empty space to show everything.

Animation follows 2D exactly, because the 3D view reads Archify's own animations as they play: the trace (relationships drawing in, nodes pulsing) when the diagram opens or 3D is chosen, the hover trace, and the flows from the Semantic Passport, Path and Lens. Live off, or reduced motion, keeps it still.

Export → 3D view saves the current 3D view as a PNG. Each open diagram remembers whether it was in 3D, its camera and its levels; set archify.defaultView to 3d to open diagrams in 3D.

The 3D view draws only when something moves, so an idle diagram costs no GPU time.

Models

A single .archify file is one diagram. A folder with a main.archify at its top is a model: a set of diagrams that belong together, of any kind, with shared elements defined once. Diagrams inside a model still open, render and export on their own.

online-shop/
  main.archify                     id, name, description; optionally an overview diagram
  registry/
    people.archify-registry        shared elements: one name for one thing
    systems.archify-registry
    containers.archify-registry
  decisions/
    0002-queue-between-api-and-worker.archify-decision
  0100-context/online-shop.archify
  0200-containers/online-shop.archify
  0300-components/api.archify

The model page. Click main.archify and you get the model's page: its name and description, the overview diagram if the file has one, then two collapsible panels: Diagrams, with a collapsible header per folder and a card per diagram (click to open), and Registries, one collapsible header per registry file (with an Open button for its view) and the file's elements as cards inside, each with the diagrams it is used in. Open or closed is remembered per page.
Shared elements. A registry file defines an element once (type, label, sublabel, brand, description, …). A diagram draws it with ref: api plus pos and size; it may override label, sublabel and tag, and may still define unshared elements inline. Hover a ref for the description, F12 jumps to the registry, completion after ref: lists the elements, unknown names appear in Problems.
Links. A registry element (or a component) with diagram: 0300-components/api.archify points at the diagram that explains it: double-click the node in the 2D view to open it.
Descriptions. Under a model diagram, hovering a row of the Elements panel shows the registry description of that element.
Decisions. One *.archify-decision file per architecture decision: id, title, status, date, the registry elements and diagrams it is about, and prose for context, decision and consequences. Diagrams point at decisions with decisions: [<id>] on the diagram, a component or a connection. They show as a Decisions panel on the main.archify page, a Decisions rail panel under each diagram (hover lights up what the decision is attached to), on element cards and in the element dialog, and a decision opens as its own page. Archify | New Decision… creates one; links are checked in Problems.
Registry view. A .archify-registry file opens as its elements, as cards. Click one and a dialog shows its description, where it is defined and the diagrams that use it; click a diagram to open it. Show Source opens the YAML beside it.
Elements and Connectors. Under every diagram, Archify's node index is titled Elements, and a Connectors panel next to it lists every connection as "from → to" with its label. Hovering highlights the connector in the diagram; clicking keeps it highlighted and scrolls to it.
Starting one. Archify | New Model… (right-click a folder) copies one of the shipped examples into a new folder, named as you choose: C4 - Standard Web App (single-page app, API, database, cache, storage, identity provider), C4 - E-Shop (web shop, API, worker, queue, payment and email providers) or C4 - Event-Based Integration (event bus, router, dead-letter queue, event store, consumers). Each has a registry and context, container and component diagrams. For an empty model, Archify | New Diagram… → Model creates just a main.archify.
The graph. The Model | Graph switch at the top of the main.archify page (next to Export when the file has a diagram) replaces the page with the whole model as one graph: every element any diagram draws plus every registry element, every connection between them, each once. Registry elements have a solid border, inline ones a dashed border; colours are Archify's type colours and the legend chips at the bottom hide or show a type. Decisions are nodes too (tags coloured by status, dotted links to the elements they are about, dashed links to what they supersede), and so are registries (one node per file, dotted links to the elements it defines); their chips hide them when the picture gets busy. The layout is Layered by default, like Archify's stack: clients on the left, data on the right, registries in a row above, decisions in a row below, connections drawn orthogonally; click the button for a Force layout instead. Drag nodes, scroll to zoom, Fit (or 0) frames what matches, Labels toggles connection labels, Links shows every decision and registry link (otherwise only the selected element's links show; hovering an element lights up its connections), the sun/moon button switches the page between its dark and light theme (remembered, shared with the diagram pages' theme choice), Export PNG saves the picture. On a diagram page the switch reads Diagram | Graph and opens the graph already narrowed to that diagram. Archify | Open Model Graph does the same from the Command Palette or Explorer.
Queries. Type a few words in the box (/ focuses it); matches stay bright, the rest dims, the count shows "9 of 14 elements". Terms combine with AND and a leading - excludes: database (id, label, sublabel, brand or type contain it), type:backend, diagram:0200-* (what those diagrams draw), decision:<id> (what a decision is about or is attached to), uses:api (an element and its neighbours), near:api,2 (within two steps), from:web to:db (the shortest path, following the arrows first), unused (registry elements no diagram draws), shared and -shared (registry or inline elements only), type:decision and type:registry for the decision and registry nodes. Decisions and registries follow the elements they are attached to into a result; -type:decision or -type:registry leaves them out. Walks and paths follow the diagrams' connections only, so a registry is never a shortcut between its elements. The ? button lists them; clicking an example runs it.
Side panel. Click an element for its description, type, where it is defined (Registry opens the file at the line), the diagrams that draw it (click to open), its connections and its decisions (click to open). Neighbours runs uses: for it. Click a connection for its labels, the diagrams that draw it and its decisions. Click a decision node for its status, context and decision text, the elements and connections it is about, and Open decision; a registry node for the elements it defines, the ones no diagram draws yet, and Open registry.
Commands. Archify | Open Model opens the model page of the current file, from the editor title, the Command Palette or the Explorer menu of a .archify or .archify-registry file; Archify | Open Model Graph opens the graph.

Formats in detail: docs/model.md. A full example: examples/online-shop.

Source evidence

A diagram that declares meta.repository and sources is verified against a local Git checkout whose origin and pinned commit match. The extension uses the Git top-level directory of the diagram file, or archify.repoRoot when set.

When verification fails, the default (archify.sourceEvidence: "fallback") still shows the diagram without source links, explains why in a notice, and reports the reason as a warning. Set it to "strict" to treat this as an error, as the Archify CLI does. Archify | Render to HTML File… always verifies strictly and asks before rendering without source links.

Settings

Setting	Default	Description
`archify.theme`	`vscode`	`vscode` follows the color theme; `dark` or `light` force one; `diagram` keeps the diagram's own choice.
`archify.defaultView`	`2d`	`3d` opens diagrams in the 3D view. Each open diagram remembers its own choice.
`archify.preview.liveUpdate`	`true`	Re-render while typing; when off, re-render on save.
`archify.preview.debounceMs`	`400`	Delay before re-rendering after an edit.
`archify.validation.enabled`	`true`	Report validation results in Problems.
`archify.quality`	`""`	Force the `standard` or `showcase` quality profile.
`archify.sourceEvidence`	`fallback`	`fallback` or `strict` handling of unverifiable source evidence.
`archify.repoRoot`	`""`	Checkout used to verify source evidence.
`archify.nodePath`	`""`	Node.js 18+ executable to use instead of VS Code's runtime.

Security

Diagrams run in a webview with a strict content security policy. Only the page's own inline scripts and the extension's bundled 3D viewer run (via a per-render nonce), there is no network access for scripts or fetches, and links open through VS Code.

Development

npm install
npm run build             # bundle to dist/
npm test                  # unit tests + renderer tests (Node)
npm run test:integration  # runs the suite inside VS Code
npm run package           # build archify-vscode-ext-<version>.vsix

Press F5 to launch an Extension Development Host with the test fixtures.

Code layout

Folder	What it holds
`src/extension.ts`	Activation: creates the views and registers everything
`src/commands/`	Command handlers, grouped by job, and the editor context keys
`src/views/`	The diagram view (editor for `.archify`, side preview for JSON) and the HTML viewer
`src/webview/`	The page the views show: CSP, the bridge script, messages from the page
`src/archify/`	Running the bundled Archify CLI: render, validate, runtime settings
`src/sources/`	Reading diagram files: type detection, YAML/JSON, source evidence
`src/language/`	Editor help: Problems, brand completion, templates
`src/util/`	Logging, settings, file reading
`src/viewer3d/`	The 3D view; runs inside the Archify page and is bundled to `dist/viewer3d.js` with three.js

Updating the bundled renderer

vendor/archify/ and schemas/ are generated from an Archify checkout:

node scripts/sync-archify.mjs /path/to/archify   # default: ../../ws-storm/archify
npm test

vendor/archify.json records the upstream version and commit.

Support

Archify Diagram Viewer is built and maintained in my spare time. If it helps you, a coffee keeps the releases coming:

Bug reports and ideas are welcome in the repository issues.

License

MIT. See LICENSE. The bundled renderer is MIT-licensed by tt-a1i; see vendor/archify/LICENSE and vendor/archify/THIRD_PARTY_NOTICES.md.

README.md Unescape Escape

Archify Diagram Viewer