- 4 minutes to read

Mermaid View

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

Every C4 diagram has a Mermaid View — a read-only rendering of the diagram as valid Mermaid C4 markup. The Mermaid View is independent of the C4 Designer: it reads the same relational rows from the database and produces a portable, embeddable diagram that renders natively in GitHub, Confluence, Azure DevOps, Notion, SharePoint, and any other Mermaid-capable tool.

How It Works

The Mermaid View is powered by the C4MermaidGenerator — a server-side class in the Nodinite Core library. It reads the five C4 diagram tables (C4Diagrams, C4DiagramLanes, C4DiagramActors, C4DiagramServices, C4DiagramConnectors) and emits valid Mermaid C4 syntax.

The generation process follows a deterministic order:

  1. Person actors from C4DiagramActors where Systems.C4Type = Person → emitted as Person(...) entries
  2. External system actors where Systems.C4Type = ExternalSystem → emitted as System_Ext(...) entries
  3. Domain lanes ordered by LaneOrder → each becomes a Boundary(...) block labelled with the Domain name
  4. Services in each lane → emitted as Container(...) blocks using C4ContainerType for the shape and C4Technology as the $techn parameter
  5. Connectors → emitted as Rel(alias, alias, "Label", "Protocol") entries

Because the generator always reads the same rows in the same order, the output is deterministic — the same diagram always produces identical Mermaid markup.

Example Output

The following is an example of Mermaid C4Container markup auto-generated by Nodinite

C4Container title API-Led Architecture (auto-generated from Repository) Person(partnerUser, "Partner", "External partner placing orders") Person(mobileUser, "Mobile User", "Uses the mobile app") Person(webUser, "Web User", "Uses the web portal") Boundary(experienceApis, "Experience APIs") { Container(edi850, "EDI 850", "BizTalk", "Receives purchase orders") Container(mobileApi, "Mobile API", "ASP.NET Core", "Handles mobile requests") } Boundary(processApis, "Process APIs") { Container(outbound, "Outbound", "Logic Apps", "Orchestrates outbound flows") Container(inbound, "Inbound", "Logic Apps", "Processes inbound messages") } Boundary(systemApis, "System APIs") { Container(purchaseOrders, "Purchase Orders", "REST/SQL", "CRUD for PO data") Container(shipments, "Shipments", "REST/SQL", "Manages shipment records") } System_Ext(erp, "ERP", "Handles financial transactions") System_Ext(wms, "WMS", "Manages warehouse and shipments") Rel(partnerUser, edi850, "Sends EDI 850", "AS2/SFTP") Rel(mobileUser, mobileApi, "Uses", "HTTPS") Rel(shipments, wms, "Reads/Writes", "REST")

Alias Generation

Node aliases in the generated Mermaid are stable and collision-free because they are derived from the entity type prefix and database ID:

Entity Alias pattern Example
Service svc_{ServiceId} svc_42
System sys_{SystemId} sys_7
Domain dom_{DomainId} dom_3

This means aliases are identical every time the same diagram is generated, making it safe to reference a specific alias in external documentation or automated tooling.

Diagram Level and Mermaid Type

The C4 level selected in the designer (Context / Container / Component) controls which Mermaid C4 header is emitted:

C4 Level Mermaid output header When to use
Context (L1) C4Context High-level people + systems overview
Container (L2) C4Container Services and technology inside a boundary
Component (L3) C4Component Internal structure of a single service

Pages for the Mermaid View

URL Purpose
/repository/c4diagrams/{id}/view Rendered Mermaid diagram with zoom/pan, shareable URL
/repository/c4diagrams/{id}/mermaid Raw Mermaid markup with copy-to-clipboard button

The /view page uses the existing Mermaid rendering infrastructure already present in Nodinite — the same engine used by the existing "Show in Mermaid" actions throughout the Repository. No new rendering library is required.

The /mermaid page displays the raw markup so it can be pasted directly into external tools such as GitHub README files, Confluence pages, or the Mermaid Live Editor.

Sharing and Embedding

Shareable URL

The /view URL is stable and always reflects current data. Share it with team members, stakeholders, or external partners. Every time the URL is opened, the diagram is freshly generated from the current relational rows — no stale screenshots.

Embedding in External Tools

Because the Mermaid markup is standard C4 Mermaid syntax, it renders natively in:

  • GitHub — paste into a README.md or wiki page inside a ```mermaid ``` block
  • Confluence — use the Mermaid macro or a compatible Confluence app
  • Azure DevOps — wiki pages support Mermaid natively
  • Notion — use the Mermaid code block
  • SharePoint — embed via web part or iFrame
  • Mermaid Live Editor — for quick sharing and editing

Export Endpoint

The headless export endpoint returns the diagram in multiple formats, always reflecting the current state:

Format URL Use case
PNG image /api/repository/c4diagrams/{id}/export.png Embed in Word, PowerPoint, Confluence
SVG vector /api/repository/c4diagrams/{id}/export.svg High-quality print, scalable embedding
Mermaid markup /api/repository/c4diagrams/{id}/export.md Paste into any Mermaid-capable tool
Draw.io XML /api/repository/c4diagrams/{id}/export.drawio Import into draw.io / diagrams.net for manual editing

See Export and Sharing for full details on export formats and automation.

Relationship to the Existing "Show in Mermaid" Feature

The existing "Show in Mermaid" action on individual Repository entities (Integrations, Services, Systems) continues to work unchanged. It provides a quick, read-only fly-by-wire rendering of whatever relationships exist in the live graph at that moment.

The C4 Diagram Mermaid View is a separate, superior capability:

Existing "Show in Mermaid" C4 Diagram Mermaid View
Source of truth Live entity graph traversal Designed diagram rows in DB
Output stability Non-deterministic (changes as graph evolves) Deterministic (same rows → same output)
C4 node types All nodes as <<external_system>> Correct types: Person, System_Ext, Container, etc.
Layout control None (Mermaid auto-layout) Designer-controlled positions
Saves and shares No Yes — shareable URL, export endpoint
Curated content No (renders entire connected graph) Yes (only entities the designer placed on canvas)

Both capabilities are valuable and serve different use cases. Use the existing action for quick ad-hoc exploration; use C4 Diagram Mermaid View for persistent, publishable architecture documentation.

Next Steps