UML Component Diagrams: A Complete Guide
Component diagrams show how a system decomposes into replaceable parts and the interfaces they expose and consume. This guide covers components, ball-and-socket interfaces, ports, and dependencies.
As a system grows past the point where a class diagram can hold it, you need a higher-altitude view: not individual classes but the major building blocks and how they plug together. That is what a component diagram provides. It models a system as a set of components, each a replaceable unit with well-defined interfaces, and shows how they depend on one another. For architecture reviews, service decomposition, and explaining a system to a new team, it is the right level of abstraction.
The signature notation of the component diagram is the ball-and-socket connector, which makes provided and required interfaces visible at a glance. This guide covers components, those interfaces, ports, and how component diagrams relate to the deployment and class diagrams they sit between. You can draw them at /diagrams, and the wider UML context is at /diagram-tools/uml-diagram.
What counts as a component
A component is a modular, replaceable part of a system that encapsulates its contents and exposes its behavior through interfaces. It is drawn as a rectangle with the component stereotype (the word component in guillemets, or a small component icon in the corner). Examples are an Authentication Service, an Order Processing module, a Payment Gateway adapter, or a database access layer. The defining property is replaceability: you should be able to swap a component for another that offers the same interfaces without the rest of the system noticing.
This is a design-time abstraction, not necessarily a physical file or process. A component might be a microservice, a library, a subsystem, or a logical grouping of classes. The point of drawing it as a component is to declare a boundary and a contract: here is a unit, here is what it offers, here is what it needs. That contract is what lets teams work against each other's components in parallel.
Provided and required interfaces
The most distinctive notation in a component diagram is the ball-and-socket symbol. A provided interface, the services a component offers to others, is drawn as a small circle (the ball, sometimes called a lollipop) on a stick from the component. A required interface, the services a component needs from others, is drawn as a half-circle (the socket) on a stick. When one component's ball fits into another's socket, they are connected: the provider satisfies the consumer's requirement.
This notation is powerful because it makes dependencies explicit and directional. You can see immediately that the Order component requires a Payment interface, and that the Payment Gateway component provides it, so the two connect. Reading a well-drawn component diagram, you can trace exactly what each part depends on, which is precisely the information you need when planning a change, isolating a fault, or deciding what to mock in a test.
Ports and internal structure
A port, drawn as a small square on the boundary of a component, is a named interaction point that groups interfaces together. Ports let you distinguish, for instance, a component's public API port from its admin port, each bundling its own provided and required interfaces. For complex components, ports keep the connections organized rather than having a dozen bare interfaces sprouting from every edge.
You can also show a component's internal structure by nesting the smaller components or classes that realize it inside its rectangle, with connectors wiring their interfaces to the outer component's ports. This is useful when explaining how a subsystem is built, but it is easy to overdo. Most component diagrams are more valuable as black-box views that show the pieces and their contracts, leaving the internals to lower-level diagrams.
How it relates to other diagrams
Component diagrams sit between class diagrams below and deployment diagrams above. Class diagrams describe the internals of what realizes a component; deployment diagrams describe where components physically run. Knowing which to reach for saves a lot of confusion.
- Use a class diagram when you care about individual classes, their attributes, and their relationships.
- Use a component diagram when you care about major building blocks and the interfaces between them.
- Use a deployment diagram when you care about which physical nodes or servers host which artifacts.
- Component diagrams answer "what are the parts and how do they connect"; deployment diagrams answer "where does each part run".
- A single component often maps to many classes and is later deployed as one or more artifacts.
- For microservice architectures, a component diagram is frequently the clearest single overview of the system.