- 6 minutes to read

What is C4 Diagrams?

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

Understanding the C4 Model

Before exploring how Nodinite implements C4 Diagrams, it is useful to understand what the C4 model is and why it has become the industry standard for communicating software architecture.

The C4 model was created by Simon Brown as a practical way to describe and communicate software systems. Its name comes from the four levels of zoom it defines:

Level Name Audience Shows
L1 Context Everyone — business and technical People, external systems, high-level relationships
L2 Container Technical teams Applications, services, databases, and the technology choices within a system boundary
L3 Component Developers Components inside a specific container
L4 Code Very senior developers UML-style class diagrams

The key insight is that most architectural communication only requires L1 and L2. Detailed L3/L4 diagrams are rarely shared beyond the development team. Nodinite currently delivers L1 (Context) and L2 (Container) — the diagrams that influence stakeholder decisions and drive integration design.

Why the C4 Model Has Won

  • Tool-neutral — the same notation works in Mermaid, PlantUML, Structurizr, Visio, or hand-drawn on a whiteboard
  • Consistent zoom levels — everyone on the team knows exactly what a "Container diagram" means
  • Widely adopted — used by thousands of engineering teams across industries and vendors
  • Embeddable — Mermaid C4 syntax renders natively in GitHub, Confluence, Azure DevOps, Notion, and more

Why C4 Diagrams Matters to Your Organization

Architecture diagrams are critical artifacts for alignment — they help executives understand system scope, guide teams through design decisions, and bridge communication gaps between technical and business stakeholders. However, most diagram tools suffer from the same problem:

Challenge Business Impact
Diagrams go stale Documentation drifts from reality, reducing trust in architectural decisions
No single source of truth Business systems, IT teams, and architects maintain separate diagrams that conflict
Expensive to maintain Teams spend 10-15% of their time keeping diagrams in sync with changes
Hard for non-technical stakeholders Generic boxes with no context make it difficult for executives and product teams to understand scope
Can't show multiple perspectives A single diagram can't show both high-level system context AND technical infrastructure layers

C4 Diagrams in Nodinite solves this by linking diagrams directly to your existing Repository — the system of record for all integration metadata. When a Service is renamed, deployed, or re-architected, every C4 diagram that uses it automatically reflects the change. Stakeholders always see current, accurate information without manual diagram maintenance.

How Nodinite Entities Map to C4 Concepts

The critical insight is that no new top-level Repository entities are needed. The existing Nodinite Repository Model already contains everything the C4 model requires. Only a small number of new typed properties are added to existing entities.

L1: C4 Context → Systems + Connectors

In a C4 Context diagram, you see People (users, roles) and Software Systems placed around a central system boundary. In Nodinite, these are Systems with the new C4Type property:

C4 L1 Element Nodinite Entity C4Type Value Visual
Person / User System Person
Internal Software System System InternalSystem
External Software System System ExternalSystem

Relationships between Persons and Systems are shown as arrows with a Label (describing the interaction, e.g., "Sends orders") and a Protocol (e.g., "REST/HTTPS").

L2: C4 Container → Services in Domain Swimlanes

In a C4 Container diagram, you zoom into the system boundary and see the applications, services, databases, and message buses — and how they communicate. In Nodinite, these are Services grouped into Domain swimlanes:

C4 L2 Element Nodinite Entity New Property Example
Container (REST API) Service C4ContainerType = RestApi Mobile API
Container (Database) Service C4ContainerType = Database Customer DB
Container (Message Bus) Service C4ContainerType = MessageBus Azure Service Bus
Container (Batch Job) Service C4ContainerType = BatchJob Nightly Sync
Boundary / Layer Domain (no new property — ordering is per-diagram) Experience APIs layer
Technology label Service C4Technology string "ASP.NET Core", "PostgreSQL"

The Visual Result

A complete C4 Container diagram produced by Nodinite follows this layered structure:

┌─────────────────────────────────────────────────────────────────────────┐
│  [Person: Partner]   [Person: Mobile User]   [Person: Web User]         │  ← Systems (C4Type=Person)
│         │                    │                       │                  │
├─────────────────────────────────────────────────────────────────────────┤
│ Domain: Experience APIs                                                  │
│   [Service: EDI 850]  [Service: EDI 810]  [Service: Mobile API]   ...  │
├─────────────────────────────────────────────────────────────────────────┤
│ Domain: Process APIs                                                     │
│   [Service: Outbound]  [Service: Inbound]  [Service: PO Tracking] ...  │
├─────────────────────────────────────────────────────────────────────────┤
│ Domain: System APIs                                                      │
│   [Service: Purchase Orders]  [Service: Shipments]  [Service: Invoice] │
├─────────────────────────────────────────────────────────────────────────┤
│  [System: ERP]  [System: WMS]  [System: Bank]  [System: TM]  [EDW]    │  ← Systems (C4Type=ExternalSystem)
└─────────────────────────────────────────────────────────────────────────┘
         ↑ Connection lines with Label and Protocol drawn between nodes

This matches the API-led connectivity pattern used widely in MuleSoft, Azure API Management, and APIM governance documentation — now auto-generated from your live Repository data.

Two Complementary Render Modes

Every C4 diagram has exactly two render modes that share the same underlying relational data:

Mode 1 — Syncfusion Designer (Interactive)

The interactive canvas at /repository/c4diagrams/{id}/design. Uses the same Syncfusion SfDiagramComponent engine that powers the BPM Designer. Users:

  • Drag Services into Domain swimlanes
  • Place System actors above or below the lane stack
  • Draw connectors with labels and protocols
  • Resize lanes and reorder them

Every interaction writes a single targeted row to the database. Nothing is serialized as JSON. The designer is the source of truth for layout.

Mode 2 — Mermaid View (Portable)

The C4MermaidGenerator (server-side, Core library) reads the same relational rows and emits valid C4Container or C4Context Mermaid markup. The output is:

  • Deterministic — same rows always produce the same Mermaid
  • Embeddable — paste into Confluence, GitHub, Azure DevOps, Notion, or any Mermaid-capable tool
  • Exportable — as PNG, SVG, raw .md, or Draw.io XML via the export endpoint

These two modes coexist and complement each other. Neither depends on the other at runtime.

What Makes This Different from Static Tools

Visio / draw.io Enterprise Architect Starlify Nodinite C4 Diagrams
Uses live Repository data ❌ ❌ ⚠️ Partial ✅ Always current
Auto-generates Mermaid C4 ❌ ❌ ❌ ✅
Designer + live Mermaid preview ❌ ❌ ❌ ✅ Split-panel
Relational layout (not JSON blobs) ❌ ❌ ❌ ✅ SQL columns
Connected to monitoring & logging ❌ ❌ ❌ ✅ Right-click node
Zero marginal cost per diagram ❌ ❌ ❌ ✅ Included in Mapify
Industry-standard C4 notation ✅ Manual ✅ Manual ✅ ✅ Auto-generated

Summary

C4 Diagrams in Nodinite is the only architecture visualization tool that:

  1. Reads from a live, CMDB-quality Repository that is already maintained by your integration teams
  2. Produces standard C4 notation without any manual drawing
  3. Stores layouts relationally so they are queryable, auditable, and conflict-safe
  4. Lets you switch instantly between an interactive swimlane designer and a portable Mermaid diagram
  5. Connects architecture documentation directly to operational monitoring and logging

It is not a replacement for your integration tooling — it is the architectural documentation layer that was always missing from it.

Next Steps