Files

T

root-at-skic 38cdc7604f Registry as Archify cards on the model page; cards under model diagrams from registry descriptions

- model page: registry elements are rendered as Archify info cards (type
  colour dot, label, id · type, description, used-in chips that open the
  diagram), replacing the table
- resolveRefs: a diagram without cards of its own gets one card per drawn
  shared element that has a description, so the registry text shows under
  every model diagram as it does on hand-written diagrams
- unit tests for generated cards, own cards winning and no cards without
  refs; docs and changelog

2026-10-19 12:53:45 +03:00

4.1 KiB

Raw Blame History

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.

Cards under a model diagram

Archify shows cards (a coloured dot, a title, a few lines) below a diagram. A diagram inside a model that draws shared elements and defines no cards of its own gets one card per drawn element that has a description in the registry, in drawing order, with the dot colour of the element's type. Write your own cards: in the diagram to replace them.

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.

4.1 KiB Raw Blame History