# 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.