Module 6 — Architecture Documentation

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

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:

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: 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 perspectives to consider:

• Perspective from stakeholders' points of view — sponsor, PM, dev, devops
• Perspective from a details point of view — conceptual, logical, physical
• Perspective from a domain point of view — data, application, technology

A short history of architectural views

Kruchten's 4+1

| +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 was proposed by Simon Brown as a simplified model providing great traceability from architecture design to implementation.

In order to create these maps of your code, you first need a common set of abstractions to create a ubiquitous language you can use to describe the static structure of a software system. It means that for your concrete project you need to define what elements you use, and what the meaning of these elements is — what the exact meaning of a container is, what container types you can have, what you call a component, and so on.

The course teaches C4 critically, using a financial risk system as the worked example:

A global investment bank based in London, New York and Singapore trades — buys and sells — financial products with other banks ("counterparties"). When share prices on the stock markets move up or down, the bank either makes money or loses it. At the end of the working day the bank needs to gain a view of how much risk of losing money it is exposed to, by running calculations on the data held about its trades. The bank has an existing Trade Data System (TDS) and Reference Data System (RDS) but needs a new Risk System.

The System Context diagram the critique below is actually about — reproduced here deliberately with the same gaps it calls out (generic "System" boxes, mixed arrow styles, no legend).

Do you see any issues with the Context diagram?

• No key or legend
• All external elements are represented as "Software Systems", which is really generic — they could be particular systems, like Microsoft Exchange
• Arrows are not always clear: what is the type of communication, what is the API provided by external systems? Only email message and SNMP are mentioned

Do you see any issues with the Container diagram? It provides the next level of detail through technology choices and by showing runtime components, with developers and operations (devops) as primary stakeholders. But:

• Too early for technology choice
• There is no mapping of functional/non-functional requirements to containers
• Difficult to use this approach with a complex solution

The Component diagram for the batch process has the same issues as the previous.

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

Style and view catalogue

Module styles and views cover the structure of implementation units.

Modelling non-relational storage — the course explicitly asks "do you have any idea how to model other storages?":

• 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 — modelling columns and super-columns; the same tools can be used; vendor-specific tools 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 — mind maps?

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. The concrete C&C views taught: monolith, service-oriented, and event-driven — 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 the ISO/IEC/IEEE 42010 standard that formalised it: 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, produced according to a viewpoint's conventions. The formulation to remember is that architects design structures; they document views of those structures. The standard itself 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 is a collection of architectural activities, tactics and guidelines used to ensure that the system exhibits a particular set of related quality properties.

Each view is directed by its viewpoint — its template and guidance. While a view describes the architecture, perspectives guide us through the process of analyzing 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

There are seven core viewpoints for information systems architecture. Although largely disjoint, it is convenient to group them:

The Functional, Information and Concurrency viewpoints characterize the fundamental organization of the system, and are grouped together to highlight that between them they define how the system provides its functionality.

The viewpoints on the right-hand side are to some extent driven by those on the left — for example the Development viewpoint defines standards and models for the construction of the architecture's functional, information and concurrency elements.

The directional version of the same relationships: everything ultimately constrains or is sketched from Design.

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

The conceptual model

An architecture is documented in an architectural description (AD).

• The AD consists of one or more views of the architecture. It may also include other elements such as principles, standards and glossaries, which lay the architectural foundations. For example an AD may include a Functional view, a Concurrency view and a Deployment view
• The contents of each view are based on a viewpoint. For example, the contents of an Operational view are based on the templates, patterns and guidelines in the Operational viewpoint
• Each view consists of one or more models. A model is a way to represent some of the salient features of an architecture pertaining to the view. For example, an Information view may include an entity-relationship model, a data ownership model and a state transition model
• Applying a perspective may lead to changes to existing models, or to the creation of one or more secondary architectural models that allow better understanding of the architecture's ability to exhibit a particular quality property — models that do not define one of the system's structures. For example, applying the Security perspective usually involves the creation of a threat model to understand the security threats the system faces

