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.

```yaml
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).

```yaml
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

```yaml
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:

```yaml
  - 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.

## `name.archify-decision`

One architecture decision of the model, anywhere under the root (`decisions/` by convention):

```yaml
schema_version: 1
decision:
  id: queue-between-api-and-worker   # unique in the model; words, or a quoted number
  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.
```

Checks (`model:validate`): id present and not a bare number, status known, every element in a registry, every diagram present, every superseded id present. A decision that another one supersedes is shown as superseded whatever its own status says.

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

```yaml
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 resolver strips the key before Archify sees the diagram and reports an unknown id at its line. Outside a model the key is an error, like `ref`. The extension shows decisions on the `main.archify` page, in a Decisions panel under each diagram, on element cards, and opens a decision file as its own page.