PlantUML Component Diagrams: Modeling System Architecture
A component diagram shows the high-level building blocks of a system and how they plug together through interfaces. PlantUML makes one from components, interfaces, and connectors written as text.
A component diagram describes the structure of a system at the level of its major building blocks - services, modules, libraries - and the interfaces through which they connect. It is the diagram you reach for to answer "what are the big pieces and how do they plug together," which makes it a staple of architecture documentation. Unlike a class diagram, which models code-level detail, a component diagram stays at the altitude of deployable or logical units, so it stays useful even as the internals churn.
PlantUML draws component diagrams from a compact syntax, and because they lean on Graphviz for layout, a small change re-arranges the whole picture cleanly. This tutorial covers declaring components and interfaces, wiring them with the provided and required connectors, and grouping with packages and nodes. As a text format, any architecture you write here can be reconstructed as an editable, styled diagram in Atlas Diagram Studio at /diagrams. The complete PlantUML overview is at /guides/plantuml-complete-guide, and the diagram-as-code guide at /guides/diagram-as-code-guide covers keeping such diagrams in sync with the system.
Components and interfaces
Between @startuml and @enduml, declare a component with the component keyword or by wrapping a name in square brackets, so [Web Server] and component "Auth Service" both create component boxes. For names with spaces, quote and alias: component "Payment Gateway" as PG lets the rest of the diagram refer to PG. An interface is declared with the interface keyword or by wrapping a name in parentheses, and it renders as the small circle - the lollipop - that UML uses for a provided interface.
The distinction between components and interfaces is the heart of the diagram. A component is a self-contained unit of the system; an interface is the named contract through which components talk. Declaring interfaces explicitly, rather than just drawing lines between components, is what makes a component diagram precise: it shows not merely that two pieces are connected but through which contract, which is the information an architect actually needs when reasoning about coupling and replaceability.
Wiring components together
Connect elements with the arrow syntax you know from other PlantUML diagrams. A solid line -- draws a plain connection, and a dashed arrow ..> shows a dependency, so [Web Server] ..> [Database] : reads means the web server depends on the database for reads. The most expressive form uses interfaces to show provided and required relationships explicitly, which mirrors UML's ball-and-socket notation.
To model a provided interface, connect the component to the interface with a solid line: [Auth Service] - Authentication draws the lollipop the service provides. To model a required interface, connect a consuming component to that interface with a dashed line, so [Web Server] ..> Authentication : uses shows the web server requiring the contract the auth service provides. Reading the two together - one component offers Authentication, another consumes it - turns a set of boxes into a genuine architecture that documents dependencies at the interface level, which is exactly where architectural risk concentrates.
Grouping with packages and nodes
Real architectures have structure beyond a flat list of components, and PlantUML gives you several containers to express it. Group related components to show subsystems, deployment targets, or ownership boundaries.
- package "Frontend" with a brace-delimited body groups components into a logical subsystem.
- node "App Server" represents a physical or virtual deployment target that hosts components.
- database "Postgres" and queue draw the specialised shapes for stores and messaging infrastructure.
- cloud "AWS" wraps components that live in an external or cloud boundary.
- folder and frame provide additional labelled containers for organising the diagram.
- Nest containers - components inside a node inside a cloud - to show deployment topology alongside logical structure.
- Colour and stereotype containers, using notation like a stereotype in double angle brackets, to convey their role.
Keeping architecture diagrams honest
Component diagrams are among the most valuable architecture artifacts and among the fastest to go stale, because the system they describe evolves continuously. The discipline that keeps them honest is the diagram-as-code one: store the PlantUML text in the repository, review changes to it in the same pull requests that change the architecture, and stamp each diagram with a last-updated date so readers can judge its freshness. A component diagram that obviously tracks reality builds trust; one that is quietly wrong is worse than none.
For the versions that face non-technical stakeholders or need presentation polish, treat the PlantUML file as the structural source and rebuild the diagram in Atlas Diagram Studio at /diagrams, where you can apply consistent styling and collaborate in real time. To sketch an initial architecture from a plain description, the AI diagram generator at /diagram-tools/ai-diagram-generator gives you an editable first draft. For turning an actual codebase into a component picture, see /guides/how-to-generate-diagrams-from-code, and for the deployment-focused view, the node and cloud containers here extend naturally into a deployment diagram.