- 13 minutes to read

Shapes and Toolbox Reference

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

The toolbox panel is the palette of shapes available when building or editing a C4 diagram. Its contents are context-sensitive: only shapes that are valid for the active diagram type are shown. Dropping a Container shape into a Component diagram would be a conceptual mistake, so the toolbox prevents it by only offering the right shapes for the right level.

The same shape vocabulary covers three surfaces in Nodinite, all in exact correspondence:

Surface What you do
Toolbox Drag and drop shapes onto the canvas in the designer
Canvas The placed shape renders on the live diagram
Import The same shapes are produced when pasting Mermaid, PlantUML, or Structurizr DSL markup into the import wizard

This means a diagram built by importing external Mermaid markup will produce identical shapes to one assembled by hand — and diagrams built in the designer will export clean, standards-compliant Mermaid that any C4-aware tool can read.

The Internal vs External Icon Convention

Every actor and node shape exists in two variants: internal (something your organisation owns and operates) and external (a third-party, SaaS, partner, or external user). Nodinite distinguishes these consistently across all diagram types using an icon overlay — colour alone is never the only signal.

Variant Icon treatment Canvas colour Mermaid macro pattern
Internal Base icon alone Blue No suffix — Person, Container, Component
External Base icon + overlay at the top-right corner Grey _Ext suffix — Person_Ext, Container_Ext, Component_Ext

The same icon pairing is applied at every tier:

Tier Internal icon External icon
Person / User +
Software System +
Container (generic) +
Database (any tier) +
Queue / Stream (any tier) +
Component +

Shape Availability by Diagram Type

The matrix below shows which shapes are offered in the primary toolbox sections for each diagram type. Use it to find a shape quickly or to confirm what is valid where.

Shape L0 / L1 L2 L3 Dynamic Deployment
Persons
Person (internal) ✅ ✅ ✅ ✅ ❌
Person (external) ✅ ✅ ✅ ✅ ❌
System-Level Shapes
Software System ✅ ❌ ❌ ❌ ❌
Software System (external) ✅ ✅ ✅ ✅ ❌
Database System ✅ ❌ ❌ ❌ ❌
Database System (external) ✅ ✅ ❌ ❌ ❌
Queue System ✅ ❌ ❌ ❌ ❌
Queue System (external) ✅ ✅ ❌ ❌ ❌
Container-Level Shapes
Container (generic or sub-typed) ❌ ✅ ❌ ✅ ✅
Container (external) ❌ ✅ ❌ ❌ ❌
Container Instance ❌ ✅ ❌ ❌ ✅
Container Database ❌ ✅ ❌ ✅ ✅
Container Database (external) ❌ ✅ ❌ ❌ ❌
Container Queue / Stream ❌ ✅ ❌ ✅ ✅
Container Queue (external) ❌ ✅ ❌ ❌ ❌
Component-Level Shapes
Component ❌ ❌ ✅ ❌ ❌
Component (external) ❌ ❌ ✅ ❌ ❌
Component Database ❌ ❌ ✅ ❌ ❌
Component Database (external) ❌ ❌ ✅ ❌ ❌
Component Queue ❌ ❌ ✅ ❌ ❌
Component Queue (external) ❌ ❌ ✅ ❌ ❌
Infrastructure Nodes
Deployment Node ❌ ❌ ❌ ❌ ✅
Cloud Region ❌ ❌ ❌ ❌ ✅
On-Premises Zone ❌ ❌ ❌ ❌ ✅
Boundaries
Container Boundary ❌ ✅ ✅ ❌ ❌
System Boundary ✅ ✅ ❌ ❌ ❌
Enterprise Boundary ✅ ✅ ❌ ❌ ❌
Generic Boundary ✅ ✅ ❌ ❌ ❌
Connectors
Relationship — solid ✅ ✅ ✅ ✅ ✅
Relationship — async (dashed) ✅ ✅ ✅ ✅ ✅
Bidirectional ↔ ✅ ✅ ✅ ❌ ❌

In Dynamic diagrams the standard Relationship shapes gain a step-number badge, and a dedicated Return ← (Rel_Back) connector is added. Bidirectional (BiRel) is accepted on import for Dynamic diagrams but is not exposed as a primary toolbox shape.

L0 System Landscape and L1 System Context

L0 and L1 use the same Mermaid C4Context declaration and identical toolbox sections. The distinction is conceptual: L0 spans your full enterprise landscape; L1 focuses on a single system in its context. The toolbox sections for both are:

Persons → Systems → Connectors

Person Shapes

