- 5 minutes to read

Creating Your First C4 Diagram

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

This guide walks you through creating a complete C4 Container diagram from scratch using existing Repository data. The full workflow takes about 10 minutes once your Repository entities have the correct C4 properties set.

Before You Begin

C4 Diagrams use existing Repository entities — there is no separate data source. Before designing your first diagram, ensure relevant entities have their C4 properties configured.

Step 1 — Set C4 Properties on Systems

Open each System you want to include in your diagram and set the C4Type property:

C4Type value When to use
Person A human user, customer, or staff role (e.g., "Mobile User", "Finance Analyst")
InternalSystem An internal application or platform you own (e.g., ERP hosted on your infrastructure)
ExternalSystem A third-party system, SaaS, or partner system outside your boundary
None Not used in C4 diagrams (default — will not appear in C4 toolbox)

Optionally set:

  • C4PersonRole — A subtitle for Person types (e.g., "Customer", "Administrator")
  • C4PositionHint — Top to place above lanes by default, Bottom to place below

These are global properties on the System entity. They apply across all diagrams.

Step 2 — Set C4 Properties on Services

Open each Service you want to include and set:

Property What to enter Example
C4ContainerType The architectural role of this service RestApi, Database, MessageBus, WebApp, BatchJob
C4Technology The technology stack or platform "ASP.NET Core", "PostgreSQL", "Azure Service Bus"

C4ContainerType drives the icon shown on the canvas node and the correct Mermaid Container(...) label. C4Technology appears as the technology subtitle in the node and in the generated Mermaid markup.

Step 3 — Create a New C4 Diagram

  1. Navigate to Repository → C4 Diagrams
  2. Click New Diagram
  3. Enter a Name (e.g., "API-Led Architecture – Order-to-Cash")
  4. Optionally enter a Description
  5. Select the C4 Level: Context (L1) or Container (L2)
  6. Set IsShared if you want other Repository users to see this diagram
  7. Click Create

The C4 designer opens automatically for the new empty diagram.

Step 4 — Add Domain Swimlanes

The designer canvas starts empty. Add Domain swimlanes to represent your architectural layers:

  1. Click + Add Lane in the lanes toolbar (or right-click the canvas background)
  2. In the Domain picker, select a Domain (e.g., "Experience APIs")
  3. The lane appears as a horizontal swimlane
  4. Repeat for each architectural tier you want to show (e.g., Process APIs, System APIs)
  5. Drag lanes up/down to reorder them — the new order is saved automatically

The Domain picker shows all Domains in the Repository, including empty ones. This lets you document future-state architecture even before Services exist in a Domain.

Step 5 — Place Services into Lanes

  1. Open the Services panel on the left toolbox ()
  2. Search or browse for a Service
  3. Drag the Service into the appropriate Domain swimlane
  4. The Service node appears as a rectangle with its C4ContainerType icon and C4Technology subtitle
  5. Drag the node left/right within the lane to position it at the desired X coordinate

Repeat for all Services you want to include. Services appear in their lane grouped by Domain.

If a Service Is Already in Another Lane

If you drag a Service that is already placed in a different lane in this diagram, you will see:

"Service is already placed in lane within this diagram. It will appear in both lanes."

This is non-blocking — the same Service can intentionally appear in multiple lanes (matching how BPM handles cross-domain services).

Step 6 — Add System Actors

  1. Open the Actors panel on the left toolbox ()
  2. Search or browse for a System
  3. Drag a Person-type System above the lane stack — it appears in the Persons row at the top
  4. Drag an ExternalSystem-type System below the lane stack — it appears in the External Systems row at the bottom
  5. Adjust positions by dragging actors left/right

Systems with C4Type = None can also be dragged onto the canvas. Use the Properties sidebar to set their C4Type if you did not do so in Step 1.

Step 7 — Draw Connectors

  1. Open the Connectors panel on the left toolbox ()
  2. Select a connector type:
    • Solid arrow — synchronous call
    • Double-headed arrow — bidirectional
    • Dashed arrow — asynchronous / event-driven
  3. Click the source node, then click the target node to draw the connector
  4. The Properties sidebar opens automatically — enter:
    • Label: e.g., "Sends purchase order" (appears on the arrow)
    • Protocol: e.g., "REST/HTTPS", "AMQP 1.0", "SFTP" (appears as subtitle)
  5. Click Save in the sidebar

Repeat for all relationships you want to document.

Step 8 — Preview the Mermaid Output

Click Split View () in the toolbar to show the Syncfusion canvas on the left and the live Mermaid C4 preview on the right. The Mermaid output updates automatically as you:

  • Add or remove nodes
  • Move nodes between lanes
  • Add or edit connectors
  • Change C4 types or technology labels

This preview shows exactly what will be emitted by the C4MermaidGenerator when someone accesses the Mermaid View URL or export endpoint.

Step 9 — Share or Export

Once satisfied with your diagram:

  • Share the viewer URL: Copy /repository/c4diagrams/{id}/view and send to stakeholders
  • Copy Mermaid markup: Navigate to /repository/c4diagrams/{id}/mermaid and click Copy
  • Export as PNG: Use the Export dropdown → PNG
  • Export as Draw.io: Use the Export dropdown → Draw.io for diagram.net

See Export and Sharing for full details on embedding options.

Checklist

Before publishing your first C4 diagram, verify:

  • All Systems included have a C4Type set (not None)
  • All Services included have a C4ContainerType set
  • All Services included have a C4Technology value (the Mermaid $techn parameter)
  • All Domain lanes are in the correct order
  • All connectors have a Label and a Protocol value
  • The diagram IsShared flag is set correctly for your audience
  • The Mermaid preview renders correctly in Split View mode

Next Steps