# Nested Components and Subsystems

**In short:** A component can contain smaller parts that work together inside it. Ports on its edge pass outside requests to those parts. This lets you describe a system level by level, from a coarse view to detail.

## Explanation

A large system is hard to grasp in one picture. Nested components help. You draw a component as one box. Then you open the box and show the smaller parts inside.

**Structure from the inside.** In UML, a structured classifier is an element whose behavior can be described by how its internal parts interact. A component with nested parts fits this idea. The whole is explained by its parts and their interactions.

**Ports.** A port is an interaction point. It connects a structured classifier with its parts and with its environment. A port can also delegate: it hands a request it received to an internal part. Outside callers deal with the port. The articles "Port" and "Delegation Connector" cover this in more detail.

**Two views of the same thing.** From outside, you see a closed box. From inside, you see its parts. arc42, a documentation template, uses the same idea in its building block view:

- Level 1 is the inside view of the whole system. It shows the top-level building blocks as closed boxes.
- Level 3 zooms into selected level-2 blocks, and so on. Each step is another inside view.

arc42 also fixes where each level goes. Level n is documented in section 5-n. Level 0 is the context view. Level 1 is the top-level system view.

**Comparison with C4.** The C4 model defines a component as a group of related functionality behind a well-defined interface. Unlike a container, a C4 component is not deployed separately. See "C4 Component Diagram" for more.

## Example

Imagine an online shop called "OrderSystem". Seen from outside, it is one box with one port that accepts orders.

Seen from inside, it holds two parts: "Cart" and "Catalogue". The port passes each incoming order request to "Cart". "Cart" works together with "Catalogue" to handle it. A reader of the top-level view needs only the box and its port. A reader who wants detail opens the box.

## Trade-offs

Each extra level gives more detail but also more diagrams to keep current. arc42 lets you zoom only into selected blocks, so you can stop where more detail adds little.

A component with a boundary port that delegates to an inner part, which works with another inner part.

```plantuml
@startuml
component OrderSystem {
  portin "orders" as p1
  component Cart
  component Catalogue
}
p1 --> Cart : delegates
Cart --> Catalogue
@enduml
```

## Checks

- The top-level building block view shows the whole system as a white box with all top-level blocks as black boxes.
- Selected blocks are refined in further levels, and each level is documented in its matching section 5-n.
- Ports on a nested component's boundary are shown, and delegation to internal parts is clear.

## Related

- [UML Component Diagram](https://arc.fuet.ch/concepts/modeling-uml/uml-component-diagram.md)
- [Port](https://arc.fuet.ch/concepts/modeling-uml/component-port.md)
- [Delegation Connector](https://arc.fuet.ch/concepts/modeling-uml/delegation-connector.md)
- [Component Connector (Assembly and Delegation)](https://arc.fuet.ch/concepts/modeling-uml/component-connector-assembly-and-delegation.md)
- [Provided and Required Interface](https://arc.fuet.ch/concepts/modeling-uml/provided-and-required-interface.md)
- [C4 Component Diagram](https://arc.fuet.ch/concepts/documentation/c4-level-3-component-diagram.md)
- [Component View Refinement Levels](https://arc.fuet.ch/concepts/documentation/component-view-refinement-levels.md)
- [UML Structure Diagram](https://arc.fuet.ch/concepts/modeling-uml/structure-diagram.md)

## Sources

- [5 - Building block view | arc42 Documentation](https://docs.arc42.org/section-5/) — docs.arc42.org, accessed 2026-11-09
- [Composite structure diagram - Wikipedia](https://en.wikipedia.org/wiki/Composite_structure_diagram) — en.wikipedia.org, accessed 2026-11-09
- [Question C-5-11: How does the hierarchy of building blocks relate to the arc42 sections (5.1, 5.2 etc.)? | arc42 FAQ](https://faq.arc42.org/questions/C-5-11/) — faq.arc42.org, accessed 2026-11-09
- [Component | C4 model](https://c4model.com/abstractions/component) — c4model.com, accessed 2026-11-09