Open a component to see what is inside

On the Architecture tab, a component can contain other items. Open it and the canvas shows its inside. The top level stays the big picture, and each level adds detail. It is all one diagram, with one version history and one share link.

Step by step Draw your architecture

What levels are

Put a "Bookstore" component on the top level. Inside it, add "Web app", "Orders API" and "Database". Inside "Orders API", add the parts it is made of. You can go as deep as you need.

• The top level is what you see when you open a diagram.
• Diagrams without levels work as before. Nothing changes until you open a component and add something inside it.
• Levels belong to the Architecture tab. The other tabs have no levels of their own, but they can use components from any level (see Other tabs).

Open and leave

To open a component, do any one of these:

• Double-click it.
• Right-click it and choose Open inside.
• Select it and click Open inside in the side panel.

To leave a level:

• Click a name in the breadcrumb. It appears at the top left of the canvas once you are inside a level; its first name (the diagram's name) takes you back to the top level.
• Press Esc with nothing selected.
• Use the browser's Back button. Each level change is its own history step.

The address bar follows the open level with a ?level= value, so you can copy a link that opens straight inside a component. A diagram that is locked, or that you can only view, can still be explored: opening and leaving levels never changes the diagram.

Fill a level

New items land on the level that is open. Add them from the palette, or double-click the empty canvas to quick add. Quick add is not available on touch devices, or when the diagram is locked or read-only.

Move things between levels

Select a component, then in the side panel open the Levels & C4 card:

• Move into… (hidden when the diagram is locked; a "Choose a component" list) lists the components it can go into. Choose The top level (shown when it is inside something) to bring it back out.

Or use the right-click menu:

• Group into a new component (with several items selected) wraps them in a new component.
• Move into <name> (with several items selected) moves them into that component. With many components on the canvas this list is left out; use the side panel instead.
• Move out moves the item out of the open level, into the level the open component sits in (greyed out on the top level).

Deleting a component that has items inside asks what to do with them: Delete everything inside or Move them up one level.

Arrows across levels

Draw an arrow on the deepest level where both ends are visible. The levels above show it as a dashed arrow between the components that contain the two ends, with a count when several real arrows are behind it. These are implied: you do not draw or maintain them.

An item inside the open level can also talk to something outside it. The outside item appears faded with an Outside label, so the arrow has somewhere to land. Double-click it to jump to the level it lives on.

Click a dashed arrow to see the real arrows behind it in the side panel. For each one:

• Go to opens the level that holds the arrow's source component.
• Select selects the real arrow so you can edit it.
• Delete removes it (hidden on a locked diagram).

Draw as a real arrow (hidden on a locked diagram) turns the dashed arrow into a real one between the same two components.

C4

C4 is a way to describe software at zoom levels: context (your system and the people and systems around it), containers (the apps and data stores inside it) and components (the parts inside a container). Levels map onto this naturally. Read more at c4model.com.

Using C4 is optional. To tag a component, open the Levels & C4 card in the side panel:

• C4 kind: None, Person, Software system, Container or Component.
• Description: a short sentence about what it does.
• Inside: the items inside it. Click one to open the level and select it.

Tagged items get the C4 look:

• A person is drawn with a person shape.
• Other kinds are boxes showing the kind in brackets, such as [Container: Node.js], with the description under the name. The technology comes from the tool or a technology property; a software system shows no technology.
• The C4 look applies in the card and plate node styles, not the symbol style.
• The open level gets a title: Containers of a software system, or Components of a container.
• A collapsed Key at the top left lists the C4 kinds on that level, faded outside items and dashed implied arrows.

C4 checks are warnings. When you select a component that has a C4 kind, its Levels & C4 card lists them: for example a container that is not inside a software system, a component that is not inside a container, or a container or component with no description. An agent's validate_diagram also reports arrows between C4 items that have no label. Warnings never block anything.

Other tabs

The DB, API, Sequence and Data Flow tabs work with components from any level. Where you pick a component, the picker shows its path, such as Bookstore › Orders API, so two components with the same name are easy to tell apart.

With an agent (MCP)

Agents can build and read levels through the MCP server:

• The add tools (add_node, bulk_add_nodes, add_boundary, add_note) and update_node take inside: a component id or label. Empty or null means the top level.
• move_to_level moves items into another component or back to the top level.
• render_diagram_text takes level to draw one level. Items outside it are marked "(outside)".
• delete_node asks before deleting a component that has items inside. Pass inside: "delete" to delete them too, or inside: "lift" to move them up one level.
• update_node also sets c4_kind and description.

Try it

The C4 levels example on the home page is a live bookstore diagram. Double-click Bookstore to open its containers, then Orders API for its components. Or open it in the demo, no sign-up needed.

Coming from Structurizr? Move from Structurizr shows how a workspace becomes levels.