root-at-skic
55894fbade
- examples/: c4-standard-web-app, c4-e-shop (was online-shop), c4-event-based-integration; the same models the extension offers under Archify | New Model… - model-scaffold --example <name> copies one and renames id, name, description and the overview title; never overwrites - tests cover every example and the copy; docs updated
100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
# 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/c4-e-shop/` in this skill is the filled-in version (two more examples sit next to it).
|
|
|
|
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.
|