Why models are important: the key skill the model builder uses is abstraction — the process of suppressing unnecessary detail. By removing such detail from our models we allow our stakeholders and ourselves to focus on the most important aspects of our architecture. A good model can help stakeholders understand an architecture they might not understand otherwise.

Benefits and pitfalls of multiple views

Benefits

Pitfalls

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:

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.

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

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.

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, and the community has since standardised templates and tooling at adr.github.io. 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.

A minimal record is short by design: the context that forced a decision, the decision itself, its status (proposed / accepted / superseded), and the consequences — both the benefits and the costs you are accepting. 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.

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:

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.

Deriving quality attribute requirements from business arithmetic

This is the single most valuable technique in the course, and the one most often skipped. The usual failure is asking the customer "how many nines do you need?", receiving a number chosen by intuition, and designing to it. The alternative is to compute it.

Worked on Lumen's settlement subsystem — the component that submits completed studies for payment.

Step 1 — establish the unit economics

Two consequences fall straight out:

• One manual rework erases the margin on ~3.7 successfully settled studies ($11.60 ÷ $3.10). That is the argument for a low failure rate, expressed in a currency the business already uses
• An hour of outage costs ~$104,400 (9,000 × $11.60), because submissions that cannot be processed automatically become manual rework

Step 2 — turn a cost appetite into an availability figure

Suppose the business will tolerate $250,000 per year in outage cost — a number a finance director can actually opine on, unlike "nines".

$$\text{tolerable outage} = \frac{$250{,}000}{$104{,}400/\text{hour}} \approx 2.4 \text{ hours per year}$$

$$\text{availability} = 1 - \frac{2.4}{8{,}760} \approx 99.97%$$

Cap a single incident at 15 minutes and 2.4 hours becomes a budget of roughly 10 incidents per year — which is now a statement operations can be measured against, and which tells you how much detection-and-recovery automation is worth building.

The direction of reasoning is what matters. Nobody asked for 99.97%; it was derived from volume, cost differential and arrival rate. This also answers "how much may I spend improving availability?" — any investment that removes outage hours and pays back against $104,400 per hour is justified, and one that does not, is not.

Step 3 — decompose the budget across components

A system-level number is unusable until each component knows its share. Four components sit in the settlement path, in series:

$$A_{\text{component}} = \sqrt[4]{0.9997} \approx 99.99%$$

The monthly reconciliation run covers ~600 partners at 8 s each, so the full batch must complete inside 2 hours — 80 minutes of work, leaving headroom for retries.

And then the tactic that makes those component figures achievable rather than aspirational:

To avoid placing an unreasonable availability demand on any single component, deploy at least two instances of each behind a health-checked balancer. Four components each needing 99.99% as a single instance would be an expensive and fragile promise; the same figure from a redundant pair is routine.

Note the corollary, which is where teams get caught: series composition multiplies. Adding a fifth component to this path drops the achievable total unless every component gets stricter. The cheapest availability decision available to an architect is usually removing a hop, not hardening one.

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.

The Baseline → Target → Transition spine

Whatever template you start from, a brownfield engagement needs these three in sequence, and the reason is not bureaucratic:

Baseline architecture   — what exists today, at sufficient detail to migrate from
Target architecture     — what you propose, with risks, dependencies, assumptions
Transition              — how you get from one to the other without stopping the business

Baseline applies only to brownfield. In a greenfield engagement there is no baseline architecture and the section should be deleted rather than filled with apologies. Conversely, in a brownfield engagement the section teams most often omit is Transition — which is where the actual difficulty lives.

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:

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.

Exercises — Module 6

Task. Write a Software Architecture Document for Lumen Diagnostics. Output: an adapted SAD with purpose-notes per section, prior homework filled in, and 3+ views mapped to requirements. 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

  • Drop chapters that do not apply (for example Baseline architecture on a greenfield)
  • Remove the template's help text
  • Add any chapter you think is missing
• For each remaining section, note its purpose and what belongs there (filling every detail is optional)

Fill from earlier Tasks

• Business Architecture
• ASRs and quality attributes

Views

• Pick a views school: C4, SEI, 4+1, or Rozanski & Woods
• Document 3 or more views, each with a short textual description
• Map each decision and view back to requirements