3.2 Architecture Views, Quality Trade-offs, and Decision Records
Architecture is not about the number of boxes or a checklist of technical terms. It is a set of decisions that have long-term impacts on system structure, key quality attributes, and high-cost choices. The purpose of architectural documentation is to enable different stakeholders to see the views that align with their concerns and to understand why those decisions were made.
Start from Architectural Requirements
Not every requirement impacts the architecture. Typically, only the following types of requirements warrant architectural attention:
- Features that define system boundaries or assign primary responsibilities;
- Critical quality attributes such as availability, performance, security, and compliance;
- Technical or organizational constraints that cannot be easily modified;
- Decisions involving high risk, significant uncertainty, or high cost of change.
For example, the color of a "registration page button" generally does not affect the architecture; in contrast, a requirement that "payment confirmation must be auditable and cannot be duplicated due to message retransmission" directly influences the data model, idempotency strategies, and system boundaries.
C4: Explain Static Structure at Different Levels of Abstraction
The core static structure diagram in C4 has four layers: System Context, Container, Component, and Code. Here, "Container" does not specifically refer to Docker containers, it denotes any independently deployable or runnable unit of data storage, application, or service.
| Layer | Questions Answered | Primary Audience |
|---|---|---|
| System Context | Who are the system's services, and which external systems do they interact with? | All stakeholders |
| Container | What are the independent, runnable or deployable units that make up the system, and how do they communicate? | Technical staff and relevant business partners |
| Component | What are the primary responsibilities within a container? | Development teams |
| Code | How do components map to classes, interfaces, or modules? | Implementation engineers |
It's not necessary to draw all four layers for completeness. According to the official C4 guidance, the System Context and Container layers are often sufficient for most teams. Component and Code layers should only be included when they help answer real-world questions.
A tournament system's System Context view might look like this:
[Participant] ----> [Tournament System] via "Register/Cancel/Check Schedule"
[Administrator] ----> [Tournament System] via "Create Event/Make Judgments/Audit"
[Tournament System] ----> [Payment Platform] via "Process Refunds"
[Tournament System] ----> [Messaging Provider] via "Send Notifications"Only after moving into the Container view do we begin to explore internal components:
[Web Application]
-> HTTPS/JSON -> [Business Application]
-> SQL -> [Relational Database]
-> publish -> [Message Broker]
[Notification Worker] <- consume --------+
-> HTTPS -> [Messaging Provider]Each box should clearly indicate its name, type/technology, and responsibility. Each relationship must specify direction, purpose, and protocol. Without semantic context (just arrows) readers cannot determine whether a connection represents a synchronous call, an asynchronous event, or a data dependency.
UML: Choose Diagrams by Problem, Not by Checklist
UML is a standardized modeling language, but it doesn't require every project to use all its diagrams. Common choices include:
- Class diagrams: domain structure, key relationships, and static dependencies;
- Sequence diagrams: call order in a specific scenario, boundary interactions, and failure paths;
- State machine diagrams: entity lifecycle and valid transitions;
- Deployment diagrams: mapping of runtime nodes to artifacts.
State machine diagrams are particularly well-suited for registration workflows:
PENDING --payment successful--> CONFIRMED --user cancels--> CANCELLED
| |
+--timeout-------------> EXPIRED
+--event ends--> COMPLETEDThis diagram is still incomplete: the team must clearly define how to handle repeated events, invalid transitions, and concurrent transitions. The value of a diagram lies in surfacing questions, it should never replace written agreements.
Sequence diagrams should include critical failure paths, rather than the "happy path alone." For example, if a database write fails after a successful payment, the recovery strategy (whether through callback retries, reconciliation tasks, or manual intervention) directly impacts consistency design.
4+1: Organizing Views by Stakeholder Concerns
Kruchten's 4+1 model describes architecture using multiple parallel views:
| View | Focus |
|---|---|
| Logical | Key functional design elements and their relationships |
| Process | Runtime processes, concurrency, communication, and synchronization |
| Development | Source code modules, subsystems, and development organizations |
| Physical | Mapping of software to hardware or runtime nodes |
| Scenarios (+1) | Use critical use cases to drive and validate the other views |
C4 is not a one-to-one replacement for the 4+1 model. C4 primarily offers a hierarchical structure for expressing system designs, while 4+1 emphasizes different points of concern. A project can use a C4 Container diagram to explain static components, a sequence diagram to illustrate process interactions, and a deployment diagram to represent the physical view.
Architecture Diagrams Must Be Bounded by Quality Attributes
Adding caching, message brokers, or replicas to a diagram does not automatically deliver high performance or high availability. Every structural choice must be grounded in the actual scenario:
Requirement: During finals, rank queries must meet p95 < 300 ms.
Candidates: Real-time aggregation on every request; precomputed rankings; short TTL caching.
Costs: Freshness degradation, write amplification, complexity of cache invalidation, additional operational components.
Validation: Conduct load testing under agreed concurrency and data volume, and monitor tail latency.Architecture design is about allocating responsibilities and risks under constraints, not about selecting patterns from a catalog.
Use ADR to Preserve "Why"
Diagrams typically show the current structure but struggle to explain why one design choice was made over another. An Architecture Decision Record (ADR) is well-suited to document key architectural decisions:
# ADR-0003: The first version adopted a modular monolith
Status:Accepted
## Context
Team size, delivery timeline, key quality attributes, known growth assumptions.
## Options
1. Modular monolith
2. Independent microservices
## Decision
Select modular monolith and with clear module API Isolate registration, schedule, and settlement.
## Consequences
- Local transactions and deployment processes are simpler;
- The module cannot be scaled independently;
- If the growth assumption fails, reevaluate the boundaries based on monitoring data.An ADR should capture the context, alternative options, the final decision, the rationale behind it, and its consequences. When an accepted decision changes, add a new Superseded record and link it to the original, this makes it easier to trace changes than quietly modifying past entries.
Only document decisions that significantly impact the system's structure, critical quality attributes, or reversibility. Decisions like "use four spaces for indentation" are better suited to coding style guidelines.
Keep Documentation Usable
- Label diagrams with title, scope, audience, update date, and legend.
- Ensure names in documentation match those used in code, deployment, and monitoring.
- Review documentation and code through the same process; update both simultaneously when the code structure changes.
- Remove outdated diagrams or clearly mark them as historical snapshots.
- Walk through diagrams using key scenarios: normal flow, timeout, retry, partial failure, and recovery.
- For decisions with low confidence, document validation methods and conditions that trigger a review.
Chapter Delivery Exercise
Complete the following for a system you are already familiar with:
- A System Context diagram;
- A Container diagram;
- A sequence diagram or state machine diagram that includes failure paths;
- Two measurable quality attribute scenarios;
- An ADR (Architecture Decision Record) documenting real trade-offs.
If any box, arrow, or component cannot be linked to a requirement, quality attribute, or constraint, ask whether it truly belongs in the architecture.