Shape Icon Mermaid Macro Nodinite Entity Notes
Person Person System — C4Type = Person Internal user, analyst, or role
Person (external) + Person_Ext System — C4Type = PersonExt External customer, trading partner, or user

System Shapes

Shape Icon Mermaid Macro Nodinite Entity Notes
Software System System System — C4Type = InternalSystem A system you own and operate
Software System (external) + System_Ext System — C4Type = ExternalSystem Third-party, SaaS, or partner system
Database System SystemDb System — C4Type = SystemDb Internal system rendered as a database cylinder
Database System (external) + SystemDb_Ext System — C4Type = SystemDbExt External database system
Queue System SystemQueue System — C4Type = SystemQueue Internal message bus or queue at context level
Queue System (external) + SystemQueue_Ext System — C4Type = SystemQueueExt External queue, event bus, or stream

At L0 and L1, all nodes bind to System entities in the Repository. The C4Type property on each System entity controls the shape it renders as — rectangle for a software system, cylinder for a database, stack for a queue.

Boundary Shapes (L0/L1)

Boundaries at L0 and L1 group actors inside a labelled box. They optionally link to a Domain entity, but a label-only boundary with no Repository anchor is equally valid.

Shape Icon Mermaid Macro Notes
System Boundary System_Boundary Marks a single system's scope
Enterprise Boundary Enterprise_Boundary Outermost organisational wrapper
Generic Boundary Boundary Custom grouping with a free-text type hint

L2 Container Diagram

Container diagrams zoom inside a system boundary to show the applications, services, databases, and message buses that implement it. Container nodes bind to Service entities; platforms, portals, and tools may bind to System entities when that entity better represents the architectural element.

The toolbox sections are:

Persons → Containers → Databases → Queues & Streams → External Systems → External Containers → Boundaries → Connectors

Container Sub-Types

Each Container sub-type is stored as the C4ContainerType property on the bound Service. The sub-type determines the icon shown and the shape label in the Properties panel — the Mermaid macro is always Container (or ContainerDb / ContainerQueue for database and queue shapes).

Shape Icon Mermaid Macro C4ContainerType Example
Container (generic) Container None Catch-all; use when no specific sub-type applies
Web Application Container WebApp Customer portal, admin UI, single-page app
Mobile App Container MobileApp iOS app, Android app
REST API / Service Container API Customer API, Order Service, gRPC endpoint
Microservice Container Microservice Shipping service, auth service
Serverless / Function Container Function Azure Function, AWS Lambda, nightly batch
File Store Container FileStore Azure Blob, SFTP folder, NFS mount
Container (external) + Container_Ext — External container inside scope; no C4ContainerType required
Container Instance Container_Instance — A specific running replica of a container; binds to the same Service as its base Container

Database Shapes (L2)

Shape Icon Mermaid Macro C4ContainerType Notes
Database / Datastore ContainerDb Database SQL Server, PostgreSQL, MongoDB, Cosmos DB
Cache / Key-Value Store ContainerDb Cache Redis, Memcached
Database (external) + ContainerDb_Ext — External database accessed by the system

Queue and Stream Shapes (L2)

Shape Icon Mermaid Macro C4ContainerType Notes
Message Bus / Queue ContainerQueue MessageBus Azure Service Bus, RabbitMQ, SQS
Event Stream ContainerQueue EventStream Kafka topic, Azure Event Hub
Queue / Stream (external) + ContainerQueue_Ext — External queue or stream outside the boundary

External System Shapes (L2)

System-level external actors appear outside the boundary at L2. These are the same System entities used at L1, placed here to show what the system depends on or exposes to.

Shape Icon Mermaid Macro Nodinite Entity Notes
Software System (external) + System_Ext System — C4Type = ExternalSystem Third-party or partner system
Database System (external) + SystemDb_Ext System — C4Type = SystemDbExt External database at system tier
Queue System (external) + SystemQueue_Ext System — C4Type = SystemQueueExt External queue or event bus at system tier

Boundary Shapes (L2)

Shape Icon Mermaid Macro Notes
Container Boundary Container_Boundary Default boundary at L2; wraps a set of Containers — this is the primary grouping for Domain swimlanes
System Boundary System_Boundary Single system's boundary within an enterprise view
Enterprise Boundary Enterprise_Boundary Outermost organisational wrapper
Generic Boundary Boundary Custom grouping with a free-text type hint

L3 Component Diagram

Component diagrams zoom into a single Container (Service) and show its internal building blocks. Component nodes bind to Integration entities in the Repository.

The toolbox sections are:

Components → External Actors → Boundaries → Connectors → Advanced (collapsed)

