root-at-skic
7a2b661afe
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.
83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
# 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.
|
|
|
|
## 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.
|