Skip to content
Software Architecture Guide

Nested Components and Subsystems

Explanation

Section titled “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

Section titled “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

Section titled “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.

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

Checks

Section titled “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.
Section titled “Related”

Sources

Section titled “Sources”