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.

arc42

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