Add archify-vscode-ext skill: Archify diagrams and models for the Archify Diagram Viewer extension
Model tasks (validate, list, scaffold, resolve), diagram tasks (validate, render), the bundled Archify 3.0.1 runtime and yaml parser under scripts/vendor, references for authoring, formats and folders, and the online-shop example model.
This commit is contained in:
commit
b6b5e57922
226 files changed
+67520
No files matched your search
@@ -0,0 +1,169 @@
|
||||
# Authoring Archify diagrams
|
||||
|
||||
What an agent needs to write a diagram that validates and reads well. The schemas under `scripts/vendor/archify/schemas/` are the authority; read the kind's schema and `common.schema.json` before using a field not listed here. Archify rejects unknown keys everywhere (`additionalProperties: false`).
|
||||
|
||||
## Every diagram
|
||||
|
||||
```yaml
|
||||
schema_version: 1 # 1 for architecture, sequence, dataflow; 2 for new workflow and lifecycle
|
||||
diagram_type: architecture # architecture | workflow | sequence | dataflow | lifecycle
|
||||
meta:
|
||||
title: Containers # required
|
||||
output: containers.html # required: relative POSIX path ending in .html, no "..", no drive letters
|
||||
```
|
||||
|
||||
Optional `meta` keys: `subtitle` (omit unless asked), `viewBox: [w, h]` (omit for architecture; Archify measures), `legend` (`mode: auto|all|hidden`, `entries: { backend: { label: Service } }` to rename), `locale` (`en`, `zh-CN`; others need `translations`), `visual_preset` (`classic` default, `signal-flow`, `blueprint`, `editorial`; only on request), `quality_profile` (`standard`, `showcase`), `animation: trace`, `repository` plus node `sources` for source-backed diagrams, `cards` (summary blocks under the diagram: `dot`, `title`, `items`).
|
||||
|
||||
Ids match `^[a-zA-Z][a-zA-Z0-9_-]*$` and are unique in their collection. Relationship `id`s are optional (they give stable `#relation=` links).
|
||||
|
||||
## Node fields (all kinds)
|
||||
|
||||
| Field | Values |
|
||||
|---|---|
|
||||
| `type` | `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external` (lifecycle states: `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, `external`) |
|
||||
| `label` | required; keep it short, the box is small |
|
||||
| `sublabel` | one fact: technology, protocol, role |
|
||||
| `tag` | small badge text (not in sequence participants) |
|
||||
| `icon` | corner symbol: `calendar`, `clock`, `person`, `briefcase`, `flag`, `moon`, a type name, or `none` |
|
||||
| `brand` | an Archify brand id (see Brands) |
|
||||
| `sources` | 1 to 3 `{ path, line, end_line, label }` repository references, with `meta.repository` |
|
||||
|
||||
`type` sets colour and legend entry. Pick by role: people and outside systems `external`; the own system as one box `cloud`; UIs `frontend`; services and jobs `backend`; stores and caches `database`; queues and topics `messagebus`; auth, gateways, secrets `security`.
|
||||
|
||||
## Architecture
|
||||
|
||||
Collections: `components` (required), `connections`, `boundaries`, `cards`, `layout`.
|
||||
|
||||
Placement is yours; Archify routes the lines but never moves boxes. Use free positions on this grid, which is what the templates and `examples/online-shop` use:
|
||||
|
||||
- box `size: [130, 60]` (`[150, 60]` for a system-level box with a longer label)
|
||||
- columns at x = 40, 250, 460, 670, 880 (step 210: an 80px clear gap between boxes)
|
||||
- rows at y = 60, 160, 260, 360, 460 (step 100: a 40px gap)
|
||||
|
||||
Rules of thumb that keep the validator quiet:
|
||||
|
||||
- Place by connections first: main path left to right, neighbours adjacent; a store or branch directly above or below its owner, centred, so the edge is one straight segment; a return edge on the side without branches.
|
||||
- A horizontal label on the 80px gap fits about 9 ASCII characters (`6.5px per character + 21px`). Longer labels: widen the step (250), or set `labelAt` when the validator asks.
|
||||
- Label width inside a box: `6.5px per character + 13px` must be under the box width; a 130px box takes about 18 characters. Sublabel: `5.4px per character + 8px`.
|
||||
- A side with k connections needs `32 + 14 * (k - 1)` px; spread a hub's partners over two or three sides.
|
||||
- External actors stay outside the boundary, including its padding.
|
||||
- Omit `meta.viewBox`; Archify sizes the canvas.
|
||||
|
||||
Connections: `from`, `to`, `label`, `variant` (`default`, `emphasis` for the main path, `security`, `dashed`), `fromSide`/`toSide` (`left|right|top|bottom`, pin only when needed), `route` (`auto`, `straight`, `orthogonal-h`, `orthogonal-v`), `via: [[x, y], ...]` (explicit waypoints, must leave the source outward on the pinned side), `labelAt: [x, y]`, `labelDx`, `labelDy`, `labelSegment`, `width`.
|
||||
|
||||
Boundaries: `kind: region | security-group`, `label`, `wraps: [ids]`, `pad`. A boundary states a real ownership, trust or deployment fact; it does not replace connections.
|
||||
|
||||
Alternative to `pos`: `row`/`col` per component with `layout: { mode: grid, origin, cols, cellW, cellH, gapX, gapY }`. Do not mix `pos` and `row`/`col` in one diagram: Archify stops with `internal/unclassified` instead of a readable error.
|
||||
|
||||
## Workflow (schema_version 2)
|
||||
|
||||
```yaml
|
||||
schema_version: 2
|
||||
diagram_type: workflow
|
||||
meta: { title: Change approval, output: workflow.html }
|
||||
lanes:
|
||||
- { id: author, label: Author }
|
||||
- { id: review, label: Reviewers }
|
||||
mainPath: [draft, review, approved, released]
|
||||
nodes:
|
||||
- { id: draft, lane: author, col: 0, type: frontend, label: Draft change }
|
||||
- { id: review, lane: review, col: 1, type: security, label: Review, sublabel: two approvals }
|
||||
edges:
|
||||
- { id: submit, from: draft, to: review, label: submit }
|
||||
- { from: review, to: draft, label: changes requested, role: branch, variant: dashed }
|
||||
```
|
||||
|
||||
`col` is 0..5, the logical step. `mainPath` lists the happy path in order; keep it monotonic. `edges.role`: `main`, `branch`, `async`, `return`, `error`. Optional `phases` and `groups` (`fromCol`, `toCol`) and `yOffset` per node (symmetric values like -90/0/90 inside one lane). `meta.legend.entries` renames types for non-software plans (see `everyday-plan` in the extension's templates: `backend` as "Time off", icons `calendar`, `briefcase`).
|
||||
|
||||
## Sequence
|
||||
|
||||
```yaml
|
||||
schema_version: 1
|
||||
diagram_type: sequence
|
||||
meta: { title: Login, output: sequence.html, viewBox: [960, 520] }
|
||||
participants:
|
||||
- { id: client, type: external, label: Client }
|
||||
- { id: api, type: backend, label: API }
|
||||
messages:
|
||||
- { from: client, to: api, y: 160, label: POST /login, variant: emphasis }
|
||||
- { from: api, to: client, y: 210, label: 200 OK, variant: return }
|
||||
```
|
||||
|
||||
Participants are columns in order; messages run top to bottom by `y` (50px apart is comfortable). `variant` adds `return`. Optional `note` per message, `segments` (`from`, `to`, `label`) and `activations` (`participant`, `from`, `to`). `meta.column_fit: spread` uses a wide viewBox for column distance.
|
||||
|
||||
## Dataflow
|
||||
|
||||
```yaml
|
||||
schema_version: 1
|
||||
diagram_type: dataflow
|
||||
meta: { title: Sales reporting, output: dataflow.html, viewBox: [960, 420] }
|
||||
stages: [{ label: Sources }, { label: Processing }, { label: Storage }]
|
||||
nodes:
|
||||
- { id: shop, type: frontend, label: Web shop, stage: 0, row: 0 }
|
||||
- { id: etl, type: backend, label: Nightly ETL, stage: 1, row: 0 }
|
||||
flows:
|
||||
- { from: shop, to: etl, label: orders }
|
||||
- { from: crm, to: etl, label: customers, classification: PII, variant: security }
|
||||
```
|
||||
|
||||
Stages are columns (index into `stages`), rows separate parallel streams. Label only data contracts, classifications and cross-boundary movement.
|
||||
|
||||
## Lifecycle (schema_version 2)
|
||||
|
||||
```yaml
|
||||
schema_version: 2
|
||||
diagram_type: lifecycle
|
||||
meta: { title: Order status, output: lifecycle.html }
|
||||
lanes:
|
||||
- { id: main, label: Normal path }
|
||||
- { id: exits, label: Exits }
|
||||
states:
|
||||
- { id: placed, type: start, label: Placed, lane: main, col: 0 }
|
||||
- { id: paid, type: active, label: Paid, lane: main, col: 1 }
|
||||
- { id: cancelled, type: failure, label: Cancelled, lane: exits, col: 0 }
|
||||
transitions:
|
||||
- { id: pay, from: placed, to: paid }
|
||||
- { id: cancel, from: placed, to: cancelled, variant: security }
|
||||
```
|
||||
|
||||
Each lane is a row (`main` first, `terminal` last); `col` 0..4 is one shared x grid, so put an exit in the column of the state it leaves. Every transition is authored, including the main path. A recoverable failure needs a real transition back. Omit `viewBox` in v2.
|
||||
|
||||
## Brands
|
||||
|
||||
`brand` puts a product logo on a node. Use the canonical id from the bundled catalogue:
|
||||
|
||||
```bash
|
||||
node scripts/vendor/archify/bin/archify.mjs brands "kafka" --json # id apache-kafka
|
||||
node scripts/vendor/archify/bin/archify.mjs brands --json # all 107
|
||||
```
|
||||
|
||||
Ids include `postgresql`, `redis`, `mysql`, `mongodb`, `apache-kafka`, `rabbitmq`, `docker`, `kubernetes`, `terraform`, `node-js`, `react`, `vue`, `python`, `go`, `rust`, `typescript`, `spring`, `django`, `fastapi`, `github`, `gitlab`, `jenkins`, `grafana`, `prometheus`, `stripe`, `paypal`, `openai`, `anthropic`, `claude`, `google-cloud`, `cloudflare`, `vercel`, `supabase`, `snowflake`, `databricks`. An unknown brand is a validation error; omit `brand` rather than guess. A URL brand needs `archify brands capture <url>` first (network) and the returned digest.
|
||||
|
||||
## Validator output and fixes
|
||||
|
||||
`task model:validate` and `task diagram:validate` map Archify's diagnostics to the file, line and JSON pointer. Fix in this order, one coherent change at a time, validating after each:
|
||||
|
||||
| Code or message | Cause | Fix |
|
||||
|---|---|---|
|
||||
| `YAML: ...` | syntax error, usually `: ` inside a plain scalar | `>` block scalar or quotes |
|
||||
| `schema/additionalProperties` | an unknown key | remove or rename it; model keys only in registries and `ref` nodes |
|
||||
| `schema/...` other | wrong enum, missing `meta.output`, bad id, `schema_version` not allowed for the kind | read the message; the pointer names the node |
|
||||
| `Label "..." is wider than component` | label too long for `size` | widen `size[0]` or shorten |
|
||||
| `Components "a" and "b" are less than 8px apart` | overlap | use the suggested `pos` |
|
||||
| `clean-flow/edge-through-node` | an edge crosses an unrelated box | move the box off the corridor, or `fromSide`/`toSide`, or `via` |
|
||||
| `clean-flow/endpoint-side-direction` | `via` leaves the box inward | first waypoint must be outward on the pinned side |
|
||||
| `composition/label-gap`, `label_route_clearance` | labels collide with routes, boxes or each other | enlarge the gap or set the suggested `labelAt`; never delete the label |
|
||||
| `layout/boundary-out-of-bounds`, `layout/route-out-of-bounds` | negative coordinates or an authored `viewBox` too small | move inward, or remove/enlarge `viewBox` |
|
||||
| `composition/excessive-route-detour` | an explicit `via` is far longer than needed | remove the `via` |
|
||||
| `Component ids must be unique` | duplicate id | rename, or `id:` next to `ref:` |
|
||||
| `brand/unknown` | brand id not in the catalogue; the message lists the closest ids | use one of them, or omit `brand` |
|
||||
|
||||
`--quality=showcase` turns composition warnings (crossings, corridors, border runs, route rhythm) into failures; use it for diagrams that will be presented. `--layout-json` on the plain Archify CLI (`archify validate architecture x.json --layout-json`) prints the resolved boxes, routes and label positions when a repair needs measurements; get `x.json` from `task model:resolve`.
|
||||
|
||||
## Composition
|
||||
|
||||
- One obvious main path, `variant: emphasis` on it. Branches beside their owner. Stores below their writer.
|
||||
- Labels carry meaning (protocol, action, direction, async). Omit one only when both endpoints imply it.
|
||||
- Group only real boundaries. A boundary around one box needs a real isolation fact.
|
||||
- A C4 level answers one question; put details in the next level and link it with `diagram:`.
|
||||
- Title only; no subtitle, no preset, no legend overrides unless asked.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Folder layouts
|
||||
|
||||
Diagrams are `.archify` files; a registry is an `.archify-registry` file. The extension knows a file by its extension; the names in front are yours, with one reserved name: `main.archify`, the entry point of a model.
|
||||
|
||||
## A single diagram
|
||||
|
||||
```
|
||||
anywhere/
|
||||
payment-flow.archify
|
||||
```
|
||||
|
||||
Nothing else. Works as a plain diagram, also when it sits inside a model folder.
|
||||
|
||||
## A model, smallest form
|
||||
|
||||
```
|
||||
online-shop/
|
||||
main.archify entry point: id, name, description, optionally a diagram
|
||||
online-shop.archify-registry one name for one thing: what several diagrams use
|
||||
containers.archify
|
||||
checkout-flow.archify
|
||||
order-lifecycle.archify
|
||||
```
|
||||
|
||||
The folder that contains `main.archify` is the root; everything below belongs to the model. Any number of diagrams of any kind. A diagram that uses a thing from the registry refers to it by name; a diagram that does not is still a plain diagram.
|
||||
|
||||
## A larger model, grouped
|
||||
|
||||
```
|
||||
online-shop/
|
||||
main.archify
|
||||
registry/
|
||||
people.archify-registry
|
||||
services.archify-registry
|
||||
stores.archify-registry
|
||||
services/
|
||||
containers.archify
|
||||
api-components.archify
|
||||
processes/
|
||||
checkout-flow.archify
|
||||
refund-sequence.archify
|
||||
order-lifecycle.archify
|
||||
```
|
||||
|
||||
Groups are folders you choose, shown in folder order. The registry may be one file or a folder of files split any way (by kind, by team).
|
||||
|
||||
## C4
|
||||
|
||||
The four C4 levels are four groups of diagrams. The registry holds the things C4 talks about: people, software systems, containers, components. Each level's diagram zooms into one thing from the level above, and the registry entry of that thing points at its diagram.
|
||||
|
||||
```
|
||||
online-shop/
|
||||
main.archify id, name, description; may hold an overview diagram
|
||||
registry/
|
||||
people.archify-registry customer, support agent
|
||||
systems.archify-registry online shop, payment provider, email service
|
||||
containers.archify-registry web app, api, worker, database, queue
|
||||
components.archify-registry api: auth, orders, catalogue; worker: mailer, invoicing
|
||||
0100-context/
|
||||
online-shop.archify people and systems around the shop
|
||||
0200-containers/
|
||||
online-shop.archify inside the shop: web app, api, worker, database, queue
|
||||
0300-components/
|
||||
api.archify inside the api: auth, orders, catalogue
|
||||
worker.archify inside the worker: mailer, invoicing
|
||||
0400-code/ optional; usually left out
|
||||
orders.archify classes inside the orders component
|
||||
```
|
||||
|
||||
How the levels hang together:
|
||||
|
||||
- The system "online shop" in `systems.archify-registry` points at `0200-containers/online-shop.archify`. Click the shop in the context diagram and the containers diagram opens.
|
||||
- The container "api" in `containers.archify-registry` points at `0300-components/api.archify`. Click the api, see its components.
|
||||
- The same api, drawn in the containers diagram and in several component diagrams, is one entry with one description.
|
||||
|
||||
The numbered folders are only for sorting; nothing depends on the names. A team that wants only context and containers has `main.archify`, two folders and two registry files. `task model:scaffold --c4` creates this shape with three levels and empty registries; `examples/online-shop/` in this skill is the filled-in version.
|
||||
|
||||
Component types that fit C4: people are `external`; the system itself and other systems are `cloud` (own) or `external` (others); containers are `frontend`, `backend`, `database`, `messagebus`, `security`; components inside a container use the same set, wrapped in a `region` boundary named after the container.
|
||||
|
||||
## How the extension knows it is in a model
|
||||
|
||||
The nearest folder above a file that contains `main.archify` is the root. Under that root, at any depth: `*.archify` are member diagrams, `*.archify-registry` make up the registry, subfolders are groups. `node_modules` and `.git` are skipped.
|
||||
|
||||
- No `main.archify` anywhere above: a single diagram.
|
||||
- A diagram inside a model still opens, renders and exports on its own.
|
||||
- A second `main.archify` deeper down would start a nested model; not supported, reported.
|
||||
|
||||
## What you see in VS Code
|
||||
|
||||
Any `.archify` diagram: click it, the diagram opens, with Show Source, live updates, Problems, export and 3D.
|
||||
|
||||
`main.archify`: the model page instead of a diagram:
|
||||
|
||||
1. the metadata: id, name, description;
|
||||
2. the file's own diagram, if it has one, drawn like any other diagram;
|
||||
3. the list of diagrams, grouped by folder, each with its title and kind; diagrams next to `main.archify` first, ungrouped, then deeper ones by folder path;
|
||||
4. the registry: every shared thing with its description and "used in N diagrams".
|
||||
|
||||
`task model:list` prints the same information.
|
||||
@@ -0,0 +1,102 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user