archify-vscode-ext/docs/model.md

Models: the file formats

A model is a folder of diagrams that belong together: a main.archify at its top, any number of diagrams below it, and *.archify-registry files for the things several diagrams share. Three file kinds, all YAML, all read by the extension; Archify itself only ever sees plain diagrams.

main.archify

schema_version: 1
model:
  id: online-shop
  name: Online Shop
  description: >
    Web shop, its API, workers and stores.

Optionally, below the model block, a diagram exactly as in any other .archify file (diagram_type, meta, components, …). The extension shows it on the model page; Archify never sees the model block.

name.archify-registry

schema_version: 1
elements:
  api:
    type: backend
    label: API
    sublabel: REST service
    brand: node-js
    description: >
      Node.js service behind the load balancer.
    diagram: 0300-components/api.archify
  db:
    type: database
    label: Database
    sublabel: PostgreSQL
    brand: postgresql
    description: Orders, customers and catalogue.

• The key is the element's id, unique across all registry files of the model.
• type, label, sublabel, tag, icon, brand, sources are Archify's component fields and are copied into every diagram that refers to the element.
• description is the one description of the thing; shown on hover and on the model page, never sent to Archify.
• diagram is the link: the diagram that explains the element, relative to the model root. Clicking the element in any diagram opens it.

A diagram that refers to the registry

components:
  - ref: api
    pos: [250, 160]
    size: [130, 60]
  - ref: db
    label: Orders DB           # a diagram may override label, sublabel, tag
    pos: [460, 260]
    size: [130, 60]
  - id: cron                   # an unshared element, inline, as today
    type: backend
    label: Nightly job
    pos: [460, 420]
    size: [130, 60]

• ref names a registry element; id defaults to the same name. id: db-replica with ref: db draws the same element twice or under another id.
• A diagram may override label, sublabel and tag; never type or brand (if those differ, it is a different element).
• Before Archify runs, the extension replaces each ref component with the registry element plus the diagram's own fields, drops description and diagram, and hands Archify an ordinary component.
• Connections, boundaries and everything else stay as they are and use the ids as before.

Descriptions under a model diagram

Archify's Elements panel under a diagram lists its nodes. For a ref component the row's tooltip is the element's registry description. Archify's own cards: stay what they are: write them in the diagram when you want text blocks below it; nothing is generated.

Links between diagrams

A diagram may point at another diagram from a component, whether shared or inline:

  - ref: api
    pos: [250, 160]
    size: [130, 60]
    diagram: 0300-components/api.archify   # overrides the registry's link for this diagram

Registry diagram links and component diagram links are the same mechanism; the component's wins when both exist. Paths are relative to the model root.

Outside a model

A diagram with ref components outside any model (no main.archify above it) reports "no registry found" and shows the component by its ref name with type external, so the picture still renders.

Starting a model

Archify | New Model… (right-click a folder, File → New File…, Command Palette) offers three complete examples: C4 - Standard Web App, C4 - E-Shop and C4 - Event-Based Integration. Pick one and a folder name; the example is copied into that folder with model.id, model.name and the overview title taken from the folder name (an example kept under its own name is copied as is). Each example has registry/{people,systems,containers}.archify-registry and diagrams under 0100-context, 0200-containers and 0300-components; every registry element is used by at least one diagram and every diagram validates.

Decisions

An architecture decision is one *.archify-decision file, anywhere under the model root (decisions/ is the convention):

schema_version: 1
decision:
  id: queue-between-api-and-worker   # unique in the model, any short string
  title: A queue between the API and the worker
  status: accepted                   # proposed | accepted | superseded | rejected
  date: 2026-09-16
  elements: [api, queue, worker]     # registry ids
  diagrams: [0200-containers/online-shop.archify]
  supersedes: []                     # ids of older decisions this one replaces
context: >
  Why a decision was needed.
decision: >
  What was decided.
consequences: >
  What becomes easier, harder, or must change.

Ids are strings; an unquoted number such as 0001 is refused because YAML reads it as 1. A decision another decision supersedes shows as superseded whatever its own status says. Unknown elements, missing diagrams, duplicate ids, unknown statuses and dangling supersedes are problems on the decision file.

Diagrams point back at decisions with a decisions list of ids on the diagram itself, on a component (or node, participant, state) and on a connection (or edge, flow, transition, message):

decisions: [postgres-as-source-of-truth]
components:
  - ref: queue
    pos: [460, 360]
    size: [130, 60]
    decisions: [queue-between-api-and-worker]
connections:
  - { from: api, to: queue, label: enqueue, decisions: [queue-between-api-and-worker] }

The key is stripped before Archify renders. An unknown id is a problem at its line; outside a model the key is an error, like ref. The main.archify page lists all decisions; a diagram page lists the ones it points at or that name it; an element's card and dialog list the decisions about it. A .archify-decision file opens as its own page. Outside a model it still opens, with a note that it has lost its model.