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.
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:
- Click Add Diagram Set
- Enter a Name for the set — use a business subject name, not a diagram type (e.g., "Order-to-Cash", "Supplier Onboarding")
- 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.

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.
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.
Check the Level — it is detected from the markup (
C4Contextgives 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
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).

Animated walkthrough: an L2 Container import, with the Scope step (the System Portal) and the boundaries resolved to Domains.Confirm the Diagram Name (taken from the markup's
title), e.g., "ERP Internal Structure"Choose the initial Diagram State. In most cases, start with Draft — a draft diagram lets you iterate safely before it becomes the canonical view.
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, soContainer(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.

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:
- Open the diagram, and click Designer
- 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)
- The diagram is now Active and the default view for this type and scope within the set
- 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
C4Typeset (notNone) - All Services included have a
C4ContainerTypeset - All Services included have a
C4Technologyvalue - 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
- Example C4 Diagrams
- Import – Full Technical Reference
- Creating Your First C4 Diagram
- Sync Diagram Links
- C4 Designer – Interactive Canvas