L1-style System shapes (System, SystemDb, SystemQueue and their internal variants) are valid Mermaid at L3 but almost never appropriate. They are available under a collapsed Advanced section in the toolbox rather than the primary palette.

Component Shapes

Shape Icon Mermaid Macro Nodinite Entity Notes
Component Component Integration — C4ComponentType = None Generic logical building block
Component (external) + Component_Ext Integration (optional binding) External module or third-party library
Component Database ComponentDb Integration — C4ComponentType = Repository Data access component; repository pattern
Component Database (external) + ComponentDb_Ext Integration (optional binding) External data store accessed by this component
Component Queue ComponentQueue Integration — C4ComponentType = Queue Async message consumer or producer
Component Queue (external) + ComponentQueue_Ext Integration (optional binding) External queue or stream

Component Sub-Types (C4ComponentType)

When a Component is bound to an Integration entity, C4ComponentType records the component's architectural role within the parent Service:

Role Icon C4ComponentType Description
Generic None Unspecified; catch-all
Controller Controller REST controller, MVC controller, route handler
Service Service Business logic service class
Repository / Data Access Repository Data access layer — drives ComponentDb shape
Queue / Consumer Queue Async message consumer or producer — drives ComponentQueue shape
Mapper Mapper DTO / domain object mapping
Validator Validator Input validation
Gateway Gateway External system adapter or anti-corruption layer
Factory Factory Object creation / factory pattern

External Actor Shapes (L3)

The same Person and Software System (external) shapes from L0/L1 are available at L3, placed outside the Container Boundary that encloses the component hierarchy.

Boundary Shapes (L3)

Shape Icon Mermaid Macro Notes
Container Boundary Container_Boundary Pre-placed as the scope Container; encloses all Component nodes

Dynamic Diagram

Dynamic diagrams show the runtime interaction sequence for a specific business workflow. Participants are Container or Person instances; connectors carry step numbers to define the execution order. There is no Boundaries section in the Dynamic toolbox.

The toolbox sections are:

Participants → Connectors

Participant Shapes (Dynamic)

Shape Icon Mermaid Macro Notes
Person Person Internal role in the sequence
Person (external) + Person_Ext External actor in the sequence
Container (any sub-type) Container Participating service; technology subtitle is optional at this level
Container Database ContainerDb Database participant
Container Queue ContainerQueue Message queue participant
Software System (external) + System_Ext External system in the interaction flow

Connector Shapes (Dynamic)

Shape Icon Mermaid Macro Notes
Numbered Step — solid with step badge Rel with step prefix Standard synchronous call; label carries the step number, e.g., "1. Submit order"
Numbered Step — async dashed with step badge Rel dashed with step prefix Asynchronous or fire-and-forget message delivery
Return ← Rel_Back Response arrow — source and target keep their logical order; direction is reversed visually without swapping the FROM/TO entities in the markup

When you add a connector in Dynamic mode, the Properties panel immediately prompts for the step number, defaulting to one higher than the current highest step in the diagram. The full numbered sequence is preserved through the complete round-trip: import → save → Mermaid export.

Deployment Diagram

Deployment diagrams show where containers are physically hosted — cloud regions, virtual networks, on-premises zones, and servers. There is no Persons section and no System-level section in the Deployment toolbox.

The toolbox sections are:

Infrastructure Nodes → Containers → Connectors

Infrastructure Node Shapes

All three Infrastructure Node variants use the same Deployment_Node Mermaid macro. The visual sub-type (generic, cloud, on-premises) is a designer annotation that controls the icon. Nodes can be nested to any depth — for example, a Cloud Region containing a VNet containing a Subnet containing a Server.

Shape Icon Mermaid Macro Notes
Deployment Node Deployment_Node Generic server, zone, or infrastructure envelope
Cloud Region Deployment_Node Cloud zone, region, or VNet
On-Premises Zone Deployment_Node Physically secured premises or data centre

Container Shapes in Deployment

The same Container, Database, and Queue shapes from L2 are placed inside Deployment Nodes to show which services are hosted where:

Shape Icon Mermaid Macro Notes
Container (any sub-type) Container Hosted application or service
Container Database ContainerDb Hosted database
Container Queue ContainerQueue Hosted queue or message broker
Container Instance Container_Instance A specific running replica; renders as a Container with a multiplicity badge

Direction is especially useful in Deployment diagrams — cross-zone arrows in nested node layouts almost always benefit from an explicit Rel_D (downward) or Rel_R (rightward) direction to avoid crossing infrastructure boundary boxes. Set the direction in the connector Properties panel.

Boundaries

Boundaries group nodes inside a dashed labelled box. They optionally link to a Domain entity, but a label-only boundary with no Repository anchor is also valid — useful for groupings that do not correspond to a Domain entity.

