Get started
The C4 model
How Archibara represents the C4 levels: the kinds of objects, which object can sit inside which, and how strict and relaxed workspaces validate those rules.
The C4 model describes software at increasing levels of detail: the systems and the people who use them, the containers inside a system, and the components inside a container. Archibara stores these as objects in one model, links each object to its parent, and shows each level in its own kind of view.
Levels and view kinds
| Level | View kind | What it shows |
|---|---|---|
| 1 | Landscape or System context | People and software systems, inside and outside your organisation |
| 2 | Container | The applications and data stores inside one software system |
| 3 | Component | The building blocks inside one container |
| none | Deployment | Where containers and systems run |
| none | Custom | Anything you want to show, with every object type available |
Archibara does not model code (C4's fourth level). A new workspace starts with one Landscape view called System landscape. Container and Component views are usually detail views that you open from a system or a container; see One model, many views.
Object kinds
Every object has a Kind. The canvas uses short names for the common ones: System, Actor, App, Store and Component.
| Kind | On the canvas | Represents | Can be inside |
|---|---|---|---|
| Person | Actor | A user, role or team that uses your systems | Nothing: always top level |
| Software system | System | A system that delivers value, yours or someone else's | Nothing: always top level |
| Container | App, or Store for data | Something that runs or stores data, such as a web app, API, database or queue | A Software system |
| Component | Component | A building block inside a container | A Container |
| Deployment node | A machine, cluster, environment or other place where software runs | Another Deployment node, or top level | |
| Infrastructure node | Supporting infrastructure, such as a load balancer or DNS | A Deployment node | |
| Deployment instance | One deployed copy of a container or system | A Deployment node or Infrastructure node | |
| Custom | Anything the other kinds do not cover | Any object that can contain others |
Rules that follow from the table:
- A Person and a Deployment instance can never contain other objects.
- A Person and a Software system can never be placed inside another object.
- Every other kind may also sit inside a Custom object.
- A Container without a parent system and a Component without a parent container are allowed, but Archibara reports them as warnings.
Deployment instances are created with Instances on the Views tab rather than from the canvas. You can change any other object's kind later in the inspector.
Roles, ownership and status
- Role refines the kind and chooses the icon: Frontend, Backend, Service, API, Database, Queue, Event bus, Object storage, Cache, Identity provider, External API, Mobile app, Web app, Worker, Serverless function, AI service or Custom.
- Ownership is Internal or External: who controls the object, you or an outside provider. External objects are drawn differently.
- Status is Live, Future, Deprecated or Removed, so one model can show what exists now, what is planned and what is being phased out. Connections have a status too.
Parents
Set an object's Parent in the inspector. Objects you create on a detail view get the right parent automatically: an App or Store added to a system's container view belongs to that system, and a Component added to a container's component view belongs to that container.
The parent relationship is what connects the levels. A system's detail view shows its children, and when a view shows children without their parent, Archibara draws the parent as a frame around them (with Show boundaries turned on in the view settings).
Groups are different: a group is a frame that belongs to one view and organises its cards, for example by environment, network zone or team. It is not an object in the model, cannot be the end of a connection and does not define a C4 level.
Strict and relaxed workspaces
Each workspace has a Validation mode, chosen when you create it. To change it, open the workspace's menu on the Workspaces page, select Edit and pick another mode.
- Relaxed — warn about C4 rule violations saves a change that breaks the parent rules and lists the problem under Issues. This is the default, and imports from Mermaid always start relaxed.
- Strict — reject C4 rule violations refuses such a change and tells you why, for example when you try to place a Container inside a Component.
Switching a relaxed workspace to strict is never blocked by problems it already has: existing problems stay listed, and only new violations are refused.
Issues
The left end of the status bar counts errors and warnings. Select it to open Issues, then select an issue to jump to the object or connection it concerns. Archibara checks the model continuously:
| Level | Examples |
|---|---|
| Errors | An object inside a parent that cannot contain it, a containment cycle, a reference to a missing object or view, a tag group that allows one tag holding two |
| Warnings | A Container without a system, a Component without a container, a database without a technology, a connection without a description, a person talking directly to a database, an object connected to itself |
| Hints | An object without a description or technology, a connection without a technology, an object that appears in no view, an object with no connections |
Warnings and hints never block your work. They are a checklist for a model that others can read without you.