Blueprint
Used in the playbook Project foundation, stage 5.
Download blueprint.md — the source, as in the repository.
How to use
The template's own instructions:
Template from the UASK Engineering Hub, version 2 (item arch.architecture-description; playbook mgmt.project-foundation, stage 5). Save as project/BLUEPRINT.md. How the system is structured, built, delivered and run. Refer to requirements by id (PRD.md) and to evidence in research/. Mark every significant or hard-to-reverse choice with **[ADR-NNNN]** linking to decisions/NNNN-….md. While a record has no number yet, mark it [ADR-candidate D1], [ADR-candidate D2], … (unique within this file); the Decisions stage replaces each with a link, and none is left when it closes. Tiers: the front matter says which one the project is on. A section opening with "Required: <tiers>" is required at those tiers only; "Optional" means never required; no marker means required at every tier. A section that does not apply says "none" and stays (arch.architecture-description#R5); an optional one may go. The earlier ten-section template is version 1 (templates/blueprint-v1.md); an artefact without `template:` is checked against it and gets a warning. Delete these comments when a section is written.
Fields
Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).
| Field or section | Where | Required |
|---|---|---|
template | front matter | required |
title | front matter | required |
status | front matter | required |
version | front matter | required |
date | front matter | required |
owner | front matter | required |
tier | front matter | required |
| 1. Goals and stakeholders | section | required |
| 2. Constraints | section | required |
| 3. Context and scope | section | required |
| 4. Solution strategy | section | required |
| 5. Building blocks | section | required |
| 6. Runtime | section | required |
| 7. Deployment and operations | section | required |
| 8. Cross-cutting concepts | section | required |
| 9. Decisions | section | required |
| 10. Quality requirements | section | required |
| 11. Risks and technical debt | section | required |
| 12. Glossary | section | required |
| Annex A: Requirements coverage and implementation sequence | section | required |
Example
A filled-in copy for an invented product, templates/examples/blueprint.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.
---template: blueprint/2title: Blueprintstatus: draftversion: 0.1.0date: 2026-03-02owner: Product Ownertier: standard---
# Blueprint — Fieldnotes
## 1. Goals and stakeholders
1. Reliability: no saved note is ever lost (the researcher).2. Portability: every note is a plain file (the owner).3. Simplicity: a researcher syncs without learning Git (the team lead).
## 2. Constraints
- The app runs on Android and a desktop browser.- Open-source licences only.
## 3. Context and scope
```mermaidflowchart LR user["Researcher<br/>[Person]"] -->|writes notes| sys["Fieldnotes<br/>[Software system]"] sys -->|pushes and pulls| ext["Git host<br/>[Software system]"]```
| Interface | Direction | Contract or owner ||---|---|---|| Git over HTTPS | both | the user's Git host |
## 4. Solution strategy
| Concern | Choice | Decision | Fallback ||---|---|---|---|| Storage | Markdown files in Git | [ADR-0002](decisions/0002-notes-as-files.md) | database with export |
Governance tier: **standard** — reason: the app holds personal research notes, but no payments and a small user base.
## 5. Building blocks
The app has two containers: the note store (files and the search index) and the sync engine (Git). The sync engine only talks to the store through its file interface.
## 6. Runtime
A researcher saves a note: the editor writes the file, the store updates the index, the sync engine queues a commit. When a network is present the engine pushes the queue.
## 7. Deployment and operations
| Environment | Purpose | Notes ||---|---|---|| Device | production | the app is installed from a package; no server |
## 8. Cross-cutting concepts
Privacy: notes never leave the device except to the Git remote the user set. Accessibility: the editor follows WCAG 2.2 AA.
## 9. Decisions
| ADR | Decision | Status | Owner-level ||---|---|---|---|| [ADR-0002](decisions/0002-notes-as-files.md) | Store notes as plain files in Git | proposed | yes |
## 10. Quality requirements
| Goal | Source | Stimulus | Environment | Response | Measure ||---|---|---|---|---|---|| Reliability | researcher | the app is killed during a save | any | the note is intact on restart | 0 notes lost in 1 000 kills |
## 11. Risks and technical debt
| Risk | Likelihood | Impact | Mitigation ||---|---|---|---|| Merge conflicts confuse users | medium | medium | a conflict screen (FR-2); test with testers |
## 12. Glossary
Note: one Markdown file. Remote: the Git repository the user chose.
## Annex A: Requirements coverage and implementation sequence
| Requirement | Covered by ||---|---|| FR-1 | §5, §6 || FR-2 | §5, §6 |
1. Owner approves this blueprint and the proposed ADRs.2. Build the note store, then the sync engine.Completion checks
A copy is complete when:
- every required field and section above is present, in the same order, and no bracketed placeholder is left;
- the template's comments are deleted from the copy;
python3 .uask/hub/tools/check_artifacts.py .reports no failure for it: front matter, sections, ids, leftover placeholders and comments (tools/check_artifacts.py, in every release bundle);- the exit criteria of stage 5 of the playbook Project foundation are met;
- the owner has approved it, where the playbook asks for approval. Only the owner sets
approved.
Source
templates/blueprint.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.
---template: blueprint/2title: Blueprintstatus: draft # draft | review | approved — only the owner sets approvedversion: 0.1.0date: YYYY-MM-DDowner: Product Ownertier: standard # lightweight | standard | high-assurance — the owner decides (mgmt.governance-tiers); the reason goes in section 4---
# Blueprint — Product name
<!-- Template from the UASK Engineering Hub, version 2 (item arch.architecture-description; playbook mgmt.project-foundation, stage 5). Save as project/BLUEPRINT.md. How the system is structured, built, delivered and run. Refer to requirements by id (PRD.md) and to evidence in research/. Mark every significant or hard-to-reverse choice with **[ADR-NNNN]** linking to decisions/NNNN-….md. While a record has no number yet, mark it [ADR-candidate D1], [ADR-candidate D2], … (unique within this file); the Decisions stage replaces each with a link, and none is left when it closes. Tiers: the front matter says which one the project is on. A section opening with "Required: <tiers>" is required at those tiers only; "Optional" means never required; no marker means required at every tier. A section that does not apply says "none" and stays (arch.architecture-description#R5); an optional one may go. The earlier ten-section template is version 1 (templates/blueprint-v1.md); an artefact without `template:` is checked against it and gets a warning. Delete these comments when a section is written. -->
## 1. Goals and stakeholders
<!-- Three to five top quality goals, each with the stakeholder who cares (vocabulary: item arch.quality-attributes); the stakeholders and the concerns the architecture has to answer. -->
## 2. Constraints
<!-- Technical, organisational, legal and platform constraints, each with its source. -->
## 3. Context and scope
<!-- C4 level 1 (item arch.c4-model): people, this system, external systems; diagrams as code (Mermaid or similar) kept in this file. Then the external interface inventory (item arch.context-and-interfaces): every redirect, webhook, scheduled job, DNS record, mail flow, hosting setting and third-party service, each with a contract or an owner. The PRD's "External interfaces and environment" is the input. -->
```mermaidflowchart LR user["User<br/>[Person]"] -->|uses| sys["Product name<br/>[Software system]"] sys -->|calls| ext["External system<br/>[Software system]"]```
| Interface | Direction | Contract or owner ||---|---|---|| … | … | … |
## 4. Solution strategy
<!-- The key choices, each linked to its ADR, in one table; how the responsibilities are separated. State the governance tier (the value is also in the front matter) and the reason for it; the owner chooses it (mgmt.governance-tiers#R1, arch.architecture-description#R12). -->
| Concern | Choice | Decision | Fallback ||---|---|---|---|| … | … | [ADR-NNNN](decisions/NNNN-….md) | … |
Governance tier: **standard** — reason: …
## 5. Building blocks
<!-- C4 level 2 (containers), and level 3 where a container is too complex to understand without it (item arch.c4-model). The dependency rules between blocks and the checks that enforce them (item arch.building-blocks-and-dependencies, arch.fitness-functions). Where a fact also appears in section 3 or 7, state the correspondence (arch.architecture-description#R4). -->
## 6. Runtime
<!-- Required: standard, high-assurance — the key scenarios as dynamic diagrams (sequence or collaboration style, item arch.c4-model). -->
## 7. Deployment and operations
<!-- Environments and the deployment diagram of production (a table of environments at the lightweight tier), the delivery path, backup and restore, monitoring and who is told. When the product replaces a running system, also the cutover and rollback: a sequence, not a list of components - what is frozen or copied, what is switched in which order (addresses, DNS, notifications from external services, schedules), how each step is proved before the next, the point of no return, and how each step is undone and how long that takes. Cover every entry of section 3's interface inventory. From the standard tier, say how each value of the PRD's "Operability" section is met (item arch.quality-attributes#R8). -->
## 8. Cross-cutting concepts
<!-- Required: standard, high-assurance — security, privacy, accessibility, language support, observability, licensing; each tied to the requirement ids (FR-n, NFR-n) it serves. -->
## 9. Decisions
<!-- The index of the ADRs: number, title, status and whether the decision is owner-level (item arch.adr). -->
| ADR | Decision | Status | Owner-level ||---|---|---|---|| [ADR-NNNN](decisions/NNNN-….md) | … | proposed | yes |
## 10. Quality requirements
<!-- Required: standard, high-assurance — one quality scenario for each top goal of section 1: source, stimulus, environment, response and a measure (item arch.quality-attributes). -->
| Goal | Source | Stimulus | Environment | Response | Measure ||---|---|---|---|---|---|| … | … | … | … | … | … |
## 11. Risks and technical debt
<!-- What could make the plan fail: likelihood, impact, mitigation, and the owner of each; the debt register (item arch.risks-and-technical-debt). -->
| Risk | Likelihood | Impact | Mitigation ||---|---|---|---|| … | … | … | … |
## 12. Glossary
<!-- Required: high-assurance — the terms of the domain, or a link to the project's own glossary. -->
## Annex A: Requirements coverage and implementation sequence
<!-- Required: standard, high-assurance — which section covers each FR/NFR, or "deferred to Mn"; then numbered steps from the first approval to the first release; the roadmap's milestones follow them. -->
| Requirement | Covered by ||---|---|| FR-1 | … |
1. Owner approves this blueprint and the proposed ADRs.2. …