Boundaries are per-diagram, not global. Placing a Domain inside a boundary in one C4 diagram — or changing its boundary type, nesting, or order — does not affect where that Domain appears in any other diagram or in the BPM Designer. All boundary configuration is scoped to the specific diagram.

Boundary Shape Icon Mermaid Macro Available In Notes
Container Boundary Container_Boundary L2, L3 Default boundary at L2; also used at L3 as the scope Container wrapper
System Boundary System_Boundary L0/L1, L2 A single system's boundary within a wider view
Enterprise Boundary Enterprise_Boundary L0/L1, L2 Outermost organisational wrapper
Generic Boundary Boundary L0/L1, L2 Custom grouping with a free-text type hint
Deployment Node / / Deployment_Node Deployment Infrastructure zone; supports unlimited nesting

Connectors

The toolbox exposes at most three connector shapes in any diagram type. Direction is a property of an already-placed connector — not a separate shape — and is set in the connector Properties panel after the connector is drawn.

The Three Toolbox Connector Shapes

Shape Icon Mermaid Output Available In
Relationship — solid Rel(...) All diagram types
Relationship — async (dashed) (dashed) Rel(...) + UpdateRelStyle($lineStyle=dashed) All diagram types
Bidirectional ↔ BiRel(...) L0, L1, L2, L3

Bidirectional vs Rel_Back: These are different tools. BiRel adds arrowheads to both ends of a single connector — use it when the relationship is genuinely two-way (e.g., a service that both sends and receives from a partner). Rel_Back is a directional variant that reverses the rendered arrow but keeps source and target in their logical markup order — use it for response or acknowledgement arrows in Dynamic step sequences.

Connector Direction

After placing a connector, the Properties panel exposes a Direction dropdown. Direction controls how Mermaid's layout engine routes the arrow and is the primary tool for avoiding arrow crossings in dense diagrams.

Direction Mermaid Macro When to use
Auto (default) Rel Layout engine decides; start here for any new connector
Down Rel_D Top-to-bottom hierarchical flow; parent → child calls
Up Rel_U Bottom-to-top callbacks or events bubbling up
Left Rel_L Return path in a left-to-right layout
Right Rel_R Sequential pipeline steps in a left-to-right layout
Back Rel_Back Response or ack — arrow direction reversed visually; FROM/TO entities in markup stay in their original order
Neighbor Rel_Neighbor Layout hint: place target node adjacent to source; minimises edge length for tightly coupled pairs

How Imported Notation Maps to Shapes

The Mermaid macro listed in each table above is the exact notation that the import wizard reads. When you paste markup from an external tool — such as Structurizr, draw.io, a hand-crafted DSL file, or a captured export from another C4 tool — Nodinite processes it as follows:

  1. Parse — Each C4 macro (ContainerDb_Ext, Component_Ext, Rel_Back, etc.) is identified and matched against the shape vocabulary on this page. The diagram type declaration on the first line (C4Context, C4Container, C4Component, C4Deployment, C4Dynamic) tells the parser which shape tier to expect.

  2. Match — Each parsed node name is looked up in your Repository by display name:

    • Container(...) → Services (prefer typed match by C4ContainerType if available)
    • System(...) / Person(...) → Systems
    • Component(...) → Integrations
    • Boundary(...) / Container_Boundary(...) → Domains (optional; a boundary can resolve as label-only)

  3. Review and Resolve — Match results are shown as Matched, NameConflict, or NotFound before anything is saved. You can reassign or skip any node in this step.

  4. Apply — The diagram is created with all nodes, boundaries, connectors, and automatic cross-diagram drill-through links.

Macros not in this reference (for example, newer Mermaid C4 additions or PlantUML-only syntax variants) are skipped, and the count of skipped directives is shown as an informational note in the import result header.

See Import for the complete import workflow, including how to resolve NameConflict and NotFound results.

Toolbox Section Order by Diagram Type

This is the default section order in the toolbox panel for each diagram type. Sections are collapsible; collapsed sections are still accessible but are hidden by default to reduce visual noise for the current diagram context.

Diagram Toolbox Sections (in order)
L0 System Landscape Persons · Systems · Connectors
L1 System Context Persons · Systems · Connectors
L2 Container Persons · Containers · Databases · Queues & Streams · External Systems · External Containers · Boundaries · Connectors
L3 Component Components · External Actors · Boundaries · Connectors · Advanced ▶ (L1 System shapes, collapsed)
Dynamic Participants · Connectors
Deployment Infrastructure Nodes · Containers · Connectors

Next Steps