Chapter 23: Diagramming Architecture
fsa diagramming architecture-documentation c4-model uml
Status: Notes complete
Overview
Architecture exists primarily in the minds of architects — diagrams are the primary mechanism for externalizing, communicating, and validating that mental model with stakeholders, developers, and other architects. Without diagrams, architecture becomes tribal knowledge that cannot be reviewed, challenged, or evolved. However, stale or misleading diagrams are actively harmful, creating false confidence in outdated information. The goal is diagrams that are accurate, appropriately leveled, and maintained alongside the architecture they represent.
Why Diagrams Matter
Architecture is invisible by default. Code reveals implementation decisions but obscures architectural intent. A well-structured diagram answers questions that code cannot:
- What are the major deployable units and their responsibilities?
- How do systems communicate at runtime?
- What does this system look like from the business perspective vs. the infrastructure perspective?
- Where are the boundaries between teams or domains?
Key insight: a diagram is a communication artifact, not a technical artifact. Its success is measured by whether the audience understands the architecture, not by how detailed or technically precise it is.
Stale diagrams are worse than no diagrams because they mislead readers into believing they understand a system they do not. A team that relies on an outdated sequence diagram will make integration mistakes and debug phantom interactions. If a diagram cannot be kept current, it should be removed or clearly marked as historical.
Diagramming Tools
Whiteboard Tools
Whiteboard tools prioritize real-time collaboration and visual speed over persistence.
| Tool | Strengths | Weaknesses |
|---|---|---|
| Miro | Rich shape library, async collaboration, integrations | Not version-controlled, diagrams drift |
| Mural | Facilitation features, templates | Similar drift problem |
| FigJam | Fast and fluid, Figma-native | Limited for complex technical diagrams |
Best use: brainstorming sessions, architecture workshops, exploratory design. Not appropriate as a system of record.
Drawing Tools
Drawing tools produce persistent, shareable diagrams with more control over visual fidelity.
| Tool | Strengths | Weaknesses |
|---|---|---|
| draw.io (diagrams.net) | Free, integrates with Confluence/Google Drive, exports XML | Manual maintenance, no code linkage |
| Lucidchart | Polished output, team sharing, templates | Paid, still manual |
| OmniGraffle | macOS-native, precise layout control | macOS only, expensive |
Best use: formal architecture documents, stakeholder presentations, onboarding documentation. Require discipline to keep current.
Code-as-Diagrams Tools
These tools generate or render diagrams from text/code, enabling version control alongside source code.
| Tool | Approach | Strengths |
|---|---|---|
| PlantUML | Text DSL rendered to image | Wide format support (sequence, component, class, deployment) |
| Mermaid | Markdown-embedded DSL | GitHub/GitLab native rendering, easy to embed in docs |
| Structurizr | C4-model-aware DSL (Structurizr DSL) | First-class C4 support, workspace concept, multiple views from one model |
Best use: diagrams that must stay in sync with code changes; CI/CD pipelines that render and publish diagrams on merge; architecture decision records (ADRs).
Key trade-off: code-based tools sacrifice WYSIWYG editing for version control and automation. Layout control is limited — the tool decides where to place shapes. Visual output is functional but rarely polished.
IDE-Integrated Diagrams
Some IDEs can generate diagrams directly from code structure. IntelliJ IDEA’s diagram view can render class hierarchies, module dependencies, and call graphs from the actual codebase. These are accurate by definition but reflect implementation, not architectural intent — every detail is present with no abstraction.
Best use: understanding an unfamiliar codebase, dependency analysis, identifying circular dependencies. Not appropriate for stakeholder communication.
Diagramming Standards
UML (Unified Modeling Language)
UML is the ISO-standardized notation for software modeling. It defines 14 diagram types across two categories:
Structural diagrams (show static structure):
- Component diagram: deployable units and their dependencies/interfaces
- Class diagram: types, relationships, attributes, and operations
- Deployment diagram: physical/virtual infrastructure topology
- Package diagram: logical groupings and namespaces
Behavioral diagrams (show dynamic behavior):
- Sequence diagram: time-ordered message exchange between participants
- Activity diagram: workflow and decision logic
- Use case diagram: system capabilities and actors
- State machine diagram: object lifecycle and state transitions
UML is precise and formally defined — every shape and arrow has a specific meaning. This makes it ideal for detailed technical design where precision matters. However, UML’s verbosity and formality create a high barrier for non-technical stakeholders.
C4 Model
Developed by Simon Brown, the C4 model provides four hierarchical levels of zoom for describing a software system. Each level targets a different audience and answers different questions.
| Level | Name | Audience | Shows |
|---|---|---|---|
| Level 1 | Context | Business stakeholders, executives | The system in its business environment — what it does, who uses it, what external systems it integrates with. No technology. |
| Level 2 | Containers | Architects, senior developers, DevOps | Deployable/runnable units (web apps, APIs, databases, message queues, mobile apps). Shows technology choices and communication protocols. |
| Level 3 | Components | Developers | Major components inside a single container — modules, services, controllers, repositories. Shows how a container is structured internally. |
| Level 4 | Code | Developers (deep-dive) | Class/entity level — UML class diagrams, ER diagrams. Usually generated from code. Rarely hand-drawn. |
C4 core principles:
- Each level zooms into one element from the level above — a Container diagram zooms into one box from the Context diagram
- Shapes are simple rectangles (persons, software systems, containers, components); color and position carry meaning through a consistent key
- Every diagram must have a title, description, and legend
- The model is notation-agnostic — C4 describes what to show, not what tool to use (it pairs well with Structurizr DSL)
C4 is the recommended default for most software architecture communication. It is lightweight enough for agile teams but rigorous enough for enterprise contexts.
ArchiMate
ArchiMate is an enterprise architecture modeling language maintained by The Open Group, designed to complement TOGAF. It models architecture at three layers:
| Layer | Content |
|---|---|
| Business layer | Business processes, actors, roles, services that the organization delivers |
| Application layer | Application components and services that support business processes |
| Technology layer | Infrastructure — servers, networks, devices, system software |
ArchiMate also models motivation (goals, requirements, constraints) and implementation and migration (work packages, deliverables, plateaus). This breadth makes it comprehensive but also complex.
Best use: enterprise architecture programs, IT portfolio management, TOGAF-aligned organizations. Overkill for a single team or product.
Comparison Table: UML vs C4 vs ArchiMate
| Dimension | UML | C4 Model | ArchiMate |
|---|---|---|---|
| Primary use | Detailed technical design | Software system documentation | Enterprise architecture |
| Audience | Developers, architects | All stakeholders (level-dependent) | Enterprise architects, CTO, EA board |
| Learning curve | High (14 diagram types) | Low (4 levels, simple shapes) | Very high (multi-layer meta-model) |
| Formality | High (ISO standard) | Medium (guidelines, not rules) | Very high (Open Group standard) |
| Tooling | Enterprise Architect, PlantUML, Sparx | Structurizr, draw.io, any tool | Archi (free), BiZZdesign, Mega |
| Version control friendly | With PlantUML/text | With Structurizr DSL/Mermaid | Limited (most tools are GUI-only) |
| Stakeholder accessibility | Low | High | Low |
| When to use | Detailed interface design, sequence flows, class hierarchies | Default choice for software architecture at any team size | Large enterprise with multiple systems, TOGAF alignment |
| When NOT to use | Executive communication, exploratory design | Fine-grained code documentation | Single product teams, agile startups |
Diagram Guidelines
The following rules apply regardless of notation or tooling.
1. Use a Consistent Visual Language
Shapes must carry consistent meaning throughout a diagram and across a diagram set. If rectangles represent services, do not also use rectangles for databases. Establish a visual vocabulary and apply it uniformly. Readers build a mental model of what shapes mean — inconsistency forces them to re-read the legend on every diagram.
2. Titles and Descriptions Are Mandatory
Every diagram needs a title (what is being shown) and a short description (why this diagram exists, what decision or question it addresses). Without these, readers cannot determine whether a diagram is current or relevant.
3. Show Directionality
Arrows must indicate the direction of data flow, control flow, or dependency. An undirected line between two components tells the reader nothing about which component initiates communication or which depends on the other. Arrowheads are not optional.
4. Label Relationships
An arrow between Component A and Component B labeled only with a line says nothing. The label should describe what the relationship means: “sends order events via Kafka”, “HTTP GET /api/orders”, “reads from (read-only)”. Labels answer the question “what is happening here?“
5. Include a Legend
Even with a consistent visual language, a legend is required. Do not assume readers have memorized your notation. A legend in the corner of every diagram removes ambiguity about shape meaning, color meaning, and line style meaning.
6. Minimize Crossing Lines
Lines that cross each other create visual confusion and suggest unintended relationships. Before publishing a diagram, reorganize the layout to minimize or eliminate line crossings. Most diagramming tools offer auto-layout options; manual adjustment is often needed for clarity.
7. Match Abstraction to Audience
A C4 Level 1 Context diagram should contain no technology details. A C4 Level 3 Component diagram should not show business actors. Each diagram should present exactly the information its target audience needs — no more, no less. Extra detail does not add value; it adds noise.
8. Diagrams Tell a Story
A good architecture diagram should be self-explanatory to a knowledgeable reader without requiring an accompanying verbal explanation. Walk through the diagram as if telling a story: “Here is where the user starts, this is what happens, these are the systems involved.” If the diagram requires a 10-minute verbal tour to understand, it has failed its communication purpose.
Common Antipatterns
Big Ball of Mud Diagram: every component connected to every other component with unlabeled bidirectional arrows. Technically shows all relationships but communicates nothing.
Out-of-Date Diagram: a diagram that was accurate 18 months ago but has not been updated since. More dangerous than no diagram because it misleads rather than saying “I don’t know.”
Wrong Level of Abstraction: a diagram that mixes C4 Level 2 containers with C4 Level 3 components in a single view. Readers cannot tell what level they are reading at.
Missing Legend: a diagram with custom colors and shapes that has no legend. The author knows what blue rectangles mean; no one else does.
No Directionality: undirected lines between components. Data flows in one or both directions — the diagram must show which.
Tool Lock-In: storing diagrams only in a paid cloud tool with no export path. When the license lapses, the diagrams are gone.
Key Takeaways
- Diagrams externalize architecture: architecture lives in minds by default; diagrams make it visible, reviewable, and transferable to new team members.
- Stale diagrams are harmful: an outdated diagram misleads readers into making decisions based on false information — remove or archive diagrams that cannot be maintained.
- C4 is the recommended default: its four levels (Context, Containers, Components, Code) address different audiences with appropriate abstraction, making it suitable for most software teams.
- Code-as-diagrams enables versioning: PlantUML, Mermaid, and Structurizr DSL allow diagrams to live in source control and evolve with the codebase, reducing staleness risk.
- UML for technical precision: use UML sequence diagrams and component diagrams when precise, formal notation is needed for interface contracts or detailed design discussions.
- ArchiMate for enterprise scope: reserve ArchiMate for TOGAF-aligned enterprise architecture programs that need to model business, application, and technology layers together.
- Consistent visual language is non-negotiable: shapes must mean the same thing across every diagram; a legend is mandatory on every diagram without exception.
- Label every relationship: an arrow without a label is incomplete — the label describes the nature of the dependency or data flow, not just its existence.
- Match level to audience: showing too much detail to an executive is as wrong as showing too little detail to a developer; C4 levels enforce this discipline.
- Diagrams tell a story: a diagram that requires 10 minutes of verbal explanation to understand has failed; a reader should be able to follow the narrative independently.
Related Resources
- ch01-introduction — architectural thinking and the role of communication in architecture
- ch02-architectural-thinking — how architects externalize decisions and work with stakeholders
- ch24-making-teams-effective — using diagrams as a team guidance tool during code reviews and office hours
Last Updated: 2026-05-29