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.

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.