One name for one thing: architecture models in VS Code
Define an element once, draw it in as many diagrams as you like, and let the editor tell you where it is used. Archify Diagram Viewer 0.7.0 adds models.
Every architecture has a few things that appear everywhere. The API shows up in the context diagram, the container diagram, the deployment view and three sequence diagrams. Each time someone draws it again: name, technology, a one-line description. Six copies, and after a quarter they say six different things.
Archify Diagram Viewer, the VS Code extension that turns a short YAML file into an interactive diagram, can now keep a set of diagrams together as a model, with shared elements defined once. Nothing changes for a single diagram: a lone .archify file opens exactly as before. A model is what you get when you want more than one.
A folder with a main.archify on top
A model is a folder. The file main.archify at its top marks it and names it. Everything below is part of the model: diagrams in any folders you like, and one or more registries of shared elements.
shop/
main.archify
registry/
people.archify-registry
systems.archify-registry
containers.archify-registry
0100-context/shop.archify
0200-containers/shop.archify
0300-components/api.archifyThe numbered folders are a convention, not a rule; the extension groups diagrams by whatever folders it finds. main.archify carries the model's id, name and description, and may carry a diagram of its own, which is a good place for the overview.
schema_version: 1
model:
id: shop
name: Online Shop
description: >
The web shop, its API and workers, and the
stores behind them.Click main.archify and you get the model page: the description, the overview if there is one, then two panels. Diagrams lists every diagram by folder, each folder its own collapsible header, each diagram a card that opens it. Registries lists the registry files, each its own collapsible header with an element count and an Open button; expand one and its elements appear. The panels remember whether you left them open or closed.
Define an element once
A registry is a YAML file that ends in .archify-registry. Each element has an id and the fields you would otherwise repeat in every diagram: type, label, sublabel, brand, a description.
schema_version: 1
elements:
api:
type: backend
label: API
sublabel: Node.js
brand: node-js
description: Owns sign-in, orders and the catalogue.
diagram: 0300-components/api.archify
db:
type: database
label: Database
sublabel: PostgreSQL
brand: postgresql
description: Orders and customers; the source of truth.A diagram then draws the element with ref and a position. That is the whole component.
components:
- ref: customer
pos: [40, 160]
size: [130, 60]
- ref: api
pos: [250, 160]
size: [130, 60]
- ref: db
pos: [460, 60]
size: [130, 60]The extension expands the references before Archify renders, so the rendered diagram is a normal Archify diagram with logos, types and labels. A diagram may still define elements inline next to the shared ones, and may override label, sublabel and tag on a reference when a view needs a different wording. Anything else comes from the registry and stays there; change it in one place and every diagram that uses it re-renders.
Get Root At Skic’s stories in your inbox
Join Medium for free to get updates from this writer.
While you type, the editor helps. After ref: the completion list shows the registry. Hovering a reference shows the element's description. F12 jumps to the registry line that defines it. An unknown name, a duplicate id or a forbidden override lands in the Problems panel at the right line.
Where is this used?
The question a registry answers best is the reverse one. Open a registry file and the extension shows its elements as cards. Click one and a dialog shows the description, the line that defines it, and every diagram that uses it. Click a diagram to open it.
The same cards sit on the model page under each registry file, so from the overview you can go element by element and see what each one touches. An element nobody uses says so.
Elements and connectors under the diagram
Below the drawing, Archify’s node index is now titled Elements, and for a shared element the row’s tooltip is its registry description, so the text you wrote once is one hover away in every diagram. A new Connectors panel next to it lists every connection as “from → to” with its label. Hover a row and the connector lights up in the diagram; click it and it stays lit.
Diagrams can link to each other too. A registry element with diagram: 0300-components/api.archify says "this diagram explains me", and a double-click on that node in any diagram opens it. Context, containers, components: the C4 levels become a click apart.
The reasons, next to the drawing
Version 0.8.0 adds the part of an architecture that diagrams never show: why it is the way it is. A decision is one small .archify-decision file in the model, with an id, a title, a status, a date, the registry elements and diagrams it is about, and three short texts: context, decision, consequences. Diagrams point back at it with decisions: [queue-between-api-and-worker] on the diagram, on a component or on a connection, so the reason sits on the exact arrow it explains. Under every diagram a Decisions panel joins Elements and Connectors; hover a row and the node or connection it is attached to lights up, click it and the decision opens as its own page with the elements it touches. The main.archify page lists all decisions, newest first, superseded ones dimmed. Links are checked like everything else in a model: a decision about an element nobody defines, or a diagram pointing at a decision nobody wrote, is a problem at that line. Archify | New Decision… on a folder writes the file from a template, and the code-agent skill validates and lists decisions the same way, so an agent that adds a queue can leave the reason next to the queue.
Start from an example
You do not have to build the folder by hand. Right-click a folder in the Explorer, choose Archify | New Model…, and pick one of three complete models:
- C4 — Standard Web App: a single-page app, an API, a database, a cache, file storage and an identity provider.
- C4 — E-Shop: a web shop, its API and worker, a queue, and payment and email providers.
- C4 — Event-Based Integration: an event bus, a router with validation and enrichment, a dead-letter queue, an event store and consumers.
Each one comes with a registry and context, container and component diagrams that validate, named after the folder you choose. Replace the elements with yours and the diagrams follow.
For the agents, too
If an AI coding agent writes your diagrams, the same format is available to it as a skill: archify-vscode-ext ships the three examples, scaffolds a model folder, validates every diagram against the registry and renders a model to HTML without VS Code. A diagram that validates there opens the same way in the editor.
Try it
Version 0.7.0 of Archify Diagram Viewer is on the VS Code Marketplace; search for “Archify” in the Extensions view. It bundles the open-source Archify renderer and needs nothing else. Your existing .archify files keep working. Add a main.archify above them, move the names you keep repeating into a registry, and let the editor keep them straight.
Archify Diagram Viewer is free and open source. If it saves you time, you can buy me a coffee.
