archify-vscode-ext/references/folders.md

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.