Import

Import brings existing C4 diagrams from Mermaid, PlantUML, Structurizr DSL, or Draw.io XML directly into your Nodinite Repository — mapping every node to the real entities that already live in your system. The import wizard resolves entities, handles conflicts, auto-creates cross-diagram navigation links within the Diagram Set, and asks you to confirm required metadata when the Draw.io source cannot provide it reliably.

Tip

Keep drill-through links current as your set grows. See Sync Diagram Links to rebuild navigation links across the full set at any time.

Understanding the Import Architecture

Import Two-Step Flow

The import pipeline runs as two separate server operations. Both are required; neither alone produces a complete diagram.

Diagram: The import pipeline — validate parses your markup and matches Repository entities, review lets you resolve ambiguities, and apply creates the diagram record along with all cross-diagram navigation links.

How Entity Matching Works

During validation, each element parsed from your markup — every Container(...), System(...), Person(...), and Boundary(...) — is compared against your Nodinite Repository:

Important

Boundaries resolve to Domains only. The import wizard never matches boundaries to Systems, regardless of the markup source. If your Integration Landscape data lives in the Nodinite Repository and you want a full Diagram Set generated from it — including correct System boundaries at L2 — use Generate from Integration Landscape instead. That pipeline derives boundaries from Repository entity IDs directly and does not go through this text import path.

Matching uses both the alias (first positional argument in the C4 macro) and the display name (second positional argument). Both are tried before declaring a NameConflict or NotFound result.

How Auto-Links Are Created

Auto-links are cross-diagram navigation entries — the data that powers drill-through badges. They are created during Apply by comparing the newly imported diagram's Repository bindings against every other diagram in the same Diagram Set:

• For each match on the (RepositoryEntityType, RepositoryEntityId) pair, a cross-diagram link is created between the two diagrams
• Auto-link creation is add-only: existing links are never removed, only missing links are added
• Deduplication prevents the same link from being created twice within a single Apply run

This means the drill-through badge on an L1 Context node pointing to an L2 Container diagram is stored as data in the cross-diagram link table — not embedded as text in any Mermaid markup.

Supported Source Formats

Mermaid C4

Mermaid is the native format. Paste standard Mermaid C4 markup with a top-level diagram type declaration on the first line.

Supported diagram type declarations:

• C4Context
• C4Container
• C4Component
• C4Deployment
• C4Dynamic

Supported macros:

Supported directives:

• title — sets the diagram title
• UpdateLayoutConfig, UpdateRelStyle, UpdateElementStyle — recognized and skipped with a warning (not a parse error)

Warning

Unknown keyword-like macros after the diagram type declaration produce a parse error. Remove any custom macros not in the table above before importing.

PlantUML C4

PlantUML C4 is accepted and normalized automatically before parsing:

1. @startuml and @enduml tags are stripped
2. !include and !pragma lines are removed
3. The diagram type is inferred from !include names (e.g., !include <C4Context> → C4Context)
4. Common layout macros (LAYOUT_WITH_LEGEND, LAYOUT_TOP_DOWN, etc.) are removed
5. Mermaid-equivalent C4 keyword is prepended, then the standard Mermaid parser processes the result

Standard C4-PlantUML macros (Person, System, Container, Boundary, Rel) work as-is after normalization. Non-C4 PlantUML constructs outside this normalization path may fail to parse.

Structurizr DSL

A C4-focused subset of Structurizr DSL is supported:

• workspace, model, and views blocks
• person and person_ext
• softwareSystem
• container
• Relationships declared as src -> tgt "Label" "Technology"
• view declarations — used to infer the diagram type

Tip

The Structurizr parser covers typical system and container model definitions. Custom DSL constructs specific to Structurizr, including themes, documentation embeds, and styling, are ignored or left uninterpreted.

Draw.io XML

Draw.io XML from draw.io / diagrams.net is supported as an import source. The importer reads labels, shapes, boundaries, and connectors from the XML and feeds them into the same validation and entity-resolution flow used for the text-based formats.

Important

Draw.io is a general-purpose diagram format, not a C4-specific language. The importer can extract structure from the canvas, but it cannot reliably infer all Nodinite metadata from the XML alone.

Before continuing from the Draw.io XML tab, review and confirm these fields:

Warning

Treat Draw.io import as a structured starting point, not a lossless semantic import. Always review the suggested metadata and entity matches before Apply.

Validate: Parse, Match, and Preview

The Validate step parses your markup without creating any database records. It is safe to run multiple times — validate, inspect, adjust your markup, and validate again until the preview matches your expectations.

Validate returns:

