Files

T

root-at-skic 7a2b661afe Models: main.archify, registries, refs, links and the model page; 0.7.0

A folder with main.archify at its top is a model, a set of diagrams
that belong together. Opening main.archify shows the model page: the
model's name and description, its own overview diagram when the file
has one, the diagrams grouped by folder (click to open), and the
registry with where each element is used. The page is built by
traversing the folder tree and refreshes when files change.

*.archify-registry files define shared elements once; diagrams draw
them with `ref: <id>` plus position and may override label, sublabel
and tag. References are resolved before Archify runs, so Archify is
unchanged. Hover, go-to-definition and completion on ref; unknown
names, forbidden overrides, duplicate ids and broken registries in
Problems; registry edits re-render open diagrams. `diagram:` links on
elements and components open the linked diagram on double-click.

New command Archify | Open Model, a Model template for New Diagram…,
editor schemas for the new keys and for registries, docs/model.md and
examples/online-shop. Single diagrams behave exactly as before.

2026-10-19 11:37:20 +03:00

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

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.

3.1 KiB Raw Blame History