Import

C4 Diagrams is part of experimental builds. To access this capability, contact your sales representative.

Import brings existing C4 diagrams from Mermaid, PlantUML, or Structurizr DSL 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, and auto-creates cross-diagram navigation links within the Diagram Set.

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:

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)

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

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

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.

Match Statuses

Resolution Choices

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

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

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.

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.

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.
• 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
• 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
• Mapify