Open app →

C4 diagrams and the architecture model

ArchForge diagrams follow the C4 model. Instead of drawing each picture by hand, you describe your architecture once in a shared model, and every diagram is a view onto it. Rename a system or add a relationship in the model, and every diagram that shows it updates.

Diagrams are available on the Pro and Enterprise plans. Anyone in the workspace can view them. Editing the model and creating diagrams requires the Member role or higher.

Open Diagrams in the sidebar. The page has two tabs:

  • Views lists your diagrams.
  • Model is where you edit the shared model and manage snapshots.

The model

Everything on a diagram comes from the model at Diagrams > Model. The model editor is organized into panels.

Groups

Groups are named boundaries, such as a domain, a business unit, or a cloud account, that you place systems, people, and containers inside. Groups can be nested (up to eight levels deep) by choosing a parent in the dropdown next to each group.

  1. Type a name in New group name and click Add group.
  2. To nest it, pick a parent group in its dropdown, or leave it at (root).
  3. Rename a group by editing its name in place.

Deleting a group never deletes what's inside it. Its child groups and members move up to the deleted group's parent.

On diagrams, groups appear as labelled boundaries around the elements they contain. Only groups that contain something on the view are drawn.

Systems

Systems are the software systems you own. Each system can be placed in a group and can contain containers.

  • Add system: type a name in New system name and click Add system.
  • Add from application catalog (Enterprise): select one or more applications and click Add selected. A system added this way is bound to its application. It shows the application's ref ID and takes its name from the catalog entry, so renaming the application renames the system. Each application can be added to the model only once.

Use the arrow next to a system to expand it and manage its containers.

Containers

Containers are the deployable parts of a system: web apps, APIs, databases, queues. Expand a system to see its Containers table, then fill in New container name, an optional Description, and an optional Technology (free text), and click Add container.

If your workspace uses Technology Components, you can also link a container to one or more components from the list beside the form. Linked components show as ref ID badges in the container's Technology column, next to any free-text technology.

People and external systems

The People & external systems panel holds the actors around your systems:

  • People: users, customers, operators. Click Add person.
  • External systems: systems you depend on but don't own, such as a payment provider or a partner API. Click Add external system.

Each takes a Name, an optional Description, and an optional group.

Relationships

Relationships connect any two elements. Pick a From and To element, give it a Description (for example "places orders via"), optionally a Technology (for example "HTTPS/JSON"), and click Add relationship.

  • An element can't relate to itself.
  • The same from, to, and description combination can only exist once.

You can draw relationships between containers. Views that don't show those containers automatically lift the relationship up to the containing system, so you only model each connection once.

Deleting elements

Click Delete on any row to remove it. Deleting a system also removes its containers, and deleting an element removes its relationships.

Diagram views

Each diagram is one of three C4 view types:

View typeWhat it shows
System landscapeEvery system, person, and external system in the model, with the relationships between them. Containers are not shown.
System contextOne system plus every person and system it has a direct relationship with.
ContainerOne system drawn as a boundary, with its containers inside and the people and systems they connect to outside.

Create a diagram

  1. Go to Diagrams and click + New diagram.
  2. Enter a Title.
  3. Choose a View type.
  4. For System context and Container views, choose the System the diagram is about.
  5. Click Create.

New diagrams start in Draft. The diagram page shows its ref ID and version, its status and view type, and the rendered canvas.

Reading a diagram

Diagrams are laid out automatically, so there is nothing to drag or align. Pan and zoom with the mouse or the on-canvas controls, and use the minimap in the corner to find your way around large views.

If the system a context or container diagram is about has been deleted from the model, the diagram shows a message instead of a canvas. Restore the system under Model, or delete the diagram and create a new one.

Hide elements on one view

Large landscapes can get noisy. To declutter a single diagram without changing the model:

  1. Open the diagram and expand Hide elements below the canvas.
  2. Tick the elements you want to hide.
  3. Click Apply.

Hidden elements stay in the model and on every other diagram. Untick them and click Apply to bring them back.

Snapshots

A snapshot freezes the entire model, every element, group, and relationship, at a point in time. Use snapshots to record a baseline before a migration, or to show how the architecture looked at the end of a quarter.

Take a snapshot

  1. Go to Diagrams > Model and scroll to Snapshots.
  2. Enter a Snapshot name and an optional Note (optional).
  3. Click Create snapshot.

Deleting a snapshot requires the Admin role.

View a diagram at a snapshot

Every diagram page has a row of buttons above the canvas: Live, followed by one button per snapshot. Click a snapshot to see the diagram drawn from the model as it was when the snapshot was taken. A banner names the snapshot and links back to live.

While viewing a snapshot, Hide elements is not available. If the diagram's subject system didn't exist yet when the snapshot was taken, the page says so.