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.

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.

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.
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 Diagram…, Archify | Render to HTML File…, Archify | Open in Browser, Archify | Refresh Preview, Archify | Show Source.

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.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 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.

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.

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

Archify Diagram Viewer