- 11 minutes to read

Import Your First C4 Diagram

This getting started guide walks you through how to import a C4 diagram from existing markup — the fastest way to get a diagram into Nodinite if you already have one. 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.

Tip

Don't have source markup yet? The Example C4 Diagrams page has ready-to-copy Mermaid examples for every diagram type. Prefer to build a diagram by hand instead of importing? See Creating Your First C4 Diagram.

Understanding the Import Flow

An import turns existing markup into a Draft diagram inside a C4 Diagram Set. The import wizard resolves every element against your Repository Model, so the diagram shows live entity names instead of raw text.

graph LR Src["fa:fa-file-code Source markup
Mermaid / PlantUML / Structurizr / Draw.io"] Wiz["fa:fa-wand-magic-sparkles Import wizard
Type, Scope, Name"] Res["fa:fa-magnifying-glass Resolve entities
System / Service / Domain"] Draft["fa:fa-pen Draft diagram"] Active["fa:fa-circle-check Active diagram"] Src --> Wiz Wiz --> Res Res --> Draft Draft --> Active style Src fill:#2678BD style Wiz fill:#2678BD style Res fill:#E47528 style Draft fill:#FFD525 style Active fill:#93d16d

Diagram: Source markup (blue) passes through the import wizard (blue) and entity resolution (orange) into a Draft diagram (yellow), which you promote to Active (green) when it is ready.

Stage What happens
Source markup Mermaid, PlantUML, Structurizr DSL, or Draw.io XML that describes the diagram
Import wizard You pick the diagram type, the Architecture Scope (L2/L3), a name, and the initial state
Entity resolution Each element is matched to an existing System, Service, Integration, or Domain, created new, or kept unbound
Draft The imported diagram, safe to iterate on before it becomes the canonical view
Active The default view for its type and scope within the set (Diagram Lifecycle); needs an Architecture Scope

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 No C4 shape set (default). The import still matches the System by its exact name, and shows ⚠ when its C4 Type doesn't fit the markup

Where to set it: Repository → Systems → edit a System → C4 Properties card → C4 Type.

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 API, Database, MessageBus, WebApp, Function (see all 13 values)
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 — Get to a Diagram Set

In the Nodinite left navigation, open Repository → Diagram Sets (under the Architecture Diagrams heading). If you already have a Diagram Set for this subject, open it and skip to Step 2.

Otherwise, create one first:

  1. Click Add Diagram Set
  2. Enter a Name for the set — use a business subject name, not a diagram type (e.g., "Order-to-Cash", "Supplier Onboarding")
  3. Click Create

Note

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

See Creating Your First C4 Diagram for the full set-creation walkthrough, including roles, Scope System, and Layered Mode versus Free Draw guidance.

Step 2 — Import Your First Diagram

You stay on the Diagram Sets list after creating a set; click the set to open it. On the set page, click Import (see Import for every part of the wizard). The wizard runs in that set; its header shows the set's name and the step.

Diagram Set page with Import clicked, the L1 Context example from the Order-to-Cash examples pasted as Mermaid Markup with its preview, Diagram Name, Level Context and Diagram State Draft, then Review and Resolve with Portal and ERP matched to Systems, Customer resolved as Create new, Resolve All, Import, and the imported Draft opened with Portal and ERP bound to their Systems, animated walkthrough (7.12)
Animated walkthrough of Steps 2 and 3: the Order-to-Cash L1 Context example imported. Portal and ERP match existing Systems, Customer is created on import, and Resolve All takes the defaults for the other new rows.

  1. Select the source tab that matches your input, then Paste the markup or Upload File:

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

    A live Preview shows the markup as you paste it.

  2. Check the Level — it is detected from the markup (C4Context gives Context, so choose System Landscape yourself when that is what you import). The levels are:

    • L0 System Landscape
    • L1 Context
    • L2 Container
    • L3 Component
    • Dynamic
    • Deployment
  3. For L2 Container or L3 Component, the wizard adds a Scope step for 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

    Search by name; Used in diagrams lists where each candidate already appears. Use picks the candidate and continues, and Skip goes on without a scope. Dynamic and Deployment get an optional Scope step; L0 and L1 get none.

    Scope is not cosmetic. It creates the drill-through from the diagrams that show the scoped item, and a diagram needs a scope before it can be promoted to Active; see Diagram Set Fundamentals. An L1 Context needs a scope (a System or a Domain) before it can be promoted too: set it after the import with Set Architectural Scope (Step 5).

    Import of the Order-to-Cash L2 Container example: the Scope step with a search for Portal and Use on the System Portal, then Review and Resolve with the Domain boundaries Sales, Planning, Logistics and Finance matched to Domains and the enterprise boundary created as a Domain, Resolve All, Import, and the L2 Container Draft scoped to the System Portal, animated walkthrough (7.12)
    Animated walkthrough: an L2 Container import, with the Scope step (the System Portal) and the boundaries resolved to Domains.

  4. Confirm the Diagram Name (taken from the markup's title), e.g., "ERP Internal Structure"

  5. Choose the initial Diagram State. In most cases, start with Draft — a draft diagram lets you iterate safely before it becomes the canonical view.

  6. Click Next to validate the markup and match its nodes against the Repository

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 3 — Review & Resolve

The Review & Resolve step lists every element the wizard parsed from your source — systems, containers, people, boundaries, and other mapped shapes — one row each. Badges at the top count the rows that are matched, conflicts to resolve, will be created, and relationships; a New row counts as a conflict until you resolve it. Resolve All accepts every proposal, so new rows are created.

Resolution Options

Each row shows Matched (with a check mark) when the wizard found the Repository entity, or New when it didn't:

  • Resolve ▾ (on New rows) — opens the Resolve dialog with two choices, and the buttons Confirm, Confirm and close, and Cancel:
    • Use existing — bind this node to an entity already in your Repository
    • Create new — create the entity in the Repository during import. The row's Kind decides the type: Person and System elements become Systems (a Person is a System with the C4 Type Person), Containers become Services (or Systems, by choice), Components become Integrations, and boundaries become Domains
  • Unlink (on Matched rows) — include the node without a Repository binding (useful for external or out-of-scope elements)

Important

The wizard matches by exact name, ignoring case, and the node's shape decides the order: a Container(...) tries Services first, then Systems, so Container(portal, "Portal", ...) binds to the "Portal" Service when both exist. Use Matched → Use existing System to bind it to the System instead. The full order per shape is in How Entity Matching Works.

Contracts are matched too: a node whose alias is contract_{id} binds to that Contract, and with UseContracts on, the Resolve dialog has a Use existing Contract tab. See C4 Troubleshooting for the common matching fixes.

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 (Mapify) as a connected node.

Review every row, confirm or override the suggestions, then click Import. With rows still open, the wizard asks Import with unresolved entries? and imports those nodes unbound.

Step 4 — Review the Imported Diagram

After Import, the wizard closes on the set page with Import successful. The new Draft diagram is in the set's list; it does not open by itself. Click it to open 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 is scoped to the Repository entity a node in this diagram is bound to, a drill-through badge with a count appears on that node. Click it to open the linked diagram, or to choose one when there are several. View in a node's menu opens the bound item's own page.

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 5 — 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.

The imported L1 Context Draft: Portal showing the name of its bound System and its drill-through badge to the L2 Container, the banner Architectural Scope required before promotion, Set Architectural Scope with the System Portal saved, Designer opened, Promote to Active with the message Diagram promoted to Active, and the set's list with the L1 Context Active, animated walkthrough (7.12)
Animated walkthrough of Steps 4 and 5: the entity name and drill-through badge checked, the missing scope set, and the L1 Context promoted to Active in the Designer.

A diagram needs an Architecture Scope and at least one element before it can be promoted; the Promote to Active button's tooltip says which is missing. When the scope is missing, the diagram shows Architectural Scope required before promotion with Set Architectural Scope.

When the diagram accurately represents the architecture:

  1. Open the diagram, and click Designer
  2. Click Promote to Active. There is no confirmation: the diagram is promoted at once (Diagram promoted to Active.) and becomes read-only (Create a Draft to make changes)
  3. The diagram is now Active and the default view for this type and scope within the set
  4. If a previous Active diagram existed for this type, scope, and mode, it is automatically moved to Archived

Promotion is only in the Designer; Edit Properties can't promote a Draft.

Step 6 — Import More Diagrams into 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. If links do not appear after importing, use Sync Diagram Links to rebuild navigation across the full set.

Checklist

Before publishing your first imported 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 or L3 Component diagram has a distinct Scope System or Service set
  • Each L1 Context, Dynamic, and Deployment diagram has a scope set before you promote it (Set Architectural Scope)
  • 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
  • If UseContracts is enabled, any contract-bound nodes are reviewed in the designer

Next Steps