UML Composite Structure Diagrams

A composite structure diagram opens up one class or component and shows the parts inside it, how those parts are wired together, and the ports through which the whole talks to the outside. It is read by designers who need more detail than a component diagram gives but less than full class-level code.

1. What a Composite Structure Diagram Shows

A class diagram tells you that Car has an association to Wheel. A composite structure diagram tells you that this car contains exactly four wheels and one engine, and that the engine connects to the drivetrain rather than to the wheels directly. The difference is context: parts are roles that instances play inside a specific whole.

The diagram has three jobs. It shows parts (internal roles with types and multiplicities), connectors (which parts talk to which, inside this whole only), and ports (the whole's interaction points). A related form, the collaboration, names a set of roles that cooperate to achieve something, such as a design pattern.

2. Notation

The outer rectangle is the structured classifier. Each inner box is a part written role : Type [multiplicity]. A solid border means the whole owns the part (composition); a dashed border means a reference to something that lives elsewhere. Lines between parts are connectors. Small squares on the boundary are ports; a delegation connector links a port to the inner part that actually handles the traffic. A dashed ellipse is a collaboration, whose roles can be bound to real parts.

3. Example 1: Inside an Online Shop Checkout

Walkthrough: requests enter through the http port and are delegated to the api controller part. The controller uses price and repo. Pricing hands off to pay, a payment client, which is the only part allowed to reach the outbound psp (payment service provider) port. The diagram documents a security-relevant fact: no other part has a route to the payment network.

4. Example 2: An ML Inference Server

Walkthrough: the server contains a tokenizer, a batcher and two model replicas ([2]). The KV cache is drawn dashed because it is shared memory owned elsewhere. On the right, the DynamicBatching collaboration describes a pattern with two roles, queue and worker, bound to the batcher and the model parts. This is how composite structure diagrams document design patterns in place.

5. Pros, Cons, and When to Use

Pros

• Shows internal wiring that class diagrams cannot express.
• Context-specific multiplicities (exactly 4 wheels in this car).
• Ports and delegation make boundaries and entry points explicit.
• Collaborations document design patterns where they are used.
• Popular in systems engineering (SysML internal block diagrams build on it).

Cons

• One of the least known UML diagrams; many readers need an explanation.
• Overlaps heavily with component diagrams.
• Weak tool support in lightweight diagrams-as-code tools.
• Easy to over-detail; it can turn into a second class diagram.
• Rarely worth it for simple CRUD services.

When to use

• Explaining the inside of an important or complex component.
• Embedded, robotics and hardware-software systems.
• Showing which internal part owns a sensitive port.

When not to use

• When a component diagram already conveys enough.
• For data models (use class or ER diagrams).

6. Reading Tips and Common Mistakes

Read from the ports inward: for each port, follow the delegation connector to the part that handles it, then follow connectors to see which other parts are involved. Parts with no path to any port are either internal helpers or dead weight, and both are worth asking about.

Common mistakes: drawing associations instead of connectors (connectors only exist inside this one whole); forgetting multiplicities, which are often the main point; and confusing a part with an object. A part is a role played by some instance at run time; an object diagram shows actual instances. If you work in systems engineering, the SysML internal block diagram is a close relative with the same ideas and extra flow ports.

7. As Diagrams-as-Code

PlantUML has no dedicated composite structure syntax; the usual approach is a component diagram with nested elements and portin/portout:

@startuml
component CheckoutService {
  portin http
  portout psp
  component "api : Controller" as api
  component "price : Pricing" as price
  component "repo : CartRepo" as repo
  component "pay : PayClient" as pay
  http --> api
  api --> price
  api --> repo
  price --> pay
  pay --> psp
}
@enduml

Full-featured modelling tools (Enterprise Architect, Papyrus, Cameo) support the real notation, including collaborations.

8. Related Diagrams

• UML Diagrams — overview of all 14 UML diagram types and when to use each
• Component Diagrams — the outside view of the same unit
• Object Diagrams — actual instances rather than roles
• Deployment Diagrams — where the whole runs