root-at-skic
900e0986e6
references/folders.md gains arc42 (sections as numbered folders and cards, black boxes, quality tree) and ArchiMate (layers, type in tag and sublabel, element mapping). Gotchas: ref in every kind needs extension 0.11.0; tags are not drawn on the box.
159 lines
8.7 KiB
Markdown
159 lines
8.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.
|
|
|
|
## arc42
|
|
|
|
[arc42](https://arc42.org) is a documentation template with twelve sections; four of them are views (diagrams), the rest are text. In a model, the views are folders numbered like their section, the decisions are section 9, and the text sections are `cards` (title plus short items) on the diagram they belong to. Card titles carry the section number so a reader finds each section.
|
|
|
|
```
|
|
cinema-tickets/
|
|
main.archify section 3 business context (the system and its neighbours);
|
|
cards 1.1 Requirements, 1.2 Quality goals, 1.3 Stakeholders,
|
|
2 Constraints, 4 Solution strategy, 11 Risks and technical debt,
|
|
12 Glossary
|
|
registry/
|
|
people.archify-registry users and operators
|
|
systems.archify-registry neighbouring systems
|
|
building-blocks.archify-registry each block's description in black-box form:
|
|
"Responsibility: ... Interfaces: ..." (section 5)
|
|
0300-context/
|
|
technical-context.archify channels and protocols; card 3 Domain interfaces
|
|
0500-building-blocks/
|
|
level-1.archify the system's white box; card 8 Crosscutting concepts
|
|
booking.archify level 2 of one block, linked from its registry entry
|
|
0600-runtime/
|
|
book-seats.archify key scenarios as sequence diagrams
|
|
0700-deployment/
|
|
production.archify building blocks inside boundaries for nodes and zones;
|
|
card 7 Mapping (block -> node)
|
|
1000-quality/
|
|
quality-tree.archify Quality -> characteristics -> scenarios;
|
|
card 10 Quality scenarios (stimulus and response)
|
|
decisions/ section 9, one *.archify-decision per decision
|
|
```
|
|
|
|
Say where each section lives in `model.description`. Cards hold short lines, not prose: an arc42 document with long text belongs next to the model, not in it. `examples/arc42-cinema-tickets/`, `arc42-iot-telemetry/` and `arc42-team-wiki/` (the smallest) are complete.
|
|
|
|
## ArchiMate
|
|
|
|
[ArchiMate](https://www.opengroup.org/archimate-forum) models an enterprise in layers. Archify has no ArchiMate notation, so each element is an Archify component type with its ArchiMate type written out: in `tag` (searchable, shown in the focus panel) and in `sublabel` (shown on the box; Archify draws tags only in the focus panel).
|
|
|
|
```
|
|
insurance-claims/
|
|
main.archify layered view: Business, Application, Technology as three
|
|
region boundaries, top to bottom, three elements each in the
|
|
same columns, serves/realizes arrows between layers
|
|
registry/
|
|
business.archify-registry actors, roles, processes, services, events
|
|
application.archify-registry components, services, interfaces, data objects
|
|
technology.archify-registry nodes, system software, technology services, networks
|
|
0100-business/
|
|
business-layer.archify actors, roles and services
|
|
handle-claim.archify the business process as a workflow (lanes per role)
|
|
0200-application/
|
|
application-structure.archify components, services, interfaces, data objects
|
|
application-cooperation.archify how the components talk
|
|
0300-technology/
|
|
infrastructure.archify nodes and networks inside boundaries
|
|
decisions/
|
|
```
|
|
|
|
A mapping that reads well: actors and roles `external`; processes `backend`; business and application services `cloud` or `frontend`; application components `backend` or `frontend`; data objects `database`; nodes `backend`, `cloud` or `database`; networks `messagebus` or `security`. Name relationships in connection labels: serves, realizes, uses, accesses, assigned to, triggers. Keep type names short enough for the box (`App Component`, `Tech Service`). `examples/archimate-insurance-claims/`, `archimate-hr-onboarding/` and `archimate-logistics-tracking/` are complete.
|
|
|
|
## 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.
|