Authoring Blueprints

Fragment

reference

The mental model

A blueprint is an architectural design document — it captures how a feature or system concern is implemented. While domains define what the system knows and features define what users can do, blueprints answer: “What is the structure of the solution, and what rules govern its construction?”

Blueprints bridge the gap between specification (what) and implementation (how). They are the place where technology choices, component topology, and wiring decisions are recorded.

Two archetypes

Blueprints come in two forms:

Feature blueprints — implement specific features. They declare implements="feature/add-bookmark" and describe how that capability is realized in code.
System blueprints — describe cross-cutting architectural concerns (layering, infrastructure, security posture). They omit implements and apply broadly.

The type attribute further classifies: infrastructure, architecture, module, or plan.

When to create a blueprint

Create a blueprint when:

A feature requires non-trivial architectural decisions (not just CRUD)
You need to communicate component relationships and boundaries to the team
Implementation rules or constraints need to be explicit and enforceable
Multiple developers will work on interconnected components

Do not create a blueprint for straightforward features where the architecture is obvious from the domain and feature specs.

Core sections

Approach

Every blueprint must have exactly one {% approach %} — a concise statement of the chosen strategy and rationale. This is the “thesis statement” of the design.

Components

Components are the building blocks. Each has an id, optional layer and tech attributes, and can declare {% uses %} relationships to other components.

Rules

Blueprint rules are implementation constraints that state what must or should hold during development. Rules can reference manifest NFRs for traceability via the ref attribute.

Links and diagrams

Use {% link %} for external references and {% diagram %} for Mermaid diagrams that visualize component relationships.

Relationship to domains and features

Domains define the business model and API — blueprints do not redefine them. Features define requirements — blueprints explain how to satisfy them. Blueprints reference both: they implement features and their rules may ref manifest constraints. The flow of information is top-down: manifest constraints become blueprint rules, domain APIs become component contracts, and feature requirements define what the blueprint must achieve.

Common mistakes

Mistake	Why it hurts
Too detailed	A blueprint is not implementation code. Describe topology and rules, not every function signature.
Duplicating the domain model	If you rewrite the DBML from the domain, you have two sources of truth. Reference, do not repeat.
No approach statement	Without a clear “why this architecture,” the blueprint is just a parts list with no rationale.
Orphaned blueprint	A blueprint that does not `implement` a feature and is not a system blueprint serves no purpose.
Premature creation	Writing a blueprint before the feature requirements are stable leads to rework. Specify first, design second.
Missing rules	Components without governing rules leave architectural decisions implicit and unenforced.

Evolution

Blueprints evolve as implementation reveals new constraints. Add components as they emerge, tighten rules as invariants become clear, and update diagrams to reflect current architecture. When a blueprint grows beyond a single concern, extract a sub-blueprint for the new concern.