Building a Diagram
The Toolbox is the heart of the C4 Designer. It gives you everything you need to populate a diagram: element shapes, boundary containers, and connector types. You drag from the Toolbox and drop onto the canvas — the Designer handles the rest.
The Toolbox is only visible when the diagram is in Draft state. Open an Active diagram in read-only mode and you will not see the Toolbox. Click Create Draft in the toolbar to begin editing.
Understanding the Toolbox
The Toolbox panel sits on the left side of the Designer. It contains three collapsible sections:
| Section | Contents |
|---|---|
| Elements | Shapes for every C4 element type — Persons, Software Systems, Containers, Components, and Infrastructure Nodes |
| Boundaries | System, Container, and Enterprise boundary containers |
| Connectors | Relationship and Dependency connection types |
Each tile in the Toolbox shows the shape's icon and name. The available tiles depend on the diagram type (L1 Context, L2 Container, L3 Component, etc.) — only shapes that make sense for the current level are shown. See Shapes and Toolbox Reference for the full availability matrix.
Collapsing the Toolbox
Click the toggle button at the top of the Toolbox to collapse it to a narrow strip. This gives the canvas more horizontal space. Click again to expand it.
Adding Elements to the Canvas
Step 1 — Find the right shape
Expand the Elements section in the Toolbox. The shapes are grouped by C4 tier:
- Persons — human actors (internal user, external user)
- Software Systems — system-level black boxes (internal and external variants)
- Containers — runtime deployable units such as APIs, databases, queues, and web apps
- Components — code modules inside a container
- Infrastructure Nodes — cloud regions, deployment zones, and server instances (Deployment diagrams only)
Each shape exists in an internal and external variant. External variants show a overlay icon in the top-right corner. See Shapes and Toolbox Reference for the full convention.
Step 2 — Drag onto the canvas
Click and hold a Toolbox tile, then drag it onto the canvas. Release the mouse button to drop the shape at that position.
The shape is created at the drop coordinates and saved automatically.
Step 3 — Bind to a Repository entity
A newly dropped shape is an unbound placeholder. To connect it to a real Service or System in your Repository, open the element's inspector by clicking it and use the Resolve button to search and bind. See Repository Bindings for the full workflow.
Adding Boundaries
Boundaries group related elements inside a named container, typically representing a Domain in your architecture.
- Expand the Boundaries section in the Toolbox
- Choose a boundary type:
- System Boundary — wraps a Software System and its containers
- Container Boundary — wraps components inside a Container
- Enterprise Boundary — a top-level organisational grouping
- Drag the boundary onto the canvas
- Drop elements inside the boundary, or drag existing elements into it
Boundaries auto-expand as you add more elements. You can also resize a boundary manually by dragging its bottom-right corner handle.
Boundaries can be bound to Domains in your Repository. Open the Boundary Inspector by clicking the boundary header and use the Domain Binding field. See Organising with Boundaries for details.
Moving Elements
Moving a node
Click and drag any element on the canvas to reposition it. Connectors update in real-time as you drag. When you release the mouse button, the position is saved automatically.
If you drag a node over a boundary, it adopts that boundary as its parent (reparenting). The boundary that most tightly contains the node's centre is the one chosen. See Organising with Boundaries.
Moving a boundary
Click and drag the boundary header to move the entire boundary and all of its contained elements together. The relative positions of elements inside the boundary are preserved.
Keyboard movement
Select a node or boundary and use the Arrow keys to nudge it by 1 pixel, or Shift + Arrow for 10-pixel steps. See Keyboard Shortcuts.
Auto-Arrange
The Auto-arrange button in the toolbar runs a server-side layout algorithm that automatically positions all elements in a tidy grid. It is useful when:
- You have just imported a diagram and the layout is cluttered
- You want a clean starting point before manual refinement
When you click Auto-arrange, an inline confirmation panel appears:
"Consider creating a copy before auto-arranging"
Click Auto-arrange to proceed, or Cancel to return to your current layout. This prompt exists because auto-arranging overwrites all manual positions and cannot be undone.
Auto-arrange requires the Mapify feature flag. If the button is not visible in the toolbar, the feature is not enabled for your installation.
Frequently Asked Questions
The Toolbox is not visible
The Toolbox is hidden when the diagram is Active (read-only). Click Create Draft in the toolbar to switch to edit mode, which makes the Toolbox appear.
I dropped an element in the wrong place
Simply drag it to the correct position. The new position saves automatically on release.
Can I add the same shape multiple times?
Yes. Drag the same Toolbox tile multiple times to create multiple instances of a shape. Each instance becomes a separate node that can be independently bound and positioned.
Should I bind nodes immediately or finish layout first?
Either approach works. Many users prefer to sketch the full layout first (adding and positioning all unbound shapes), then bind each shape to a Repository entity in a second pass. See Repository Bindings.