archify-vscode-ext/references/formats.md

File formats of a model

Three file kinds, all YAML, all read by the extension. Archify itself only ever sees plain diagrams; the model keys are resolved first (by the extension, and by this skill's tasks in the same way).

main.archify

The entry point of a model. The folder that contains it is the model root.

schema_version: 1
model:
  id: online-shop              # ^[a-zA-Z][a-zA-Z0-9_-]*$
  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 as the overview. Archify never sees the model block.

A main.archify without a diagram is valid (metadata only). A model block in any other file is ignored and reported as a warning.

name.archify-registry

Shared things of the model. One file or many, anywhere under the root, split any way (by kind, by team).

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 id, unique across all registry files of the model. A duplicate is an error.
• type, label, sublabel, tag, icon, brand, sources are Archify's component fields and are copied into every diagram that refers to the element. type and label are required.
• 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, ending in .archify, must exist. Clicking the element in any diagram opens it.
• Any other key is reported as a warning and never reaches a diagram.

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, brand, icon or sources (if those differ, it is a different element). The validator reports the attempt.
• Before Archify runs, each ref component is replaced by the registry element plus the diagram's own fields; description and diagram are dropped; what remains is an ordinary component.
• Connections, boundaries and everything else stay as they are and use the ids as before.
• The same works in the node collection of every kind: components (architecture), nodes (workflow, dataflow), participants (sequence), states (lifecycle). Only fields the kind's schema accepts are copied (sequence participants have no tag; lifecycle states need a lifecycle type).

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. Levels, zoom-in and "see also" are this one mechanism.

Outside a model

A diagram with ref components outside any model (no main.archify above it) has no registry. The extension reports "no registry found" and shows the component by its ref name with type external, so the picture still renders. The validator treats it as an error: define the element inline or create the model. A diagram: link outside a model is dropped with a warning.

What the resolver does, exactly

For each diagram file under the root (and a single file outside a model):

1. Parse the YAML; a syntax error is reported with its line and stops that file.
2. Remove model (main.archify only).
3. For each node in the kind's collection: expand ref, apply the diagram's own keys, drop ref and diagram, keep id (own id or the ref name).
4. Check ids are unique in the diagram, links exist, overrides are allowed.
5. Hand the result to archify validate <kind> <json> --json (or render).

task model:resolve -- --file=… --out=x.json writes step 4's result.

Cards under a model diagram

Archify shows cards (a coloured dot, a title, a few lines) below a diagram. An architecture 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 (frontend cyan, backend emerald, database violet, cloud amber, security rose, messagebus orange, external slate). model:resolve and the extension both add them; write your own cards: in the diagram to replace them.