Blueprint Writing Guide

This is the canonical specification for writing Blueprints: technical specification documents authored in 8090 Software Factory.

Introduction to Blueprints

8090 Software Factory defines each product through two sets of complementary documents: Requirements and Blueprints. Requirements capture the externally expected outcomes and constraints through structured user stories and acceptance criteria; Blueprints are the technical specifications that define how the software system operates to satisfy those requirements. Both document types are authored as markdown and are intended to be readable as plain source documents while still supporting structured references and machine-assisted workflows.

In requirements-engineering terms, Requirements describe what must be true from the user and business perspective, while Blueprints describe how the system is structured and behaves to make that true. Blueprints allocate behavior to concrete runtime components, define the data/contracts that cross component boundaries, and describe the dependency and control flow that turns user intent into system behavior.

Together, Requirements and Blueprints form a complete product definition that is testable in both directions: each Blueprint should trace upward to Requirements and downward to real code symbols and runtime interactions.

Blueprint Categories

8090 Software Factory organizes Blueprints into three categories. In your project they appear as Containers, Components, and Feature Blueprints. The categories borrow terms from the C4 model, a common way to describe software architecture: a container is a deployable or runnable unit, and a component is a part inside it that does work.

Container Blueprints describe a single C4 container: a separately deployable or runnable unit in the system, such as a web application, API server, database, background worker, or build pipeline. A Container Blueprint documents the container's technology stack, runtime characteristics, cross-cutting concerns (for example, authentication, error handling, and observability), and the boundaries it presents to other containers. Container Blueprints are infrastructure-focused and feature-agnostic: they establish the deployment and operational context that Component Blueprints build within.

Component Blueprints describe a reusable system capability made of multiple C4 components: a cohesive group of services, controllers, hooks, strategies, and other runtime components that together power one capability. A Component Blueprint is the prose equivalent of a C4 component diagram: structured component blocks are the nodes, and the paragraphs between them are the relationship edges. Component Blueprints are feature-agnostic (they describe what the system can do, not what any one feature uses) and commonly span multiple C4 containers (for example, API Server and Client App). Most capabilities cross containers, because a single user action usually touches the user interface, API orchestration, background processing, and persistence.

Feature Blueprints describe how capabilities from Component Blueprints come together, plus any feature-specific components, to satisfy a set of product Requirements. Each Feature Blueprint corresponds to a Feature Requirements Document (FRD) and is its technical counterpart: Requirements say what; the Feature Blueprint says how. Feature Blueprints are composition-first: they wire shared capabilities together, configure them for the feature, and document feature-only glue.

Practical Example

Container Blueprints (for example, Client App, API Server, and Database) are usually set up at the start of a project and evolve as the infrastructure grows. From there, a typical flow looks like this:

1. A product manager defines features, such as "Checkout" and "Order Tracking". Creating a feature also creates its FRD and its Feature Blueprint, for example the Checkout FRD and the Checkout Feature Blueprint.
2. The product manager writes structured requirements into the FRDs, such as REQ-CHECKOUT-001 and REQ-CHECKOUT-002 for Checkout, and REQ-TRACK-001 and REQ-TRACK-002 for Order Tracking.
3. An engineer reads the requirements, identifies shared capabilities, and writes Component Blueprints for them. For example, Identity and Session Management contains components like AuthenticationService, SessionTokenStore, and UserProfileClient. Notification Delivery contains components like NotificationRouter, EmailDeliveryService, and SmsDeliveryService.
4. The engineer writes the Feature Blueprints. The Checkout Feature Blueprint composes Identity and Session Management plus checkout-specific components. The Order Tracking Feature Blueprint composes Identity and Session Management, Notification Delivery, and order-tracking-specific components.

