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

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

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

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

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

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