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 section | Where | Required |
|---|---|---|
title | front matter | required |
status | front matter | required |
version | front matter | required |
date | front matter | required |
owner | front matter | required |
| System overview | section | required |
| Building blocks | section | optional |
| Data and interfaces | section | optional |
| Technology stack | section | required |
| Cross-cutting concerns | section | optional |
| Deployment and operations | section | optional |
| Cutover and rollback | section | optional |
| Requirements coverage | section | optional |
| Risks | section | required |
| Implementation sequence | section | required |
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.
---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 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.
---title: Blueprintstatus: draft # draft | review | approved — only the owner sets approvedversion: 0.1.0date: YYYY-MM-DDowner: 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. -->
```mermaidflowchart 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. …