Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Blueprint v1

This template is not tied to a playbook stage.

Download blueprint-v1.md — the source, as in the repository.

How to use

The template's own instructions:

Frozen: version 1 of this template. An artefact without `template:` is checked against it and gets a warning; new work uses templates/blueprint.md (version 2). Do not edit.

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 sectionWhereRequired
titlefront matterrequired
statusfront matterrequired
versionfront matterrequired
datefront matterrequired
ownerfront matterrequired
System overviewsectionrequired
Building blockssectionoptional
Data and interfacessectionoptional
Technology stacksectionrequired
Cross-cutting concernssectionoptional
Deployment and operationssectionoptional
Cutover and rollbacksectionoptional
Requirements coveragesectionoptional
Riskssectionrequired
Implementation sequencesectionrequired

Example

A filled-in copy for an invented product, templates/examples/blueprint.md, in the Hub repository.This template is frozen; the example follows its current version.It shows the level of detail to aim for, not text to reuse.

example-blueprint.md
---
template: blueprint/2
title: Blueprint
status: draft
version: 0.1.0
date: 2026-03-02
owner: Product Owner
tier: 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
```mermaid
flowchart 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 owner has approved it, where the playbook asks for approval. Only the owner sets approved.

Source

templates/blueprint-v1.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.

blueprint-v1.md
---
title: Blueprint
status: draft # draft | review | approved — only the owner sets approved
version: 0.1.0
date: YYYY-MM-DD
owner: Product Owner
---
<!-- Frozen: version 1 of this template. An artefact without `template:` is checked against it and gets a warning; new
work uses templates/blueprint.md (version 2). Do not edit. -->
# Blueprint — Product name
<!-- Template from the UASK Engineering Hub, 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.
Sections marked "Optional" may be deleted; delete these comments when a section is written. -->
## System overview
<!-- A system context view (people, this system, external systems) and a container view, drawn as in
item arch.c4-model; diagrams as code (Mermaid or similar) kept in this file. Then one paragraph on how
responsibilities are separated. -->
```mermaid
flowchart LR
user["User<br/>[Person]"] -->|uses| sys["Product name<br/>[Software system]"]
sys -->|calls| ext["External system<br/>[Software system]"]
```
## Building blocks
<!-- Optional. Main modules or components, their responsibilities, and the repository layout. -->
## Data and interfaces
<!-- Optional. Data owned and its lifecycle; public interfaces, APIs, extension points, integrations. -->
## Technology stack
<!-- One row per concern; every choice that is hard to reverse links its ADR. -->
| Concern | Choice | Decision | Fallback |
|---|---|---|---|
| … | … | [ADR-NNNN](decisions/NNNN-….md) | … |
## Cross-cutting concerns
<!-- Optional. Security, privacy, performance, accessibility, observability, internationalisation,
licensing — each tied to the NFR ids it satisfies. State the governance tier here (lightweight,
standard or high-assurance — item mgmt.governance-tiers) with the reason; the owner chooses it. -->
## Deployment and operations
<!-- Optional. Environments, delivery path, backups and restore, rollback, monitoring. -->
## Cutover and rollback
<!-- Optional, but expected where the product replaces a running system. A sequence (flowchart or numbered
steps), 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 the PRD's
"External interfaces and environment". -->
## Requirements coverage
<!-- Optional, recommended. Which section covers each FR/NFR, or "deferred to Mn". -->
| Requirement | Covered by |
|---|---|
| FR-1 | … |
## Risks
<!-- What could make the plan fail, with a mitigation for each. -->
| Risk | Impact | Mitigation |
|---|---|---|
| … | … | … |
## Implementation sequence
<!-- Numbered steps from the first approval to the first release; the roadmap's milestones follow them. -->
1. Owner approves this blueprint and the proposed ADRs.
2. …