What you'll be able to do
- Choose a SAD template — arc42, Views and Beyond or the TOGAF Architecture Definition Document — and adapt it, marking each section Mandatory, Recommended or Optional
- Select views from a stakeholder × view matrix (d/s/o), and describe each view with its primary presentation, element catalogue and rationale
- Explain views, viewpoints and perspectives, and map 4+1, Rozanski and Woods and C4 onto one another
- Write an interface description with the SEI template, giving error handling as much space as the nominal flow
- Record decisions as ADRs that name the options you rejected
- Structure a brownfield document as Baseline → Target → Gap analysis → Transition
Worth asking before you start: do you find architecture documentation useful — and if not, why? Are you sceptical about documentation?
Documentation earns its cost through a handful of concrete returns beyond simply existing: it forces the design process itself toward explicit, reviewable decisions rather than ones left implicit in code; it is the fastest way to bring a new team member to a working understanding of the system; it is literally what an architecture review or evaluation is conducted against; and it gives architects and developers a shared baseline to argue from, instead of re-deriving intent from memory each time a question comes up.
Forms of documentation
| Form | Examples |
|---|---|
| Formal document | Usually quite big and complete documents: RFP Response, Software Architecture Document, Architecture Definition Document, Architecture Design, Architecture and Code Review |
| Articles and guidelines | Design guidelines, implementation guidelines, design of particular cases. Also a good example: when big formal documentation is split into a group of articles and guidelines |
| Presentations | Often used in pre-sales and for presenting architecture design to business stakeholders and teams |
| Models and diagrams | Design models and various forms of diagrams |
| Autogenerated documentation | Based on metadata or implementation — API documentation, SDK documentation |
Cost and the three attributes
Architecture documentation should be reasonable, and the amount of documentation should be reasonable — but it is almost impossible to calculate this value because of the big variety of every parameter and the difficulty of making predictions. In reality you select it based on your personal experience.
Total Cost of Ownership (TCO) includes the initial costs to implement a project together with the continuing costs to maintain, modify, train staff, house, deploy, provide infrastructure, or any other cost associated with the project — including final decommissioning. TCO is an estimate including all direct and indirect costs over the useful life of the application, commonly used in full cost accounting systems.
Three main attributes of good documentation:
| Attribute | Meaning |
|---|---|
| Essential | Select the most essential and important part of your system to document, rather than creating detailed documentation for every small piece. Too detailed documentation could become outdated quite quickly and requires more time to develop |
| Valuable | Understand your stakeholders, and the value of your documentation for them |
| Timely | And evolutionary — you do not need to do big up-front design |
Why views
Software is complex, the design of software is even more complex, and you could not represent your system with one holistic view. Therefore views are the essential part of describing software.
What this basically means is that we handle hundreds of elements, hundreds of element types, their relationships and properties. Views help limit that to a reasonable amount that could fit in our heads.
Principle (Rozanski and Woods, Software Systems Architecture): it is not possible to capture the functional features and quality properties of a complex system in a single comprehensible model that is understandable by, and of value to, all stakeholders.
Three different lenses to consider — "lens" in the everyday sense, not the Rozanski and Woods perspectives defined later in this module:
- The stakeholder lens — sponsor, PM, dev, devops
- The level-of-detail lens — conceptual, logical, physical
- The domain lens — data, application, technology
A short history of architectural views
| Year | Who | Contribution |
|---|---|---|
| 1974 | David Parnas | In On a "Buzzword": Hierarchical Structure he observed that software is composed of many structures, not one |
| 1992 | Perry and Wolf | Foundations for the Study of Software Architecture — outlined that architecture involves multiple views and multiple architecture styles; made a comparison with building architecture |
| 1995 | Philippe Kruchten (Rational Software Corporation) | An influential paper describing four main views of software architecture — logical, process, development, physical — plus a distinguished fifth view tying the other four together by showing how they satisfy key use cases: the "4+1" approach. Since embraced as a foundation piece of the Rational Unified Process |
| 1995 | Dilip Soni, Robert Nord, Christine Hofmeister (Siemens Corporate Research) | A similar observation from industrial practice: the conceptual view, module interconnection view, execution view and code view. These correspond more or less to Kruchten's four and became known as the Siemens Four View model |
| 2000 | IEEE | Adopted IEEE 1471-2000 for architecture descriptions. Unlike approaches prescribing a fixed set of views, this standard advocates creating your own views that best serve the stakeholders and their concerns. (The Views and Beyond approach also advises flexibility in choosing your view set) |
| 2005 | Rozanski and Woods | Software Systems Architecture (1st edition) advocates six viewpoints: functional, information, concurrency, development, deployment and operational |
| 2007 | ISO/IEC | Adopted IEEE 1471-2000 as ISO/IEC 42010:2007, with the content essentially unchanged |
| 2011 | ISO/IEC/IEEE | Joint revision, ISO/IEC/IEEE 42010:2011: views governed by viewpoints that frame stakeholders' concerns, plus model kinds, correspondences between views, and requirements on architecture frameworks and description languages |
| 2011 | Rozanski and Woods | Second edition adds the Context viewpoint — six viewpoints become the seven used later in this module |
| 2022 | ISO/IEC/IEEE | ISO/IEC/IEEE 42010:2022, the current edition. It describes an entity of interest rather than only a system, renames "architecture framework" to architecture description framework, and replaces "architecture model" with view component |
| — | Philips Research | The CAFCR model, calling for five views: customer, application, functional, conceptual and realization |
Kruchten's 4+1
| View | Content |
|---|---|
| Logical | The most misunderstood of the four. Kruchten describes it as a decomposition into key abstractions taken mostly from the problem domain — objects or object classes. In practice it is often drawn as a functional decomposition, in several ways: sub-systems; domains and domain entities; states and the transitions between them; business interactions. For the Lumen case it would be functional modules such as referral intake, availability search, offer and confirmation, notifications, partner management and reporting. The logical view primarily serves the functional requirements — what the system offers its users |
| Process | Basically represents abstractions from the logical view within runtime: components, processes, threads, runtime element interactions. It also shows integration with external systems and interfaces to the outside. Addresses concurrency, distribution, performance and scalability; Kruchten names system integrators as its main audience |
| Development | Describes the static organisation of the software in its development environment — modules, libraries, subsystems and layers. Its concerns are ease of development, reuse and build; its audience is developers and their managers |
| Physical | Maps the software onto infrastructure — nodes, networks, regions — and shows where each process runs. Addresses availability, reliability, performance and scalability of the deployed system, and is where encryption in transit and data location become visible; its audience is system and operations engineers. A worked Lumen physical view follows the Task |
| +1 Scenarios | Ties the other four together by showing how they satisfy key use cases |
The original description of the model is The "4+1" View Model of Software Architecture, 1995.
The C4 model
The C4 model is taught in Module 5 (Architecture Modeling), where you draw the Lumen context and container diagrams. In a SAD, C4 supplies some of the views, not all of them. Roughly: the system context diagram is Rozanski and Woods's Context view; container and component diagrams are component-and-connector views, close to their Functional view and to Kruchten's process view; and C4's deployment diagram is the physical or Deployment view. C4 has no counterpart for the Information, Development or Operational views — take those from another school when your stakeholders need them. The rest of this module is about choosing, describing and maintaining views in any notation.
SEI Views and Beyond
View-based documentation allows us to split the bigger task of architecture description into a few smaller ones that are much more manageable. SEI bases its documentation approach on the style-and-view relation.
How to describe a view
| Section | Content |
|---|---|
| Primary Presentation | Shows elements and their relations. It is the main representation of the view, typically a graphical representation |
| Element Catalog | Describes the elements from the primary presentation. It can include the catalog of elements and their properties: element catalog, element properties, element interfaces/APIs, element interaction and relationships |
| Context Diagram | Depicts the relationship with external systems and other environments |
| Variability Guide | Shows possible variability points |
| Rationale | A justification of the design — why this particular design was selected |
Beyond views
The "beyond" in the name is documentation that belongs to no single view (Clements et al., Documenting Software Architectures). A documentation roadmap tells each stakeholder how the document is organised and which parts to read. A system overview gives the system's purpose and context in a page, before any view. A mapping between views shows how elements correspond — which modules implement which containers, which containers deploy to which nodes. Add the cross-view rationale and a glossary. The mapping is the piece most often missing, and its absence is how views drift apart unnoticed.
Style and view catalogue
Module styles and views cover the structure of implementation units.
| View | Notations and tools |
|---|---|
| Decomposition | Box-and-line; UML; treemap (jArchitect for Java, NDepend for C#); jigsaw treemaps (D3.js); Code City — create or generate an MSE file then visualize |
| Uses | UML packages plus UML depends-on arrows; dependency graph. Be aware of different dependencies — up-stream and down-stream |
| Layered | Shows which layer is allowed to use which. The key must state the rule — for example whether a layer may use only the layer directly below it, or any lower layer. Onion architecture is layered too, although its rings make the layering less obvious than stacked boxes |
| Data model | ERD using Crow's Foot notation; UML |
Modelling non-relational storage is less settled than drawing an ERD. Workable options by store type:
- Key-value — tables are the simplest way, clear and easy to support. Depending on your key you could use different approaches, even JSON. Values differ: blobs → tables; aggregates → JSON; lists → their own treatment
- Document-oriented — JSON and JSON visualization; models with "include" relationships (ERD, UML); vendor-specific tools such as MongoDB Compass
- Column-families — model one table per query, showing partition keys, clustering columns and the access pattern each table serves (older Cassandra material talks of super-columns, which are obsolete); the same tools can be used, or vendor-specific ones such as the Kashlev Data Modeler for Cassandra, which builds a conceptual model using Chen notation plus access patterns, then generates the logical model based on those access patterns
- Graph database — a property-graph model: node labels with their properties, and named, directed relationships with their own properties. A small example graph plus the main traversal queries usually communicates better than an abstract schema
Component-and-connector styles and views usually explain:
- What the major executing components are and how they interact
- What the major data storage is
- How data flows through the system
- How it could be scaled
There are many C&C styles; SEI specifies dataflow style, call-return style, event-based style, and repository. In practice the C&C views you will draw most often are for a monolith, a service-oriented system and an event-driven system — including ESB and actor-based variants.
Allocation styles and views — deployment above all.
Rozanski and Woods: views, viewpoints and perspectives
A viewpoint defines the stakeholders whose concerns it reflects, and guides principles and template models to construct and format views.
The relationship between views and viewpoints is something like the relationship between classes and objects in programming: class definitions provide templates to construct objects.
Underneath this vocabulary sits a distinction worth keeping precise, from Bass, Clements and Kazman's Software Architecture in Practice and the SEI Views and Beyond approach: a structure is the actual set of a system's elements and their organisation — the module structure is simply the modules and how they are arranged — while a view is the documented representation of that structure. Their formulation to remember is that architects design structures; they document views of those structures. ISO/IEC/IEEE 42010:2022 does not define structure; it standardises the description side — views governed by viewpoints that frame stakeholders' concerns — and it deliberately avoids prescribing which views you must produce, which is why the catalogue below is a recommendation to adapt, not a checklist to complete unmodified.
A perspective, in Rozanski and Woods's sense, is a set of activities, tactics and guidelines for making sure the system has a group of related quality properties — properties that cut across several views.
Each view is directed by its viewpoint — its template and guidance. While a view describes the architecture, perspectives guide us through the process of analysing and modifying the architecture to ensure it achieves the qualities defined.
Perspectives don't exist in isolation, in contrast to views. Perspectives are worth something only in the context of a particular view — this is called applying the perspective to the view. Applying a perspective doesn't result in new views (there is no "security view" or "scalability view"); it identifies a number of modifications to existing views, to help those views address the stakeholders' quality attribute concerns.
The design loop: having a set of architecture candidates captured as a set of architecture views, you apply perspectives one by one — conducting dedicated activities, identifying action items, choosing and applying tactics. As a result you typically make some changes to the candidate, and so on.
The seven core viewpoints
The second edition of Software Systems Architecture (2011) defines seven core viewpoints for information systems architecture — the first edition had six, and Context is the one added. Rozanski and Woods present them as largely separate, but group them under Context, which sets the scope for the rest:
| Viewpoint | Describes (in summary) |
|---|---|
| Context | The system's place in its environment: the people, systems and organisations it deals with, and what it depends on them for. It comes first because it fixes the scope every other view works within |
| Functional | The elements that do the work at runtime — what each is responsible for, the interfaces it offers, and how the elements call one another |
| Information | The system's data: what is stored where, who owns it, how it changes over its life and how it moves between elements |
| Concurrency | Which functional elements run in which processes and threads, what can run in parallel, and how that parallelism is coordinated |
| Development | What the people building the system need: module structure, shared design rules, and how code is organised, built and tested |
| Deployment | The runtime environment and the system's dependence on it: the nodes, networks and storage required, the technical needs of each element, and which software runs where |
| Operational | How the system is installed, migrated, run, monitored and supported once it is live |
The first group — Functional, Information and Concurrency — describes the system's fundamental organisation: between them they define how the system provides its functionality. The second group — Development, Deployment and Operational — describes how that organisation is built, placed and run, and is to some extent driven by the first. The Development view, for example, sets the standards for building the functional, information and concurrency elements; the Deployment view decides where those elements run, and the Operational view how they are kept running.
Perspectives
Perspectives deliberately pair tightly related qualities:
- Performance & Scalability Perspective joins two qualities because of the tight relationship between them: performance concerns what workload the system can process and how quickly, whereas scalability focuses on the predictability of system performance as the workload increases
- Availability & Resilience Perspective — the desired quality is to be fully or partially operational as and when required, and to effectively handle failures that could affect system availability
Those two, with Security and Evolution (the ability to absorb change), are the book's four core perspectives. It adds others — Accessibility, Development Resource, Internationalisation, Location, Regulation and Usability. For Lumen, Regulation and Location matter as much as any core one: applied to the Deployment and Information views, they are what turn "comply with health-data regulation in each region" into region-bound data stores.
The conceptual model
An architecture is documented in an Architecture Description (AD).
- The AD is made of one or more views, and may also carry the principles, standards and glossary the views build on. An AD might hold, say, a Functional, a Concurrency and a Deployment view
- Each view is built according to a viewpoint: an Operational view follows the templates, patterns and guidance of the Operational viewpoint
- Each view contains one or more models, each showing the features of the architecture that matter to that view. An Information view might hold an entity-relationship model, a data-ownership model and a state-transition model
- Applying a perspective changes existing models, or adds secondary models that help judge a quality property without defining any of the system's structures. Applying the Security perspective, for instance, usually produces a threat model of what the system must defend against
Why models are important: a model's value is abstraction — deliberately leaving detail out, so that stakeholders, and you, can see the aspects of the architecture that matter. A good model lets a stakeholder understand an architecture they could not follow from the code or the full design.
Benefits and pitfalls of multiple views
Both tables summarise, in this course's words, the argument Rozanski and Woods make in Software Systems Architecture (2nd edition); read the book for the full version.
Benefits
| Benefit | Explanation |
|---|---|
| Separation of concerns | One model of everything tangles independent concerns together, so a change to one is hard to reason about and hard to explain. Separate but linked views let you design, analyse and explain one concern at a time |
| Communication with stakeholder groups | End users, security auditors and support staff care about very different things. Views let you send each group straight to the part that answers its questions, in a language and notation that group can read |
| Management of complexity | Nobody holds every aspect of a large system in mind at once. Taking one significant aspect at a time makes the whole tractable |
| Improved developer focus | Developers build from the AD. Views that isolate what they need — structure, interfaces, build rules — make it likelier that the system they build is the one that was designed |
Pitfalls
| Pitfall | Explanation |
|---|---|
| Inconsistency | Several views of one system drift apart: a component renamed in one view but not another, a container in the deployment view that the functional view never mentions. When Rozanski and Woods wrote, little tooling could check this. Model-based tools such as the Structurizr DSL now generate several views from one model, so a rename reaches every view (see Module 5), and architecture tests in the ArchUnit style check code against documented module and layer rules. Cross-view consistency is still mostly checked by hand — which is what the mapping between views is for |
| Selection of the wrong set of views | No rule picks the views for you. The right set depends on the system's nature and complexity, on the experience of the stakeholders and the architect, and on the time available. The best tool is an explicit analysis of the significant concerns — the stakeholder × view matrix below |
| Fragmentation | Every view costs effort to write and maintain, and too many make the AD hard to navigate. Drop views that address no significant concern. A hybrid view — deployment plus concurrency, say — can replace two thin ones, but a hybrid that serves too many concerns becomes hard to read in its turn |
Selecting which views to write
The SEI method is mechanical and worth copying: interview stakeholders to understand their needs, views and concerns — bearing in mind many stakeholders will say they want everything — then specify how much detail each stakeholder actually needs, using a simple three-level scale per view:
| Code | Meaning |
|---|---|
| d | Detail |
| s | Some information |
| o | Overview only |
Build the stakeholder × view matrix, fill it with d/s/o, and the view set — and the depth of each view — falls out of it. This is what stops you writing a Deployment view in loving detail for an audience that needed one paragraph. An illustrative fragment, for a generic web product rather than Lumen:
| Stakeholder | Context | Functional | Information | Deployment | Operational |
|---|---|---|---|---|---|
| Sponsor | s | o | o | — | — |
| Developers | s | d | d | s | o |
| Operations | o | o | s | d | d |
| Security auditor | s | o | d | d | s |
Read it by column: every view with a d somewhere must be written in full; a view with only o and s is a page in the overview, not a chapter. A column of dashes is a view you do not write.
Integration and interface documentation
Interfaces are documented as part of a view, in the element catalog. If the document is standalone, additional sections are required — for example system context. Integration documentation has a distinct readership of its own — the developer implementing the interface, the developer consuming it, the tester validating it, business analysts and the project manager — and the central tension the document must resolve is finding a balance between usability and modifiability: expose enough for a consumer to integrate confidently, without exposing so much of the provider's internals that every implementation change becomes a breaking one.
Multiple resources are specified in a single document. However, having a separate document for each integration point is better from the development and change-management process perspective.
The SEI interface specification template
| Section | Content |
|---|---|
| 1. Interface identity | What this interface is, and its version |
| 2. Resources provided | The points of interaction — methods of an interface of a class, messaging endpoints, CRUD operations for a REST resource. An interface can be considered as a collection of resources. For each resource, document the three items below |
| → Resource syntax | Signatures of functions/services, arguments and data types |
| → Resource semantics | Visible behaviour — changes in externally visible state — and restrictions. Recommended to use preconditions, postconditions and some formal language |
| → Error handling | "Nominal flows are only the tip of the iceberg." Error conditions and exceptions: wrong arguments, wrong state, wrong environment |
| 3. Data type definitions | For the data passed and returned by the resources. Constants are more relevant for program interfaces |
| 4. Configuration parameters | And how they affect the semantics — a parameter that changes behaviour is part of the contract |
| 5. Rationale | The reasons and motivation behind the interface's design |
The full SEI template carries two further sections this condensed version folds away: a Quality attribute characteristics section stating the interface's own performance, capacity and availability commitments — including SLAs, when they exist — and a Usage guide giving worked examples, code snippets and sequence diagrams. Both are worth restoring whenever the interface is complex enough, or contractually significant enough, that reading the signature is not an adequate onboarding path for a consuming team.
Data mapping is usually highlighted but generally should be documented in a separate document; if provided inline it cannot serve as the integration contract.
Write the resource syntax in a machine-readable form where one exists: OpenAPI (3.1, or 3.2 released in 2025) for HTTP APIs, AsyncAPI 3 for message and event interfaces. Those specifications cover syntax and data types well and semantics, error handling and quality commitments thinly — the template's other sections are what they leave out. Contract tests, in which each consumer's expectations run as tests against the provider (Pact is a common tool), keep the description and the implementation from drifting apart. And check for an industry standard before inventing a format: in healthcare, HL7 FHIR defines ServiceRequest, Appointment and Slot resources that map closely onto a referral, a booking and a partner's availability.
Architecture Decision Records
Views capture what the architecture is. ADRs capture why, one decision at a time, in a lightweight file that lives beside the code.
The technique comes from Michael Nygard's 2011 post Documenting Architecture Decisions; adr.github.io now collects the community templates and tooling that grew out of it. The value for a solution architect is direct: the Rationale sections of your views answer "why this design", but an ADR log answers "why this design rather than the alternative we rejected in March" — which is the question that actually arrives six months later, usually from someone new.
Nygard's record is short by design: a title, its status (proposed, accepted, deprecated or superseded), the context that forced a decision, the decision itself, and the consequences — both the benefits and the costs you are accepting. His template has no field for the options you rejected; templates such as MADR add a considered options section, and that is what lets the log answer the "rejected in March" question. A superseded ADR is never deleted; it is marked superseded and linked to the one that replaced it, so the reasoning chain survives.
This pairs naturally with the Timely and evolutionary documentation attribute above: you cannot write a big up-front design honestly, but you can record each decision as it is made.
Keep ADRs — and the SAD itself — as text in the repository (arc42 publishes Markdown and AsciiDoc versions of its template), with diagrams as code (Module 5). Documentation changes are then reviewed in the same pull request as the code they describe, which is the cheapest way to keep the two in step.
Documenting a service-oriented solution
View-based documentation organises by structure. When the solution is a set of collaborating services, an alternative that often reads better is to organise by service, with an identical template repeated for each one. The repetition is the feature — it makes the document navigable, and a missing section becomes obvious.
A workable per-service template:
| Section | Content |
|---|---|
| Role in business processes | Which processes the service participates in, and what it contributes to each |
| Interfaces | Contracts provided and consumed, each documented per the interface template above |
| Externally observable structure | What a consumer can see — deliberately excluding internals |
| Externally observable state | The state consumers may depend on, and its lifecycle |
| Coordination and ordering | How it sequences with other services; what ordering guarantees it offers and requires |
| Constraints | What limits it — capacity, licensing, data residency, ownership |
| Quality attribute behaviour | Its share of the performance, availability, disaster-recovery and security budgets |
That last row is the one teams skip, and it is the one that makes the document useful. A service description without its share of the budget cannot be held to anything. How to split a system-level budget into those shares is in Module 3.
SAD templates worth starting from
Do not invent a document structure. Start from a published one and adapt it — then record why you adapted it.
| Template | Source | Character |
|---|---|---|
| Views and Beyond | SEI, Documenting Software Architectures | View-centric. Strongest when the architecture's difficulty is structural. It splits each view into view packets — small, self-contained chunks, each carrying the sections from How to describe a view above, sized so one reader can take one in at a sitting |
| arc42 | arc42.org, freely licensed | Twelve standard sections, every one of them optional — keep only what earns its place. Deliberately lean, and the most practical default for a team that will actually maintain the document. It explicitly includes architecture decisions (section 9), quality requirements (section 10) and risks and technical debt (section 11) |
| TOGAF Architecture Definition Document | The Open Group | Enterprise-oriented, aligned to the ADM phases. Strongest where the solution must demonstrably fit an existing enterprise architecture. It carries baseline and target architectures, a gap analysis between them and the transition architectures that close the gaps — the spine below |
| Corporate outline | Most consultancies have one | Typically a Baseline → Target → Transition spine, which is the right shape for brownfield engagements. Worth reproducing even if you use a different template, because it forces the migration question |
The Baseline → Target → Transition spine
Whatever template you start from, a brownfield engagement needs these four in sequence, and the reason is not bureaucratic:
Baseline architecture — what exists today, at enough detail to migrate from
Target architecture — what you propose, with risks, dependencies, assumptions
Gap analysis — what must be added, changed or retired to get from one to the other
Transition — the steps that close the gaps without stopping the business
Gap analysis is the step TOGAF makes explicit and corporate outlines usually skip. Set baseline against target, element by element — business process, data, application, technology — and mark each as kept, changed, new or retired. Every gap becomes a work package in the transition plan; a baseline element with no counterpart in the target was either retired on purpose or forgotten; TOGAF's gap matrix makes you say which.
Few engagements are truly greenfield. A genuinely new system with nothing to integrate or replace has no baseline, and there the section can go. But most "new platforms" are brownfield underneath. Lumen is one: the scheduling platform is new, yet it must integrate with the existing referral management system, patient identity service and corporate SSO, and it replaces a manual phone-and-email process that the referral desk runs every day. Its baseline is mostly business process and interfaces rather than software to migrate, and its Transition — the case allows a phased roll-out by region — is where the risk lives. In a brownfield engagement the section teams most often omit is Transition, which is where the actual difficulty is.
Mark every section with its obligation
The single most useful adaptation to any template is to annotate each section with whether it is Mandatory, Recommended, or Optional for this engagement, and delete what is neither. This is what makes a template adaptable rather than a checklist to fill blindly — and it converts "the document is incomplete" into a decision someone made on purpose.
A component record worth repeating
For each architecturally significant component, in both baseline and target:
| Field | Content |
|---|---|
| Purpose | What the component is for, in one or two sentences |
| Technology stack | Principal frameworks, libraries, runtimes and managed services |
| Related components | Each relation named, with the nature of the relation — calls, publishes to, reads from, is deployed with |
| Requirements covered | Which functional requirements and which quality attribute scenarios this component satisfies |
| Notes | Anything else a reader needs, including known debt |
That fourth field is the traceability hook, and its absence is the most common serious defect in architecture documents: a design that never states which requirement it satisfies cannot be reviewed, and quality attribute requirements silently go unaddressed.
A sample Lumen SAD outline
Guidance on structure, not the answer: arc42's twelve sections, plus the two chapters a brownfield, integration-heavy bid needs and arc42 does not have, each mapped to the earlier Task output that feeds it. Whether each section is Mandatory, Recommended or Optional for Lumen is your call in the Task.
| arc42 section | What goes there for Lumen | Built from |
|---|---|---|
| 1. Introduction and goals | Drivers, SMART objectives, the top three quality goals, the stakeholder register | Module 2; Module 3 utility tree |
| 2. Architecture constraints | Supplier-hosted service, TLS 1.3, health-data regulation in each region, first release within 12 months | Module 3 constraints; the case |
| 3. Context and scope | Users, the referral system, identity service, SSO, the automated partner API, email and SMS providers | Module 5 context diagram |
| 4. Solution strategy | The style decisions for search, the offer workflow and partner integration, and why | Module 4 decision note and ADD iteration |
| 5. Building block view | Container diagram and element catalogue, including the requirements each container covers; component views only where a container is complex | Module 5 container diagram |
| 6. Runtime view | The few flows where order and failure matter: offer to booking, one referral-sync run | Module 5's booking-flow example; your own referral-sync sequence diagram (draw it here if you skipped it in Module 5) |
| 7. Deployment view | Per-region topology, the encryption path, the reporting path | This module |
| 8. Cross-cutting concepts | Identity and SSO, audit, configuration and rules, notifications, data residency | Module 3 tactics |
| 9. Architecture decisions | The ADR log | Module 4 decisions, rewritten as ADRs here |
| 10. Quality requirements | Utility tree and six-part scenarios, keeping their IDs | Module 3 |
| 11. Risks and technical debt | The RAID log's risks, and the case's open questions: how Lumen's own centres publish availability, and how Billed reaches finance | Module 2 RAID log; the case |
| 12. Glossary | Referral, study, slot, offer, partner group and the other domain terms | Module 2 |
| Added: Baseline, gap analysis and transition | Today's manual process and the existing systems, the gap list, the regional phasing | The case; this module |
| Added: Interface descriptions | The referral system's change extract and the automated partner API, in the SEI template | This module |
Check yourself
- Why can't one diagram describe an architecture, and what stops you writing every view you can think of?
- What is the difference between a view, a viewpoint and a perspective? Give a Lumen example of applying a perspective.
- A colleague says, "The container diagram is our logical view." What is wrong with that?
- Why is Lumen brownfield although the platform is new, and what goes in its Baseline?
- In the interface template, why does error handling deserve as much space as the nominal flow? Give one error case for the referral extract.
- What does an ADR record that a view's Rationale section usually does not?
- Your stakeholder × view matrix gives the Scheduling Manager "o" for Deployment and "d" for Functional. What does that change in the SAD?
- What does Views and Beyond mean by documentation "beyond views", and which part of it is most often missing?
Suggested answers
- Stakeholders have different concerns, and a single model that tries to serve all of them serves none — Rozanski and Woods's principle. The limit is cost: every view must be written and kept consistent with the others, so the d/s/o matrix decides which views earn their place.
- A viewpoint is the template and conventions for a kind of view; a view is that viewpoint applied to this system; a perspective is quality-focused guidance applied across views. Applying the Regulation perspective to Lumen's Deployment and Information views produces region-bound data stores — changes to existing views, not a new "compliance view".
- Kruchten's logical view decomposes the system into key domain abstractions, independent of how it runs. A container diagram shows runnable units, technologies and protocols, which is closer to the process and physical views; calling it the logical view leaves the domain view undrawn.
- The platform must integrate with the existing referral management system, patient identity service and SSO, and it replaces a manual process. The baseline is those systems' interfaces plus the manual phone-and-email process, with its volumes and cost; the gap analysis and the regional transition follow from it.
- Nominal flows are the easy part; integrations fail in the cases nobody wrote down. For the extract: a run that arrives late or not at all, a run delivered twice, an amendment that arrives before the referral it amends, or a cancellation of a referral that is already booked.
- The options that were rejected and why, the context at the time the decision was made, and a status that changes over time — superseded, not deleted — so the reasoning survives later changes.
- The Scheduling Manager needs only an overview of deployment, so the detailed deployment material can be written for operations. The functional view must be detailed enough for them — workflow, configuration and reporting — and the documentation roadmap should send them there.
- The documentation roadmap, the system overview, the mapping between views, the cross-view rationale and the glossary. The mapping between views is the part most often missing, and its absence is how views drift apart unnoticed.
Exercises — Module 6
Task. Write a Software Architecture Document for Lumen Diagnostics, assembled from your earlier Task outputs and extended. Output: an adapted SAD of about 12–20 pages, or the same as Markdown in a repository, containing: a purpose note for every section; a stakeholder × view matrix (d/s/o); 3+ views, each with a primary presentation, element catalogue and rationale, mapped to requirements; interface descriptions for the referral management system and the automated partner API, using the interface template; at least 3 ADRs; and Baseline, Gap analysis and Transition sections. Time: about 6 hours. Inputs: the case; your Module 2 business-architecture pack; your Module 3 ASRs and utility tree, keeping their IDs; your Module 4 style decisions and ADD iteration; your Module 5 context and container diagrams. Start from arc42, SEI Views and Beyond, or the TOGAF Architecture Definition Document.
Template
- Read the Lumen Diagnostics case
- Start from a public template: arc42, SEI Views and Beyond, TOGAF Architecture Definition Document, or a corporate outline
- Adapt the structure
- Mark each section Mandatory, Recommended or Optional for Lumen, and delete what is none of these
- Keep Baseline, Gap analysis and Transition: Lumen is brownfield (see the spine above)
- Remove the template's help text
- Add any chapter you think is missing — arc42, for one, has no Baseline or Interfaces chapter
- For each remaining section, note its purpose and what belongs there (filling every detail is optional)
- Add a short documentation roadmap: which stakeholder reads which sections
Fill from earlier Tasks
- Business architecture: drivers, objectives, stakeholders (Module 2)
- ASRs, utility tree and tactics, with their IDs (Module 3)
- Style decisions and the ADD iteration (Module 4)
- Context and container diagrams (Module 5), updated wherever the SAD changes them
Views
- Build the stakeholder × view matrix (d/s/o) from your Module 2 stakeholder register, and let it choose the views and their depth
- Pick a views school — C4, SEI, 4+1 or Rozanski & Woods — and say why
- Document 3 or more views, each with a primary presentation, element catalogue and rationale
- Add the mapping between views: at least, which containers deploy where
- Map every view element, interface and ADR back to requirement IDs in one trace table
Interfaces and decisions
- Referral management system: the 15-minute change extract — new referrals, amendments and cancellations; what a late, missing or repeated extract does; and the limit the extract puts on how fresh the platform can be
- Automated partner API: availability and booking resources, timeouts and retries, idempotency, and what happens when the slot has already gone
- Label every assumption: the case describes neither interface in detail
- Write at least 3 ADRs from your Module 4 decisions, each naming an option you rejected and why
Self-assessment
| Criterion | What good looks like |
|---|---|
| Built on earlier work | Your Module 2 stakeholders, Module 3 ASR IDs, Module 4 decisions and Module 5 diagrams all appear, reused and updated rather than redone, and element names match across them |
| Views chosen, not collected | The d/s/o matrix exists and explains every view you included; nothing is written in detail for readers who needed only an overview |
| Every requirement traced | Each ASR ID maps to at least one view element, interface or ADR, and each significant element to at least one requirement. Gaps are listed as open issues, not hidden |
| Interfaces fit to build against | Both descriptions cover resources, semantics, error handling and data types. The referral one says what the 15-minute extract means for freshness; the partner one covers timeouts, retries and a slot that has gone |
| ADRs that record a choice | At least three, each with its context, the options considered (including one rejected, and why), the decision, and the costs being accepted |
| Brownfield spine present | Baseline (existing systems and the manual process), a gap analysis and a transition phased by region. Nothing deleted as "greenfield" |
Worked answer — Lumen physical view
Attempt the Task first. This is one of the views your SAD could contain, worked for comparison.
The physical view, drawn for one region: two or more symmetric application nodes, each running the portal front end, the offer-and-confirmation service and the notification worker, behind an edge load balancer; a regional managed database with read replicas; a regional search cluster. It is drawn per region because data residency (Module 3, QA05) makes the topology repeat rather than centralise.
Two things in it answer requirements that a simpler drawing misses:
- Encryption on every hop. Public TLS 1.3 terminates at the edge, where the web application firewall has to inspect requests. Traffic is then re-encrypted to the application nodes with TLS 1.3, ideally as mutual TLS (mTLS), in which both ends present certificates so each tier also authenticates its caller — and the database and search connections use TLS too. The case requires encrypted transport for all authenticated traffic (QA09), so a clear-text hop inside the private network would fail it.
- Reporting that respects residency. Patient-level operational reports run in the region, against a reporting replica rather than the primary, so a heavy report cannot slow bookings (a lighter form of Module 3's separate-read-model tactic). Lumen-wide utilisation, partner and financial reporting — the case's centralised reporting — receives only aggregates without patient identifiers, and those aggregates are the only data that crosses the regional boundary.
Assumptions to confirm with Lumen: that each jurisdiction's regulation, including the new one outside the current jurisdiction, treats such aggregates as non-patient data — pseudonymised records usually still count as personal data (under the GDPR, for example), which is why the design aggregates rather than pseudonymises; and where the central store is hosted. The view leaves out the integrations (referral extract, partner API, identity provider), disaster recovery and the non-production environments; a complete deployment view adds them.