• Parsed diagram model — all nodes, boundaries, and connectors extracted from your markup
• Entity matches — for each node: Matched, NameConflict, or NotFound with the suggested Repository entity
• Mermaid preview — a rendered preview. For PlantUML and Structurizr DSL sources this shows the normalized Mermaid output the server produced, making it easy to spot translation issues before committing to Apply
• Parse warnings — skipped directives and unrecognized but non-fatal constructs
• Parse errors — fatal issues with line and column number (Mermaid parse exceptions)

Review and Resolve

After validation, the Review and Resolve table lists every node parsed from your markup. Rows auto-matched with high confidence are pre-filled — you confirm or override. Rows with conflicts or unresolved names require a deliberate choice.

When the source is Draw.io XML, the wizard first asks you to confirm the diagram metadata. A detected name is only a suggestion; the correct Level / Diagram Type and Diagram State must be selected explicitly before you continue to entity resolution.

Match Statuses

Resolution Choices

For each row in the table, you choose one of the following:

Note

External (_Ext) elements are automatically assigned External status. Container_Ext, ContainerDb_Ext, ContainerQueue_Ext, Component_Ext, ComponentDb_Ext, and ComponentQueue_Ext nodes appear with a grey External badge and an "Unbound placeholder" note in the Action column. No manual resolution is required, and they do not block the Apply button. These nodes are stored without a Repository binding and can be linked to an Integration or Service later in the C4 Designer.

Optional overrides per row (available for any row):

• Target display name
• Component type or icon
• Container type and technology
• System type (useful for container-as-system cases)
• Description and C4 actor attributes

Note

Rows that are auto-matched and left unchanged are not sent as explicit conflict resolutions — the server applies the auto-match result directly. Only rows where you made an override or resolved a conflict are included as explicit modifications in the Apply request.

Apply: Create Diagram and Build Links

When you confirm the Review and Resolve table and click Import, the Apply operation creates the complete diagram in a single transaction:

1. Creates the diagram record with the selected type, scope, and name
2. Creates all boundary records (linked to Domains where matched, label-only otherwise)
3. Creates all node records bound to the resolved Repository entities
4. Creates all connector records in the original sequence from the parsed markup
5. Creates cross-diagram links by comparing Repository bindings against all other diagrams in the same Diagram Set

The newly created diagram opens immediately in Draft state. Promote it to Active when you are satisfied with the resolved entity names and the Mermaid preview.

Important

Step 5 — auto-link creation — only runs when the diagram belongs to a Diagram Set (C4DiagramSetId > 0). Always select a set during import to get drill-through links automatically. [!TIP] Links not appearing after import? Import auto-links only evaluate diagrams present at Apply time. Use Sync Diagram Links to rebuild cross-diagram links across the full set after adding further diagrams.

Practical Authoring Guidelines

• Include a valid diagram type declaration — every Mermaid import must begin with C4Context, C4Container, C4Component, C4Deployment, or C4Dynamic. A missing declaration causes a parse error.
• Keep aliases unique and stable — relationships in C4 markup are alias-based. If two nodes share an alias, relationship resolution fails. Stable aliases also make it easier to reference nodes when re-importing revised markup.
• For Draw.io XML — confirm the Diagram Name, Level, and Diagram State manually before continuing. If the XML contains a name, treat it as a suggestion rather than ground truth.
• Set C4ContainerType on Services before importing — the import wizard matches by name, but correct container types make auto-matching more confident and produce the right icons in the generated Mermaid output.
• Use Validate before Apply — the Validate step is free and does not write to the database. Use it to inspect match counts, review warnings, and confirm the Mermaid preview before committing.
• Always select a Diagram Set — Apply requires a C4DiagramSetId > 0 to be selected. Auto-link creation depends on set membership to find sibling diagrams.
• For PlantUML — keep to C4-PlantUML style macros and !include directives. Non-C4 PlantUML constructs outside the normalization path are not supported.
• For Structurizr DSL — keep to core workspace, model, views, person, softwareSystem, container, and relationship constructs.
• After adding or editing diagrams — run Sync Diagram Links on the Diagram Set to ensure all cross-diagram links are complete.

Next Steps

• Sync Diagram Links – Rebuild Navigation in C4 Diagram Sets
• Generate from Integration Landscape – Create a Diagram Set from IL Data
• Creating Your First C4 Diagram
• Mermaid View – Read-Only Rendering
• Export and Sharing
• Repository Properties for C4 Diagramming

Related Topics

• Architecture Diagrams Overview
• What is C4 Diagrams?
• C4 Designer – Interactive Canvas
• Example C4 Diagrams