- 8 minutes to read

Creating Your First C4 Diagram

This guide walks you through creating your first complete C4 diagram using the import workflow — the primary way to create diagrams in Nodinite. Import supports Mermaid, PlantUML, Structurizr DSL, and Draw.io XML. If you already have a diagram in one of these formats, you can be up and running in about 10 minutes.

If you do not yet have importable source, the Example C4 Diagrams page has ready-to-copy Mermaid examples for every diagram type.

Before You Begin

Architecture Diagrams build on your existing Repository data. A small set of properties on Systems and Services control how nodes are recognized during import and how they render in diagrams.

C4 Properties on Systems

Open each System you want to include and verify its C4Type property:

C4Type value When to use
Person A human user, customer, or staff role (e.g., "Mobile User", "Finance Analyst")
InternalSystem An internal application or platform you own
ExternalSystem A third-party system, SaaS, or partner system outside your boundary
None Not intended for C4 diagrams (default — will not appear in dropdown searches during import)

Where to set it: Repository → Systems → edit a System → C4 tab → C4 Type field.

C4 Properties on Services

Open each Service you want to include and set:

Property What to enter Example
C4ContainerType The architectural role of this service RestApi, Database, MessageBus, WebApp, BatchJob
C4Technology The technology stack or platform "ASP.NET Core", "PostgreSQL", "Azure Service Bus"

C4ContainerType drives the icon on the diagram node and the correct Mermaid element type (Container, ContainerDb, ContainerQueue). C4Technology appears as the technology subtitle in the node and in the generated Mermaid markup.

Tip

These properties make the import resolution smarter — entities with matching names and correct types are auto-matched with higher confidence.

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, the Mapify module may not be enabled for your environment. 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.

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.

Step 3 — Import Your First Diagram

On the Set detail page, click Import Diagram.

  1. Select the source tab that matches your input:

    • Mermaid Markup
    • Structurizr DSL
    • PlantUML
    • Draw.io XML

  2. Select the diagram type — choose the type that matches the diagram you want to create:

    • L0 System Landscape
    • L1 Context
    • L2 Container
    • L3 Component
    • Dynamic
    • Deployment

  3. If you selected L2 Container or L3 Component, you are also asked for the 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

  4. Enter or confirm a Name for the diagram (e.g., "ERP Internal Structure")

  5. Choose the initial Diagram State. In most cases, start with Draft.

  6. Paste your source markup or XML into the editor.

  7. Click Next — Resolve Entities

Tip

Draw.io XML can provide structure and labels, but it does not reliably describe the diagram's C4 level. If the importer finds a name in the XML, treat it as a suggestion only. Always review the Diagram Name, Level, and Diagram State before continuing.

Step 4 — Resolve Entities in the Import Wizard

The import wizard parses every element in your source and presents a resolution table. For Draw.io XML, this step begins after you confirm the required metadata fields. For each element it found — systems, containers, people, boundaries, and other mapped shapes — you see:

Column What it shows
C4 Element The element type from your Mermaid source (Container, System_Ext, Person, etc.)
Name in Source The display name extracted from your source
Suggested Match The Repository entity Nodinite thinks this is — shown as a confidence badge
Resolution Your choice for this element

Resolution Options

For each row, you choose one of:

  • Use existing Service — bind this node to a specific Service in your Repository
  • Use existing System — bind this node to a specific System in your Repository
  • Create new Service — create a new Service in the Repository during import
  • Create new System — create a new System in the Repository during import
  • Keep as placeholder — include the node without a Repository binding (useful for external or out-of-scope elements)

Important

The wizard performs a two-pass search: it first looks for a matching Service name, then looks for a matching System name. A Container(portal, "Portal", ...) node may be suggested as matching either the "Portal" Service or the "Portal" System — you choose the correct one for your context.

In the current iteration, import matching remains System/Service-based. If UseContracts is enabled, you can replace a service binding with a Contract after import from the designer's Resolve flow.

Resolving Boundaries

For each Boundary(...) block, the wizard similarly asks whether to link it to an existing Domain or keep it as a label-only boundary. Linking to a Domain lets the boundary appear in the Integration Landscape as a connected node.

Review every row, confirm or override the suggestions, then click Import.

Step 5 — Review the Imported Diagram

After import, Nodinite creates the diagram in Draft state and opens the diagram viewer. You see:

  • The rendered Mermaid C4 view of your diagram
  • Node names pulled from the matched Repository entities (not the raw Mermaid text — the live entity name)
  • A Set breadcrumb at the top linking back to the Diagram Set

Check Entity Names

Because nodes are bound to Repository entities, their names in the diagram always reflect the current entity name. If a Service was recently renamed, the diagram shows the new name automatically — you do not need to re-import.

Check Drill-Through Badges

If another diagram in the same set references the same Repository entity as a node in this diagram, a drill-through badge appears on that node. Click it to navigate to the linked diagram.

For example: if you already imported an L1 Context diagram that contains the "ERP" System, and you now import an L2 Container diagram scoped to ERP, the L1's ERP node automatically gets a drill-through badge pointing at your new L2.

Step 6 — Promote to Active

A newly imported diagram starts as Draft. You can iterate — re-import with corrected markup, adjust, or add notes — 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 7 — Add More Diagrams to the Set

Return to the Set detail page. Import additional diagram types for the same subject to build out the full picture:

  • Import the L0 System Landscape to show the broader enterprise context
  • Import the L1 Context to introduce the central system and its actors
  • Import a second L2 Container scoped to a different System (e.g., Portal) — it becomes a sibling alongside the first L2 for ERP
  • Import a Dynamic diagram to document a specific runtime workflow
  • Import 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
  • All Systems included have a C4Type set (not None)
  • All Services included have a C4ContainerType set
  • All Services included have a C4Technology value
  • For Draw.io imports, the Diagram Name, Level, and Diagram State were reviewed manually
  • Each L2 Container diagram has a distinct Scope System set
  • Entity resolution is complete — no unresolved items remain as placeholders unless intentional
  • The Mermaid preview renders correctly in the viewer
  • The diagram is promoted to Active when ready for stakeholders
  • The IsShared flag is set correctly on diagrams meant for all Repository users
  • If UseContracts is enabled, any contract-bound nodes are reviewed in the designer

Next Steps