- 7 minutes to read

What is C4 Diagrams?

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 delivers L1 (Context), L2 (Container), and L3 (Component) — covering the full range from executive-level overview to developer-level module documentation.

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.

The same Architecture Diagrams capability also supports grouped Log View runtime inspection. That gives teams an investigation-first view of related events without forcing them to save a curated diagram first.

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 or Systems

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, Container nodes can bind to either Services or Systems depending on what best represents the architectural element:

C4 L2 Element Nodinite Entity Property Example
Container (REST API) Service C4ContainerType = API Mobile API
Container (Database) Service C4ContainerType = Database Customer DB
Container (Message Bus) Service C4ContainerType = MessageBus Azure Service Bus
Container (Batch Job) Service C4ContainerType = Function Nightly Sync
Container (platform / portal / tool) System C4Type existing value Portal, ERP core, CRM platform
Boundary / Layer Domain (optional) Link during import wizard — DomainId is nullable Experience APIs layer
Technology label Service or System C4Technology string "ASP.NET Core", "PostgreSQL"

A Container node can bind to a System. This is the key fix enabling platforms, portals, and tools — which are better represented as Systems in the Repository — to appear correctly in L2 diagrams without forcing duplication as Services. The C4ElementKind property on the node controls the rendering shape independently of the entity type binding.

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.

Diagram Sets and How Diagrams Are Generated

Every C4 diagram belongs to a Diagram Set — the primary organizing unit in Architecture Diagrams. A Set groups all architectural views for one subject (L0 Landscape, L1 Context, multiple L2 Containers, L3 Component views, Dynamic, and Deployment) into a single navigable collection.

Diagram Sets

All diagrams in a set share entity bindings. When an L1 Context diagram and an L2 Container diagram in the same set both reference the same Repository entity, Nodinite automatically creates a drill-through link between them. The L1 node shows a badge; clicking it navigates directly to the L2.

This is the key benefit of Sets: you write a Person(user, "Mobile User") once, bind it to the "Mobile User" System in the Repository, and the binding is shared across every diagram in the set that includes that entity.

How Diagrams Are Generated

Architecture Diagrams uses the C4MermaidGenerator — a server-side component that reads relational diagram data and emits valid Mermaid C4 markup. The output is:

  • Deterministic — same data always produces the same Mermaid, in the same order
  • 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

The C4 Designer is now part of the Architecture Diagrams workflow. Many teams still start with the import-first path because it is the fastest way to bootstrap a diagram from Mermaid or Draw.io, then switch to the designer to refine layout, manage boundaries, and maintain connector message members without cluttering the canvas.

Runtime inspection from grouped Log Views

Architecture Diagrams is not only for saved documentation. A grouped Log View can also open an on-demand runtime diagram based on related events.

This complements authored Dynamic diagrams:

  • the grouped Log View runtime diagram is investigation-first and can switch between Participants mode and Systems mode
  • the authored Dynamic diagram remains a curated architecture artifact inside a Diagram Set
  • when UseContracts=true, grouped runtime can classify a single resolved Contract as the participant and use contract ownership for Systems-mode placement

Learn how grouped runtime inspection works ->

What Makes This Different from Static Tools

Visio / draw.io Enterprise Architect Starlify Nodinite Architecture Diagrams
Uses live Repository data ❌ ❌ ⚠️ Partial ✅ Always current
Diagram Sets with drill-through ❌ ❌ ⚠️ Partial ✅
Multiple L2 diagrams per subject ❌ ❌ ⚠️ ✅ Per-set scoping
Import from existing Mermaid ❌ ❌ ❌ ✅ Import wizard
Auto-generates Mermaid C4 ❌ ❌ ❌ ✅
Container node binds to System OR Service ❌ ❌ ❌ ✅
Connected to monitoring & logging ❌ ❌ ❌ ✅
Zero marginal cost per diagram ❌ ❌ ❌ ✅ Included with the Mapify module
Industry-standard C4 notation ✅ Manual ✅ Manual ✅ ✅ Auto-generated
Interactive visual designer ✅ ✅ ✅ ✅

Summary

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

  1. Organizes all views for one subject in a Diagram Set with automatic drill-through navigation between levels
  2. Reads from a live, CMDB-quality Repository that is already maintained by your integration teams
  3. Produces standard C4 notation from imported or visually designed diagrams
  4. Binds Container nodes to either Services or Systems and, when UseContracts is enabled in runtime/designer paths, supports first-class Contract participants
  5. Stores all relationships relationally — including connector message members — so they are queryable, auditable, and conflict-safe
  6. 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