Blueprint template

When to use

• Shelf: build/blueprints/<topic>/
• kind: blueprint or planning doc before execution playbooks
• Diátaxis mode: explanation (design reasoning, not step-by-step ship)
• Readers served: architects and agents deciding what to build before how

Design rationale

• Blueprints record decisions, not procedures — ADR-style docs capture context, options, and consequences; execution belongs in playbooks (ADR overview).
• Problem before diagram — readers need the forcing function before boxes-and-arrows (C4 model — context first).
• Constraints as explicit section — unwritten constraints cause rework; listing them prevents “obvious” scope creep (arc42 section 1–2).
• Open questions section — perfectionist gate: ship the blueprint when known unknowns are listed, not hidden (architecture decision records — status).
• Diagram mandatory — relationship/structure between proposed parts triggers warrant test (ZajLibrary visuals).

Copy-paste skeleton

---
title: "<Blueprint name>"
description: One sentence — decision or system this blueprint captures.
kind: blueprint
status: draft
tags: [blueprint, topic]
---

## Problem

&lt;What pain or goal forces this design?&gt;

## Constraints

- &lt;Technical / time / policy constraint&gt;

## Decisions

### Decision 1 — &lt;title&gt;

- **Context:** …
- **Choice:** …
- **Consequences:** …

## Architecture

\`\`\`mermaid
flowchart TD
  …
\`\`\`

## Open questions

- [ ] &lt;Unknown 1&gt;

:::tip[Next]
When locked, execute via [Playbook](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) or [Runbook](/tech-stack/laravel/codecanyon/build/runbooks/code-test-ship/).
:::

Anti-patterns

• Do not use playbook step spine on a blueprint.
• Do not ship architecture without a diagram when components interact.
• Do not embed secrets or environment-specific credentials.

Worked example

• Blueprints hub (stub — replace when reference blueprint lands)

Sources

• Architecture Decision Records — decision-centric blueprint structure.
• arc42 template — constraints, context, and solution structure.
• C4 model — diagram levels and context-before-detail.
• Diátaxis — Explanation — blueprints explain design, they don’t instruct steps.
• Writing style → Doc-type spines