The engineer's job is to identify the shared capabilities that underpin features, document them as Component Blueprints, and compose them into Feature Blueprints that map onto Requirements. Container and Component Blueprints form the system's foundation: Container Blueprints establish the infrastructure context early and evolve as the platform grows, and Component Blueprints capture reusable capabilities within and across those containers. Feature Blueprints are driven by product requirements and compose what the foundation provides. Ideally, Feature Blueprints are mostly composition, with feature-specific components only where needed. Components often start in a Feature Blueprint and move into a Component Blueprint once reuse emerges. That is expected.

Core Syntax and Semantics

Blueprint syntax defines the canonical structural elements that can appear in a Blueprint document (component and model blocks). Blueprint semantics define how those elements should be interpreted: what each element means, how elements relate across sections and documents, and how references map to runtime ownership, contracts, and behavior.

Component Blocks

Components are defined in structured code blocks that act as the nodes of the architecture. Put each component in a code block whose language is component (in markdown, a block that opens with ```component). It has three fields:

• name: PascalCase, matching the component's name in code.
• container: The C4 container or containers it runs in, as documented in a Container Blueprint. Separate several with commas (for example, Client App, API Server, Task Server, or Client App, API Server).
• responsibilities: A tab-indented bullet list (-) of what this component does. Use element mentions (`Name`) for data and contracts, and component mentions (`#Name`) for the components it depends on or works with, including components defined in other Blueprints.

Anything defined with a component block (for example, name: MyComponent) can be referenced as #MyComponent from any document.

Example:

```component
name: NotificationDeliveryService
container: API Server
responsibilities:
	- Selecting delivery channels based on `NotificationPreference` and message type
	- Rendering channel-specific payloads from `NotificationTemplate`
	- Dispatching messages through provider adapters with retry and idempotency guards
```

Model Blocks

Use a model block when a Blueprint needs an explicit, canonical data or domain model that is central to implementation but is not a runtime component. Put it in a code block whose language is model. It has five fields:

• name: Model name.
• store: Where the model is stored (for example, Postgres, S3, DynamoDb, or CacheMemory).
• description: Short statement of purpose.
• fields: Tab-indented bullet list of canonical fields and types.
• constraints: Invariant rules enforced by domain logic.

Models are mentioned with backticks like an element (see Mentions below).

Example:

```model
name: CustomerOrder
store: Postgres
description: Canonical persisted order model used by checkout, fulfillment, and support workflows.
fields:
	- id: UUID (required)
	- order_number: string (required)
	- customer_account_id: UUID (required; foreign key -> `CustomerAccount.id`)
	- status: Draft | Placed | Packed | Shipped | Delivered | Cancelled (required)
	- total_amount: decimal (required)
	- placed_at: datetime (nullable)
constraints:
	- unique `order_number`
	- `total_amount` is non-negative
	- `placed_at` is present when `status` is not `Draft`
```

Mentions

Blueprints use three mention types to create navigable links:

• `#ComponentName` for components (runtime behavior).
• `ElementName` for elements (data shapes and contracts).
• @SystemEntity for whole documents and platform entities.

The table below summarizes syntax, scope, and where each type is defined.

`#ComponentName`: a backticked hashtag for components (services, controllers, hooks, strategies, providers). These are things that have (or could have) a component block. Components are runtime things that do work. Examples: `#NotificationDeliveryService` , `#OrderLifecycleService`, `#CheckoutApiController`. Components defined in any Blueprint using the ```component block syntax can be mentioned this way from any other Blueprint; this cross-Blueprint referencing is how composition is expressed.

`ElementName`: backticks for elements, the architecturally significant code symbols that are not defined as components. These include schemas, configs, domain types, enums, request/response models, exceptions, feature flags, permission matrices, and models (including those defined in model blocks). Elements describe shape; they define contracts and configuration that components read, produce, or share. Request/response models and exception types are especially good as element mentions because their names are often self-documenting. Use the casing of the source language (for example, CustomerOrder, OrderStatus, NotificationTemplate, CheckoutRequest, CheckoutResponse). Element mentions don't create blueprint-to-blueprint dependency; multiple blueprints can mention the same element without implying a dependency.

@SystemEntity: an at-sign for other entities and documents in 8090 Software Factory, such as Requirements, Blueprints, Work Orders, and Knowledge Base files. Examples: @Checkout Requirements, @Order Tracking Feature Blueprint, @WO-123, @Customer Call Notes. These link to actual documents and entities in 8090 Software Factory.

When to use which: if it does work (processes, orchestrates, renders, fetches), use #Component. If it describes a shape or contract (schema, type, config, enum, model, request/response, exception), use Element. If it is a document (Requirements, Blueprint) or a Knowledge Base file in 8090 Software Factory, use @SystemEntity.

Example paragraph: #CheckoutApiController (see @Checkout Feature Blueprint) validates CheckoutRequest and calls #OrderLifecycleService to create a CustomerOrder. The service sets OrderStatus to Placed and then calls #NotificationDeliveryService with a NotificationTemplate. Here the # names are components with definitions somewhere; CheckoutRequest, CustomerOrder, OrderStatus, and NotificationTemplate are elements; @Checkout Feature Blueprint is a platform entity.

Writing Component Relationship Paragraphs

Relationships between components are described in natural language paragraphs that act as the edges of the architecture: what flows between components, who depends on whom, and why.

Key principles:

• Use each paragraph to connect concrete components defined in component blocks. Mention both components early so the edge is explicit.
• State the direction: who depends on whom.
• Use component mentions (#...) and element mentions (...) to add implementation detail and make the data flow clear, not as ends in themselves.
• Explain why the interaction exists, not just what it does.
• Cover one relationship per paragraph, in two to four sentences.
• Don't restate the component blocks' responsibilities. Describe the interaction and what crosses the boundary.

Container Blueprint Guidance

What They Are and When to Create One

A Container Blueprint is the technical specification for a C4 container: a separately deployable or runnable unit in the system. It documents the container's technology choices, runtime environment, cross-cutting infrastructure, and the boundaries it presents to components within it and to other containers. Container Blueprints are feature-agnostic and infrastructure-focused.

Create a Container Blueprint when: you're establishing or documenting a deployable unit, such as a web application, API server, task worker, data layer (schema management, migration strategy, access patterns), or CI/CD pipeline. Container Blueprints are especially valuable when the container has cross-cutting concerns like authentication, middleware, error handling, or observability that affect all components hosted within it, or when multiple Component Blueprints reference the same container and would benefit from a single source of truth about its characteristics.

Structure

1. Title and container summary: Start with the Blueprint title, then add ## Container Summary that names what the container is (web app, API server, worker, database, pipeline), its main tech stack, and the role it plays in the system.
2. Architecture diagram: Add ## Architecture Diagram with a Mermaid diagram (a fenced mermaid code block) that places the container in its system context: its boundary, external systems, other containers, and infrastructure dependencies, with labeled, directional relationships. Keep internal component detail in Component Blueprints.
3. Infrastructure: Add ## Infrastructure for the runtime environment, deployment model, and key platform dependencies such as datastores, queues, and external services.
4. Entry points and boundaries: Add ## Entry Points and Boundaries to describe how work enters the container (HTTP or gRPC endpoints, queues, scheduled jobs, webhooks, CLI commands) and the boundaries it exposes to other containers and systems.
5. System Contracts: Add ## System Contracts with ### Key Contracts (guarantees at the container boundary, such as availability, authentication and authorization, idempotency, ordering, and error handling), ### Integration Contracts (events, APIs, webhooks, and message formats that cross the boundary), and ### Integration Boundaries (ownership and separation of concerns, including trust, security, or data residency boundaries).
6. Architecture Decision Records: Add ## Architecture Decision Records for container-level design choices, in the same ### ADR-NNN: Title format described below.

Component Blueprint Guidance

What They Are and When to Create One

A Component Blueprint is the technical documentation of a reusable system capability. It is feature-agnostic and may span multiple C4 containers. Component Blueprints primarily serve Feature Blueprints by defining reusable capabilities that features compose, and secondarily serve engineers and AI agents during implementation, debugging, and extension.

Create a Component Blueprint when: you're building a shared technical system that two or more features depend on (or will); you're abstracting a reusable capability; the system has enough internal structure (multiple components and relationships) to warrant its own document; or you want to establish the contracts (elements) that other Blueprints will reference.

Don't create one for: a single utility or helper with no internal structure; feature-specific logic that only makes sense in one context (that belongs in a Feature Blueprint); or infrastructure already well-documented elsewhere (reference as external dependency if needed).

Structure

1. Title and capability summary: Start with the Blueprint title, then add ## Capability Summary that explains what the capability does in two or three sentences and names the key elements flowing through it.
2. Architecture diagram: Add ## Architecture Diagram with a Mermaid diagram (a fenced mermaid code block) showing the runtime components that provide the capability, the containers that own them, and their directional dependencies and data flows. Keep it at the component level rather than expanding classes, functions, or fields.
3. Core components (grouped logically): Add ## Core Components and define component blocks in logical groups (for example ingestion, orchestration, persistence, and presentation; or backend then frontend).
4. Relationship paragraphs as edges: Treat component blocks as nodes and prose paragraphs as edges. Insert a relationship paragraph between components or groups when direction, data flow, or intent is not obvious from colocation. If adjacency already makes the relationship unambiguous, the paragraph is optional.
5. System Contracts: Add ## System Contracts to capture the capability's guarantees and boundary interfaces. Organize it with ### Key Contracts (invariants, correctness rules, and reliability semantics such as idempotency, ordering, consistency, and retry behavior) and ### Integration Contracts (events published or consumed, API interfaces, webhook payloads, and composition expectations). Use ### Integration Boundaries when the emphasis is ownership and separation of concerns rather than payload or API detail.
6. Architecture Decision Records: Add ## Architecture Decision Records for non-obvious design choices and trade-offs. Each entry is a ### heading in the format ### ADR-NNN: Title, followed by three labeled paragraphs: Context (why the decision was needed), Decision (what was chosen and how), and Consequences (trade-offs, benefits, and implications). Number ADRs sequentially within the Blueprint.

Feature Blueprint Guidance

What They Are and When to Create One

A Feature Blueprint describes how Component Blueprints, plus any feature-specific components, come together to satisfy product Requirements. It is composition-first: shared capabilities do the heavy lifting, and the Feature Blueprint wires and configures them and documents feature-only glue.

Create a Feature Blueprint when: a product manager has defined a feature with structured Requirements; the feature composes one or more Component Blueprints; you need to document how those capabilities are configured and wired for this feature; or feature-specific components exist that don't belong in any Component Blueprint.

Requirements Connection

Every Feature Blueprint has a corresponding Feature Requirements Document in a structured format, for example:

### REQ-XXX-001: Requirement Name
**User Story:** As a [role], I want to [action], so that I can [outcome].
**Acceptance Criteria:**
* **AC-XXX-001.1:** When the user [action], the system shall [behavior].
* **AC-XXX-001.2:** When [condition], the system shall [behavior].

It is assumed that the author of a Feature Blueprint has read the corresponding Requirements Document. The Feature Blueprint provides the technical path for satisfying those requirements; no formal cross-referencing is required.

Structure

1. Title and feature summary: Start with the Blueprint title, then add ## Feature Summary with a two- or three-sentence, user-centered summary that references the corresponding Requirements Document.
2. Architecture diagram: Add ## Architecture Diagram with a Mermaid diagram (a fenced mermaid code block) showing how the feature composes shared capabilities, feature-specific components, and external systems. Label the directional relationships and important data flows, without repeating the internal design of the capabilities it uses.
3. Component Blueprint composition: Add ## Component Blueprint Composition to document which shared capabilities this feature composes and how each is configured or scoped. Use document mentions (@...) for referenced Blueprints and Requirements, and component mentions (#...) for the concrete runtime components involved. Use composition paragraphs to explain how each capability wires into the feature, stating direction and data flow.
4. Feature-specific components: Add ## Feature-Specific Components for components that exist only for this feature (panels, pages, feature-specific hooks), and give them full component blocks. Use relationship paragraphs between component blocks when direction, data flow, or intent is not obvious from colocation.
5. System Contracts: Add ## System Contracts to capture the feature's guarantees and behavioral rules. Organize it with ### Key Contracts (invariants, correctness rules, reliability semantics) and ### Integration Contracts (events, APIs, and composition expectations specific to this feature).
6. Architecture Decision Records: Add ## Architecture Decision Records for non-obvious design choices and trade-offs. Each entry is a ### heading in the format ### ADR-NNN: Title, followed by three labeled paragraphs: Context (why the decision was needed), Decision (what was chosen and how), and Consequences (trade-offs, benefits, and implications). Number ADRs sequentially within the Blueprint.

Referencing Component Blueprints and Feature-Specific Components

When referencing a Component Blueprint, don't redefine its components. Describe how the feature uses the capability (for example, feature scoping, section limits, or response transformation). Example:

The Checkout feature uses shared Identity and Session Management plus Order Lifecycle capabilities. #CheckoutApiController validates CheckoutRequest, delegates authentication/session checks to #AuthenticationService, and submits the order command to #OrderLifecycleService. The resulting CustomerOrder is mapped to CheckoutResponse for the client.

Feature-specific components get full component blocks in the Feature Blueprint. Feature Blueprints can also extend shared capabilities with full component blocks when the extension is feature-specific. Any component defined in any Blueprint can be referenced with # from any other Blueprint.

Blueprint Principles

1. Code-grounded. Blueprints reference real code symbols. Components map to runtime components; elements map to concrete schemas, types, models, and contracts.
2. Composition-first. Container Blueprints define deployment units; Component Blueprints define reusable capabilities within and across them; Feature Blueprints compose those capabilities and add feature-specific components only where needed.
3. Structured and narrative. Structured blocks provide anchor points (component, model); prose paragraphs explain interactions, direction, and intent.
4. Implementable. A Feature Blueprint should provide enough architectural clarity for implementation without material ambiguity.
5. Markdown-native. Blueprints and Requirements are markdown documents with lightweight structured conventions.
6. Living artifacts. Blueprints evolve with the system as architecture and requirements change.

Authoring Checklist

• Choose the Blueprint type and category: a Container Blueprint for a deployable unit's technology and infrastructure, a Component Blueprint for a reusable system capability, or a Feature Blueprint for composing capabilities to satisfy requirements.
• Follow the baseline sections: Container Blueprints use ## Container Summary, ## Architecture Diagram, ## Infrastructure, ## Entry Points and Boundaries, ## System Contracts, and ## Architecture Decision Records. Component Blueprints use ## Capability Summary, ## Architecture Diagram, ## Core Components, ## System Contracts, and ## Architecture Decision Records. Feature Blueprints use ## Feature Summary, ## Architecture Diagram, ## Component Blueprint Composition, ## Feature-Specific Components, ## System Contracts, and ## Architecture Decision Records.
• Declare components and models: use component blocks for runtime nodes, and use model blocks only when you need a canonical domain model definition.
• Use mention syntax correctly: use #... for components, `...` for elements (schemas, types, request/response models, exceptions, models), and @... for documents, Knowledge Base files, and other entities.
• Write composition and relationship paragraphs: name concrete components (including cross-blueprint #... references), state direction, identify the data and contracts crossing boundaries, and explain why the interaction exists.
• Write System Contracts: use ### Key Contracts for invariants and reliability semantics, and ### Integration Contracts or ### Integration Boundaries for events, APIs, and composition expectations.
• Document Architecture Decision Records: use ### ADR-NNN: Title headings with labeled Context, Decision, and Consequences paragraphs. Number them sequentially within each Blueprint.
• Confirm requirement alignment (Feature Blueprints): assume the author has read the Requirements Document, and make sure each major requirement theme has a clear technical path through the Blueprint.