Creating Your First C4 Diagram

This getting started tutorial walks you through how to create a C4 diagram directly in the C4 Designer: build a Diagram Set, add a new diagram and choose its type, place nodes and boundaries from the Toolbox, and bind them to real entities in your Repository Model.

Tip

Already have a diagram in Mermaid, PlantUML, Structurizr DSL, or Draw.io XML? Skip straight to Import Your First C4 Diagram instead — it is usually faster than rebuilding an existing diagram by hand.

Understanding How a Diagram Comes Together

A Diagram Set holds one or more diagrams. Each diagram is built by dragging shapes from a type-specific Toolbox onto the canvas, then binding those shapes to real Repository entities.

Diagram: A Diagram Set holds diagrams (blue, structure); each diagram is populated from its Toolbox (yellow, authoring); nodes and boundaries are then bound to Repository entities and can carry Custom Metadata (green, Repository link).

Step 1 — Navigate to Architecture Diagrams

In the Nodinite left navigation, open Repository → Architecture Diagrams. The landing page shows the Diagram Sets list.

Note

If you do not see this menu item, your Nodinite instance may not have the Mapify license. Contact your Nodinite administrator.

Step 2 — Create a Diagram Set

A Diagram Set groups all diagrams for one architectural subject together. Before creating a diagram, you must have a set to hold it.

1. Click New Set
2. Enter a Name for the set — use a business subject name, not a diagram type (e.g., "Order-to-Cash", "Supplier Onboarding", "ERP Integration Landscape")
3. Optionally enter a Description
4. Optionally select a Scope System — the primary System this set is centred on. When set, the set header displays a direct link to that System's detail page in the Repository
5. Click Create

The Set detail page opens, showing an empty tile grid. This is where all diagrams for this subject will appear.

Note

^{New 7.x} From Nodinite 7.6.0, new Diagram Sets honour the DefaultRolesInViews system parameter. The Roles specified in that parameter are automatically assigned to the set at creation time, giving the right teams immediate access without manual role configuration. See DefaultRolesInViews for details on configuring the default roles.

Tip: You can add as many diagrams of different types as you need — one set can hold an L0 Landscape, an L1 Context, two L2 Containers for different systems, and a Dynamic diagram. They are all siblings, all cross-linked through shared Repository bindings.

Scope and mode decision

Treat Architecture Scope as the identity of the architecture your diagram describes.

Use:

• Layered Mode when you want related C4 views in the same scope to maintain inferred relationships across zoom levels.
• Free Draw when you want local node and boundary edits that do not affect other Draft diagrams, regardless of scope.

See Diagram Set Fundamentals for the full scope model and how Layered Mode and Free Draw behave per scope.

Step 3 — Create a New Diagram

On the Set detail page, click Add Diagram. The Create Diagram modal asks for:

1. Name — the diagram title (e.g., "ERP Internal Structure")
2. Diagram type — choose the type that matches the view you want to build:
   • L0 System Landscape
   • L1 Context
   • L2 Container
   • L3 Component
   • Dynamic
   • Deployment
3. Description (optional)

If you choose L2 Container or L3 Component, also set the Architecture Scope:

• For L2: pick the System this diagram zooms into (e.g., select "ERP" — this is what makes it distinct from another L2 for "Portal")
• For L3: pick the Service this diagram zooms into

Scope is not cosmetic. Choosing scope determines which diagrams can participate in inferred navigation and layered relationships.

The new diagram is created in Draft state and opens directly in the Designer, with the Toolbox visible.

Tip

See Diagram Lifecycle for the full properties reference, including how to change the diagram type or state later.

Step 4 — Add Nodes and Boundaries from the Toolbox

The Toolbox sits on the left side of the Designer. Its contents are context-sensitive — only shapes valid for the current diagram type are shown.

Add elements

1. Expand the Elements section in the Toolbox. Shapes are grouped by C4 tier — Persons, Software Systems, Containers, Components, or Infrastructure Nodes, depending on diagram type
2. Click and drag a tile onto the canvas
3. Release the mouse button to drop the shape at that position — it is created and saved automatically

Each shape exists in an internal and external variant (external shapes show a small overlay icon). See Shapes and Toolbox Reference for the full availability matrix per diagram type.

Add boundaries

