Shapes and Toolbox Reference
The toolbox panel in the C4 Designer is the palette of C4 shapes you use to build or edit C4 Diagrams. Its contents are context-sensitive: the C4 toolbox shows only the shapes that are valid for the active diagram type, so the visible toolbox is always a subset of the full C4 shape vocabulary. Use this page as the lookup reference; for the hands-on workflow, see Building a Diagram.
Animated walkthrough: the same toolbox on a Context, Component, Dynamic, and Container diagram, switched with Navigate. The sections change with the level; the Service filter chip narrows the list, and All brings everything back. It ends on the Container toolbox.
Understanding the Shape Vocabulary
One shape vocabulary covers every way a shape reaches a diagram in Nodinite. A diagram you Import from Mermaid, PlantUML, Structurizr DSL, or Draw.io XML produces the same shape families as one you assemble by hand, and diagrams built in the designer export clean, standards-compliant Mermaid that any C4-aware tool can read.
filtered by diagram type"] --> Canvas["fa:fa-diagram-project Canvas"] Import["fa:fa-file-import Import
Mermaid, PlantUML, Structurizr DSL, Draw.io XML"] --> Canvas Repo["fa:fa-database Repository entity
and its Component Type"] -. binding and icon .-> Canvas Canvas --> Mermaid["fa:fa-code Mermaid source and export"]
The toolbox and the import wizard feed the same canvas; Repository bindings supply the node's entity and icon, and every diagram renders as Mermaid C4 markup.
| 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 import wizard produces the same shapes from external markup |
Example of the toolbox on a Deployment diagram: only Infrastructure Nodes, Containers, Boundaries, and Connectors appear, because those are the shapes valid for that diagram type. The Domain filter chip shows because the Infrastructure Node can bind to a Domain.
Toolbox Filter, Resolver, and Binding Defaults
The toolbox has up to six filter chips: All, System, Domain, Service, Integration, and Contract. A chip only shows when the diagram type has shapes for it: a Context diagram shows All and System, Domain shows on a Deployment diagram (for the Infrastructure Node), and Contract shows only when UseContracts is enabled and you have read rights on Contracts.
The filter chips do not limit the diagram to a single binding target. They only change which repository-centric shape families the toolbox emphasizes. A separate node resolver decides what a selected node can bind to and what its default binding kind is (see Repository Bindings). This holds for every diagram type below, so switching the filter never changes the meaning of a node that is already on the canvas.
| Filter chip | What it emphasizes in the toolbox | What it does not mean |
|---|---|---|
| All | All toolbox sections allowed for the diagram type | It does not force every node to bind to every entity kind |
| System | System-facing shapes, plus the advanced System items valid in the diagram | It does not mean every selected node binds as a System |
| Domain | Deployment items that can bind to a Domain (the Infrastructure Node) | It does not mean the diagram is scoped to a Domain |
| Service | Service-facing container and deployment items | It does not mean the current node is a Service node |
| Integration | Integration-facing component items | It does not mean the node is integration-only in the resolver |
| Contract | Contract-capable items, where contract support is enabled | It does not mean the diagram type is contract-only |
The designer default may prefer Integration, Service, or Contract depending on the node kind and current binding, but the filter chip only changes what the toolbox shows.
Component Type Icons vs Toolbox Icons
Every shape on the canvas displays one of two icons:
- Toolbox default icon: the built-in icon for the shape type, shown in the toolbox and used as the fallback when no Component Type is available.
- Component Type icon: the icon from the Component Type assigned to the bound Repository entity.
When the bound entity has a Component Type, its icon replaces the toolbox default on the canvas. Assign the icon once to a System, Service, Integration, or Domain, and it appears automatically in every C4 diagram that references that entity, in both view mode and the designer.
Important
The entity Component Type always wins. For the full priority chain and fallback rules, see Component Types. The icons listed on this page are the default fallback icons.
The Internal vs External Icon Convention
Every actor and node shape exists in an internal and an external variant. Nodinite marks the difference with an icon overlay on every diagram type, so colour 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 |
| Tier | Internal icon | External icon |
|---|---|---|
| Person | + | |
| Software System | + | |
| Container (generic) | + | |
| Database (any tier) | + | |
| Queue / Stream (any tier) | + | |
| Component | + |
The tables below list the internal icon; the external variant adds the overlay.
Shape Availability by Diagram Type
| Shape | L0 / L1 | L2 | L3 | Dynamic | Deployment |
|---|---|---|---|---|---|
| Person (internal) | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
| Person (external) | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
| Software System | ✅ Yes | ✅ Yes | ✅ Advanced | ✅ Yes | ❌ No |
| Software System (external) | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |
| Database System | ✅ Yes | ✅ Yes | ✅ Advanced | ✅ Yes | ❌ No |
| Database System (external) | ✅ Yes | ✅ Yes | ✅ Advanced | ✅ Yes | ❌ No |
| Queue System | ✅ Yes | ✅ Yes | ✅ Advanced | ✅ Yes | ❌ No |
| Queue System (external) | ✅ Yes | ✅ Yes | ✅ Advanced | ✅ Yes | ❌ No |
| Container (generic or sub-typed) | ❌ No | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| Container (external) | ❌ No | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| Container Instance (+ external) | ❌ No | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
| Container Database (+ external) | ❌ No | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| Container Queue / Stream (+ external) | ❌ No | ✅ Yes | ❌ No | ✅ Yes | ❌ No |
| Component (+ external) | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
| Component Database (+ external) | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
| Component Queue (+ external) | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
| Infrastructure Node | ❌ No | ❌ No | ❌ No | ❌ No | ✅ Yes |
| Container Boundary | ❌ No | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
| System Boundary | ✅ Yes | ✅ Yes | ❌ No | ❌ No | ❌ No |
| Enterprise Boundary | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No |
| Generic Boundary | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
| Deployment Node | ❌ No | ❌ No | ❌ No | ❌ No | ✅ Yes |
| Relationship: solid and async (dashed) | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| Bidirectional ↔ | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
| Numbered Step, Numbered Step (Async), Return / Callback | ❌ No | ❌ No | ❌ No | ✅ Yes | ❌ No |
"Advanced" means the shape sits in the collapsed Advanced section of the L3 toolbox. On L2 the System shapes sit in the External Systems section, internal ones included; on Dynamic they sit in Participants.
Note
In Dynamic diagrams the 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 isn't a primary toolbox shape.
Toolbox Section Order by Diagram Type
| Diagram | Toolbox sections (in order) |
|---|---|
| L0 System Landscape | Persons · Systems · Boundaries (System, Enterprise) · Connectors |
| L1 Context | Persons · Systems · Boundaries (System, Enterprise) · Connectors |
| L2 Container | Persons · Containers · Databases · Queues & Streams · External Systems · External Containers · Boundaries (System, Container) · Connectors |
| L3 Component | Components · External Actors · Advanced ▶ (System shapes, collapsed) · Boundaries (Boundary, Container) · Connectors |
| Dynamic | Participants · Connectors (no Boundaries section) |
| Deployment | Infrastructure Nodes · Containers · Boundaries (Deployment Node) · Connectors (no Persons or System-level section) |
L0 System Landscape and L1 System Context
L0 and L1 use the same Mermaid C4Context declaration and the same toolbox sections, including the System Boundary and Enterprise Boundary. The difference is conceptual: L0 spans your full enterprise landscape; L1 focuses on a single system in its context. All shapes bind to Systems; the System filter maps most directly to the binding model here.
| Shape | Icon | Mermaid macro | C4Type on the bound System |
Notes |
|---|---|---|---|---|
| Person | Person |
Person |
Internal user, analyst, or role | |
| Person (external) | + overlay | Person_Ext |
PersonExt |
External customer, trading partner, or user |
| Software System | System |
InternalSystem |
A system you own and operate | |
| Software System (external) | + overlay | System_Ext |
ExternalSystem |
Third-party, SaaS, or partner system |
| Database System | SystemDb |
SystemDb |
Internal system rendered as a database cylinder | |
| Database System (external) | + overlay | SystemDb_Ext |
SystemDbExt |
External database system |
| Queue System | SystemQueue |
SystemQueue |
Internal message bus or queue at context level | |
| Queue System (external) | + overlay | SystemQueue_Ext |
SystemQueueExt |
External queue, event bus, or stream |
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 Services; platforms, portals, and tools may bind to Systems when that entity better represents the element. The L2 toolbox also offers all six System shapes from L0/L1, internal ones included, in its External Systems section (System, System_Ext, SystemDb, SystemDb_Ext, SystemQueue, SystemQueue_Ext). Its boundaries are the System Boundary and the Container Boundary.
Container Sub-Types
The C4ContainerType values below come from the Service's C4 properties; Repository Properties for C4 Diagramming is the full reference, including numeric values.
| Shape | Icon | Mermaid macro | C4ContainerType |
Example |
|---|---|---|---|---|
| Container (generic) | Container |
None |
Catch-all when no specific sub-type applies | |
| Web Application | Container |
WebApp |
Customer portal, admin UI | |
| Single-Page App | Container |
SinglePageApp |
Single-page application or progressive web 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) | + overlay | Container_Ext |
— | External container inside scope |
| Container Instance | Container_Instance |
— | A specific running replica of a container |
Database, Queue, and Stream 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) | + overlay | ContainerDb_Ext |
— | External database accessed by the system |
| Message Bus / Queue | ContainerQueue |
MessageBus |
Azure Service Bus, RabbitMQ, SQS | |
| Queue | ContainerQueue |
Queue |
Standalone point-to-point queue, decoupled from a bus | |
| Event Stream | ContainerQueue |
EventStream |
Kafka topic, Azure Event Hub | |
| Queue / Stream (external) | + overlay | ContainerQueue_Ext |
— | External queue or stream outside the boundary |
L3 Component Diagram
Component diagrams zoom into a single Service scope and show its internal building blocks. Component nodes bind to Integrations, Services, or Contracts depending on the selected node binding kind and permissions. The designer defaults a component node to Integration; the binding picker also allows Service and Contract.
| Shape | Icon | Mermaid macro | C4ComponentType |
Notes |
|---|---|---|---|---|
| Component | Component |
None |
Generic logical building block | |
| Component (external) | + overlay | Component_Ext |
— (optional binding) | External module or third-party library |
| Component Database | ComponentDb |
Repository |
Data access component | |
| Component Database (external) | + overlay | ComponentDb_Ext |
— (optional binding) | External data store accessed by this component |
| Component Queue | ComponentQueue |
Queue |
Async message consumer or producer | |
| Component Queue (external) | + overlay | ComponentQueue_Ext |
— (optional binding) | External queue or stream |
The External Actors section offers the Person and Software System (external) shapes from L0/L1, placed outside the Container Boundary that encloses the components. The collapsed Advanced section exposes the System-level shapes still valid at L3: System, SystemDb, SystemDb_Ext, SystemQueue, and SystemQueue_Ext. The Boundaries section offers the generic Boundary and the Container Boundary, which wraps the scope Container.
Dynamic Diagram
Dynamic diagrams show the runtime interaction sequence for a specific business workflow. Participants are Person, System, or Container instances (no Component shapes), and connectors carry step numbers that define the execution order. The Dynamic toolbox has no Boundaries section. The filter changes which participant families appear; the step and return connectors give the diagram its shape.
| Shape | Icon | Mermaid macro | Notes |
|---|---|---|---|
| Person | Person |
Internal role in the sequence | |
| Person (external) | + overlay | Person_Ext |
External actor in the sequence |
| Container (any sub-type) | Container |
Participating service; the technology subtitle is optional | |
| Container Database | ContainerDb |
Database participant | |
| Container Queue | ContainerQueue |
Message queue participant | |
| Software System | System |
Internal system in the interaction flow | |
| Software System (external) | + overlay | System_Ext |
External system in the interaction flow |
| Database System (+ external) | SystemDb, SystemDb_Ext |
Database system in the flow | |
| Queue System (+ external) | SystemQueue, SystemQueue_Ext |
Queue or event bus in the flow |
Deployment Diagram
Deployment diagrams show where container instances are physically hosted. The selected node resolves according to the deployment-specific item you place, not through a generic System or Service binding.
| Shape | Icon | Mermaid macro | Notes |
|---|---|---|---|
| Infrastructure Node | InfrastructureNode |
Generic deployment participant | |
| Container Instance | Container_Instance |
Specific running replica; binds to the same Service as its base Container | |
| Container Instance (external) | + overlay | Container_Instance_Ext |
External or managed instance outside the local deployment boundary |
| Deployment Node | Deployment_Node |
Deployment boundary / infrastructure envelope (see Boundaries) |
Boundaries
Boundary shapes group nodes inside a dashed labelled box. They optionally link to a Domain, but a label-only boundary with no Repository anchor is also valid. For adding, binding, collapsing, and nesting boundaries, see Organising with Boundaries.
Important
Boundaries are per-diagram, not global. Placing a Domain inside a boundary in one C4 diagram, or changing its boundary type, nesting, or order, doesn't affect where that Domain appears in any other diagram or in the BPM Designer.
| Boundary shape | Icon | Mermaid macro | Available in | Notes |
|---|---|---|---|---|
| Container Boundary | Container_Boundary |
L2, L3 | Default boundary at L2; the scope Container wrapper at L3 | |
| System Boundary | System_Boundary |
L0/L1, L2 | A single system's boundary within a wider view | |
| Enterprise Boundary | Enterprise_Boundary |
L0/L1 | Outermost organisational wrapper | |
| Generic Boundary | Boundary |
L3 | Custom grouping with a free-text type hint; the toolbox tile is named Boundary | |
| Deployment Node | Deployment_Node |
Deployment | Infrastructure zone; supports unlimited nesting |
Connectors
The toolbox exposes a diagram-specific connector palette. Direction is a property of a placed connector, not a separate shape; set it per flow in Connector Properties after you draw the connector. For drawing, display names, protocols, flows, and the connection rules per diagram type, see Drawing Connectors.
| Shape | Icon | Mermaid output | Available in |
|---|---|---|---|
| Synchronous | Rel(...) |
L0, L1, L2, L3, Deployment | |
| Asynchronous | (dashed badge) | Rel(...) + UpdateRelStyle($lineStyle=dashed) |
L0, L1, L2, L3, Deployment |
| Bidirectional | BiRel(...) |
L0, L1, L2, L3 | |
| Numbered Step | Rel(...) with step prefix |
Dynamic only | |
| Numbered Step (Async) | (dashed badge) | Rel(...) + dashed style with step prefix |
Dynamic only |
| Return / Callback | Rel_Back(...) |
Dynamic only |
Note
Bidirectional vs Rel_Back:
BiReladds arrowheads to both ends of one connector; use it when the relationship is genuinely two-way.Rel_Backreverses 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
| Direction | Mermaid macro | When to use |
|---|---|---|
| Auto (default) | Rel |
The 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; the arrow is reversed visually while FROM/TO stay in their original order |
| Neighbor | Rel_Neighbor |
Places the target adjacent to the source; minimises edge length for tightly coupled pairs |
How Imported Notation Maps to Shapes
The Mermaid macro in each table above is the exact notation the Import wizard reads. The diagram type declaration on the first line (C4Context, C4Container, C4Component, C4Deployment, C4Dynamic) tells the parser which shape tier to expect, and each macro (ContainerDb_Ext, Component_Ext, Rel_Back, …) maps to the shape with that macro on this page. The wizard then matches node names to Repository entities (Container → Services, System and Person → Systems, Component → Integrations) and lets you review conflicts before anything is saved; see Import for the full workflow and the supported syntax per source format.
Macros that aren't in this reference, such as newer Mermaid C4 additions or PlantUML-only variants, are skipped, and the import result header shows the count of skipped directives.