UML composite structure diagrams
The inside of one thing. Its parts, the ports on its boundary, and the connectors wiring them together - the diagram for explaining how a single component is actually built.
6 min readUML 2.5.111 of 15
01What it shows
A composite structure diagram answers one question: what is this thing made of, on the inside? It takes a single classifier - a class, a component, a subsystem - and draws its internal parts and how they are wired.
The distinction from the diagrams either side of it is worth getting straight. A class diagram shows types and the relationships between them, in general. A component diagram shows several components and the contracts between them. A composite structure diagram zooms into one of those and shows the runtime structure inside it.
02Parts, ports, connectors
| Element | Notation | What it means |
|---|---|---|
| Part | rectangle inside the frame | A role played inside the owner, written roleName: Type. Can carry a multiplicity in the corner. |
| Port | small square on the boundary | A named interaction point. Everything crossing the boundary goes through one, which is what makes the boundary meaningful. |
| Connector | line between parts | A communication path between two parts inside the owner. |
| Delegation connector | line from a port to a part | Traffic arriving at this external port is handled by that internal part. The outside never learns which one. |
| Assembly connector | ball in a socket | One part's provided interface wired to another's required one. |
| Collaboration | dashed ellipse | A named pattern of roles - the structural half of a design pattern, without committing to classes. |
03Why ports are the useful bit
A port is a small square, and it is doing more work than it looks. It says: this is the only way in. Nothing outside reaches a part directly; everything arrives at a port and is delegated inwards.
That produces the property this diagram exists for. The outside of the box depends only on the ports, so the entire inside can be rearranged - parts split, merged, replaced - without anything outside changing, as long as the ports keep their contracts. It is encapsulation drawn as geometry.
Ports also let one component present several distinct faces. A payment orchestrator with a public API port, an admin port, and an event-publishing port is saying something precise about its surface area, and about which of those a firewall or an authorization policy needs to treat differently.
04When to draw one
Reach for it when
- Explaining how one non-obvious component is built internally
- Designing something where the same type appears in two different roles
- Documenting a component with several distinct interaction points
- Embedded, telecoms, or protocol work, where this diagram is genuinely load-bearing
Reach for something else when
- The internals are three classes with obvious relationships - a class diagram is enough
- You are showing several components, not the inside of one - use a component diagram
- The interesting part is what happens over time, not the wiring
- Nobody has asked how the inside works
This is one of the less-used UML diagrams and reasonably so - most components do not have interesting internal structure. When one does, though, nothing else expresses it as directly, and the alternative is usually a paragraph of prose that nobody reads twice.
In one line each
- 01Shows the inside of exactly one classifier: its parts, ports, and wiring.
- 02Parts are roles played at runtime, not classes - the same class can be two parts.
- 03Ports are the only crossings of the boundary, which is what makes the boundary real.
- 04Delegation connectors hand an external contract to an internal part.
- 05Rearranging the inside is free as long as the ports keep their contracts.
Related reading