root-at-skic
57914d435c
- templates/models: C4 - Standard Web App, C4 - E-Shop, C4 - Event-Based Integration; each a complete model (main.archify, registry, context, containers, components) that validates - archify.newModel: pick an example and a folder name, copy it, name the model after the folder, open the model page - Explorer menu: New Model… on folders, Open Model on .archify and .archify-registry files; File → New File… lists New Model… - unit test validates every example end to end; integration test runs the command; README, CHANGELOG, docs/model.md
87 lines
3.8 KiB
Markdown
87 lines
3.8 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.
|
|
|
|
## 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.
|