root-at-skic
90a0c0d109
The extension shows descriptions as tooltips in its Elements panel; the resolver no longer adds cards to a diagram.
103 lines
4.7 KiB
Markdown
103 lines
4.7 KiB
Markdown
# 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.
|