Architecture description (the Blueprint) and its sections
- Status
- Review
- Version
- 0.1.5
- Authority
- UASK standard
- Applies to
- Core
Summary
A project’s Blueprint is its architecture description: the document that says, for the people who care, how the system is built and why. It uses the vocabulary of ISO/IEC/IEEE 42010 (stakeholder, concern, viewpoint, view, correspondence, rationale) and the section order of arc42 (by reference; the text is the Hub’s own), with C4 for the diagrams and an ADR for each hard choice. It has twelve sections and one annex. A governance tier marks each section required or optional, so a small project writes a short Blueprint and a high-assurance project writes the whole of it.
Rules
Stakeholders, concerns and views
- R1. A Blueprint MUST name its stakeholders and, for each, the concerns the architecture has to answer. Each section MUST say which concern it answers and for whom.
- R2. A Blueprint MUST state its top quality goals, three to five, in the first section, each with the stakeholder who cares.
- R3. Views MUST be drawn as
arch.c4-modelrequires, and that item says which diagrams each tier needs: level 1 (system context) and level 2 (containers) by default, level 3 where a container is too complex to understand without it, a deployment diagram for section 7 and dynamic diagrams for section 6 (arch.c4-model#R9,arch.c4-model#R13). - R4. Where one fact appears in two sections (an interface in section 3 and in section 5; a database in section 5 and in section 7), the Blueprint MUST state the correspondence, so that a change to one is checked against the other.
Sections
- R5. A Blueprint MUST contain the sections its tier requires, in the order of the table under Guidance. A section that does not apply MUST say “none” and MUST NOT be left out.
- R6. Section 3 MUST list every external interface of the system (redirects, webhooks, scheduled jobs, DNS, mail, hosting settings, third-party services) with a contract or an owner for each.
- R7. Section 7 MUST state the environments, the delivery path, backup and restore, and monitoring. When the system replaces a live one, it MUST also state the cutover and the rollback.
- R8. Cross-cutting concepts (security, privacy, accessibility, language support, observability, licensing) MUST each be tied to the requirement ids they serve.
- R9. At the standard tier and above, section 10 MUST give a quality scenario (source, stimulus, environment, response, measure) for each top quality goal.
- R10. At the standard tier and above, the annex MUST map every functional and non-functional requirement to a section of the Blueprint, or say “deferred to” a named milestone.
Decisions and rationale
- R11. Every significant or hard-to-reverse choice MUST be recorded as an ADR (
arch.adr) and linked from section 4 or section 9; no decision stands without a recorded reason. - R12. Section 4 MUST state the governance tier of the project and the reason for it (
mgmt.governance-tiers).
Citing arc42
- R13. An item or a template that follows arc42’s section structure MUST name arc42, with its edition, under
standards:and in its Sources section with its address and licence. It MUST NOT list arc42 undersources:, and MUST NOT copy arc42’s text. Text adapted from arc42 MUST go undercontent/adapted/arc42/with attribution, under the licence arc42 carries (CC BY-SA 4.0).
Guidance
The vocabulary of ISO 42010
The Hub takes the terms and not the wording of the standard. This is what each term is in a project.
| Term | In a UASK project |
|---|---|
| Stakeholder | A person or group with an interest in the system: the owner, a client, users, the people who run it. Listed in section 1. |
| Concern | Something a stakeholder needs from the architecture: cost, safety of data, ease of change, time to market. Each is answered in at least one section. |
| Viewpoint | The convention for a kind of view: for example “C4 level 2, containers, for the people who build and run it”. |
| View | What a section shows, drawn by a viewpoint’s convention: a diagram with its text. |
| Correspondence | A stated link between two views, such as “this interface in section 3 is the same as that container in section 5”. |
| Rationale | Why a choice was made. In the Hub it is the ADR. |
The sections
R means required and O optional, at the lightweight (L), standard (S) and high-assurance (H) tier. The tier definitions
live in mgmt.governance-tiers and are not repeated here.
| # | Section | Must say | L | S | H |
|---|---|---|---|---|---|
| 1 | Goals and stakeholders | 3 to 5 top quality goals; stakeholders and their concerns | R | R | R |
| 2 | Constraints | technical, organisational, legal, platform | R | R | R |
| 3 | Context and scope | C4 level 1; the external interface inventory, with a contract or owner per interface | R | R | R |
| 4 | Solution strategy | key choices with links to ADRs; the governance tier and why | R | R | R |
| 5 | Building blocks | C4 level 2, and level 3 where needed; dependency rules and the checks that enforce them | R | R | R |
| 6 | Runtime | key scenarios as dynamic diagrams, in the sequence style or the collaboration style | O | R | R |
| 7 | Deployment and operations | environments and the deployment diagram of production (a table of environments at the lightweight tier, arch.c4-model#R9), delivery path, backup and restore, monitoring; cutover and rollback when it replaces a live system |
R | R | R |
| 8 | Cross-cutting concepts | security, privacy, accessibility, language support, observability, licensing, each tied to requirement ids | O | R | R |
| 9 | Decisions | the ADR index with status and the owner-level flag | R | R | R |
| 10 | Quality requirements | a quality scenario for each top goal | O | R | R |
| 11 | Risks and technical debt | likelihood, impact, mitigation; a debt register | R | R | R |
| 12 | Glossary | or a link to the project’s domain glossary | O | O | R |
| A | Annex: requirements coverage and implementation sequence | every requirement mapped to a section, or “deferred to” a milestone | O | R | R |
Mapping the earlier ten-section Blueprint
The template that the Hub shipped before has ten sections. They all map into the list above, so an existing Blueprint
can be read against it. The template templates/blueprint.md is on the twelve sections (version 2); the earlier one is kept as templates/blueprint-v1.md.
| Earlier section | Goes to |
|---|---|
| System overview | sections 3 and 5 |
| Building blocks | section 5 |
| Data and interfaces | sections 3, 5 and 8 |
| Technology stack | section 4 |
| Cross-cutting concerns | section 8 |
| Deployment and operations | section 7 |
| Cutover and rollback | section 7 |
| Requirements coverage | annex A |
| Risks | section 11 |
| Implementation sequence | annex A |
One thing moves: mgmt.governance-tiers#R1 asks for the tier under “Cross-cutting concerns”, which this table sends to
section 8. In a Blueprint on the twelve sections the reason for the tier is written once, in section 4 (R12), because
it is a choice about the solution and the way of working and not a cross-cutting concept. The value is also declared
in the Blueprint’s front matter (tier:, template version 2), and that declaration is the one a checker reads. A Blueprint
that is still on the earlier ten-section template records the tier under “Cross-cutting concerns”, as mgmt.governance-tiers says,
until it moves to version 2.
What the sections borrow, and what the Hub adds
- Section order follows arc42’s twelve sections. Our text is our own; see R13.
- Diagrams follow C4. Level 1 and level 2 are the default; level 3 is for a container that needs it; the deployment
and dynamic diagrams are the ones sections 7 and 6 draw (
arch.c4-model). - Decisions use the ADR fields of MADR: options, outcome, consequences and confirmation. The owner-level flag is the Hub’s own.
- Quality scenarios (
arch.quality-attributes) use the nine quality characteristics of ISO/IEC 25010:2023 as vocabulary: functional suitability, performance efficiency, compatibility, interaction capability, reliability, security, maintainability, flexibility and safety. - Solution design takes the idea of “alternatives considered” from the design doc.
- Added by the Hub: the external interface inventory (section 3), the operability points and the cutover and rollback (section 7), and the requirements annex. Reviews of past projects found their worst gaps in exactly these.
Writing a short Blueprint
At the lightweight tier a Blueprint of two pages is enough: goals and stakeholders, constraints, a context diagram with the interface list, the strategy with ADR links, one container diagram, deployment and backup, decisions and risks. Say “none” for what does not apply. It grows by adding sections as the tier rises; it does not need rewriting.
Keeping the Blueprint true
The Blueprint says what is built, so it changes in the same pull request as the code that changes it. A release spec
(process.release-spec) states which Blueprint sections the release changes. A rule that the Blueprint states, such as a
dependency rule, should become an automatic check, so that the document and the code cannot drift apart without a
failure.
Explanation
Why an architecture description. Systems live longer than the people who designed them. ISO/IEC/IEEE 42010 gives the vocabulary for describing an architecture so that different readers find what they need: who cares, about what, and which view answers them. The Hub took the vocabulary, because it is precise and neutral, and nothing else, because the standard’s text is not open to copy.
Why arc42’s order. arc42 is a widely used template of twelve sections with answers to the questions that come up in
reviews. Using its order lets a reader who knows arc42 find their way at once. Its text is licensed CC BY-SA 4.0; the
Hub’s licence rules (ADR-0005) confine anything adapted from it to content/adapted/. Structure cited by reference, with
no text adapted, is not an adaptation: that is the Hub’s reading of ADR-0005, which ADR-0008 (accepted) records,
and R13 keeps to it.
Why the additions. Reviews of past projects found the same gaps again and again: the world outside the system (redirects, cron jobs, mail, DNS), what happens in operation (backup, restore, rollback, monitoring) and which requirement landed where. They are now required, at the tiers where a miss costs the most.
Why tiers. A two-page Blueprint for a small script and a full one for a distribution of an operating system are both correct. Marking each section as required or optional by tier lets the same structure scale.
Examples
Good. A Blueprint for a small shop at the standard tier opens with three quality goals (checkout availability, page speed on phones, safe handling of customer data), each with its stakeholder. Section 3 lists eleven external interfaces, among them the payment webhook, the nightly order export and the mail relay, each with an owner. Section 7 has the cutover steps and the rollback, with the backup and the time to restore. Each hard choice links to an ADR. The annex maps FR-1 to FR-23 to sections, and FR-24 to “deferred to M3”.
Bad. A Blueprint that is one container diagram and a technology list. It says nothing of who cares about what, so no one can tell whether it answers their concern; it lists no external interface, so the first cutover breaks the payment notifications; and its choices are stated as facts with no ADR, so nobody can tell later why it was built that way. Rules R1, R6 and R11 are missed.
Sources
- The C4 model for visualising software architecture — CC BY 4.0; the levels and the supplementary diagrams. Accessed 2026-11-21.
- MADR 4.0.0 — Markdown Architectural Decision Records — MIT OR CC0-1.0; the decision fields. Accessed 2026-11-21.
- Malte Ubl, “Design Docs at Google” — all rights reserved; the idea of alternatives considered, paraphrased, not copied. Accessed 2026-11-21.
- ISO/IEC/IEEE 42010:2022 (architecture description) — referenced by name and edition only; the terms stakeholder, concern, viewpoint, view, correspondence and rationale are used, and none of the standard’s wording.
- arc42 template, edition 9.1 (October 2026) — licence CC BY-SA 4.0; referenced for its twelve-section structure only; no text is adapted (R13).
- ISO/IEC 25010:2023 (product quality model) — referenced by name only; the nine characteristic names are used as vocabulary.