Boundaries group related elements inside a named container, typically representing a Domain in your architecture.

1. Expand the Boundaries section in the Toolbox
2. Choose a boundary type — System Boundary, Container Boundary, or Enterprise Boundary, depending on diagram type
3. Drag the boundary onto the canvas
4. Drop elements inside the boundary, or drag existing elements into it

Boundaries auto-expand as you add more elements, and you can resize one manually by dragging its bottom-right corner handle.

Tip

See Building a Diagram and Organising with Boundaries for the full authoring walkthrough, including moving, nesting, collapsing, and Auto-arrange.

Step 5 — Bind Nodes and Boundaries to Repository Entities

A freshly dropped shape is an unbound placeholder. Binding — Nodinite's entity resolution step in the Designer — connects the shape to a real entity so it shows live names, monitoring health, and navigation.

Bind a node

1. Open the Node Inspector by clicking the node's centre area
2. In the Binding field, click Resolve
3. The Entity Resolver dialog opens — type to search for the entity by name
4. Select the matching System, Service, or Contract from the results list

When UseContracts is enabled, you can replace an existing Service binding with a Contract binding directly from the same Resolve flow.

Bind a boundary

Open the Boundary Inspector by clicking the boundary header. Use the Domain Binding field to search for and select a Domain from your Repository. Once bound, the boundary header shows the Domain name and stays in sync with it automatically.

Tip

See Repository Bindings for the full binding reference, including monitoring state, drill-through links, and article links that appear once a node is bound.

Step 6 — Add Custom Metadata (Optional)

Bound nodes can carry Custom Metadata — key/value attachments used to filter or highlight nodes on the canvas.

1. Open the Node Inspector for a bound node
2. Click the Custom Metadata button — it shows a count badge once metadata is assigned
3. In the Custom Metadata Attachment modal, attach new values, view what is already attached, or remove existing assignments

Custom Metadata attached here also drives the Custom Metadata Filters bar in the Designer, which can dim or spotlight nodes based on their metadata values.

Step 7 — Promote to Active

A newly created diagram starts as Draft. You can iterate — add more nodes, rebind entities, adjust boundaries — without the Draft version appearing as the canonical view.

When the diagram accurately represents the architecture:

1. On the diagram detail page, click Promote to Active
2. Confirm the promotion
3. The diagram moves to Active state and becomes the default view for this type and scope within the set
4. If a previous Active diagram existed for this type and scope, it is automatically moved to Archived

Step 8 — Add More Diagrams to the Set

Return to the Set detail page and repeat Steps 3–7 to build out the full picture:

• Add the L0 System Landscape to show the broader enterprise context
• Add the L1 Context to introduce the central system and its actors
• Add a second L2 Container scoped to a different System (e.g., Portal) — it becomes a sibling alongside the first L2 for ERP
• Add a Dynamic diagram to document a specific runtime workflow
• Add a Deployment diagram to document the infrastructure topology

Each new diagram you add is automatically cross-linked to the others through shared Repository entity bindings.

Checklist

Before publishing your first Architecture Diagram, verify:

• A Diagram Set exists with a descriptive business subject name
• Diagram Set roles are correctly assigned (configured via DefaultRolesInViews or set manually after creation)
• The diagram type matches the view you intend to communicate
• Each L2 Container or L3 Component diagram has a distinct Architecture Scope set
• Every node is bound to a Repository entity — no unbound placeholders remain unless intentional
• Boundaries that represent a business domain are bound to the matching Domain
• Custom Metadata is attached where it helps filtering or highlighting
• The diagram is promoted to Active when ready for stakeholders
• Diagram Set roles are configured for the intended audience using standard role-based security
• If UseContracts is enabled, any contract-bound nodes are reviewed in the designer

Next Steps

• Import Your First C4 Diagram
• Building a Diagram
• Repository Bindings – Linking Shapes to Systems, Services, and Contracts
• Organising with Boundaries
• C4 Designer – Interactive Canvas

Related Topics

• What is C4 Diagrams?
• What is a C4 Diagram Set?
• C4 Designer Overview
• Shapes and Toolbox Reference
• Diagram Lifecycle
• Export and Sharing
• Example C4 Diagrams
• C4 Diagrams Troubleshooting
• C4 Diagrams for business users