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