Blueprints

Blueprints are human-readable technical specification documents that serve as the definitive source of truth for how a system should be built. They translate product requirements into precise engineering guidance while remaining synchronized with real implementation.

Describes 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 (e.g., authentication, error handling, 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.

Describes a reusable system capability composed of multiple C4 components: a cohesive group of services, controllers, hooks, strategies, and other runtime components that together power one capability. It is the prose equivalent of a C4 component diagram: structured component blocks are the nodes, paragraphs between the component blocks 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 (e.g., API Server and Client App). In modern software systems, most capabilities are inherently cross-container because end-to-end behavior typically combines user-interface, API orchestration, background processing, and persistence concerns.

Describes 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.

Together, these blueprints form a connected technical narrative that spans high-level architecture down to feature-level implementation details.

The agent can propose edits to any blueprint by generating structured, reviewable suggestions. These appear as color-coded diffs in the document editor and can be accepted or rejected by users with the appropriate permissions.

The agent has contextual awareness across:

• All blueprints in the project
• The codebase index
• Artifacts
• Feature requirements
• Work orders
• Code files linked to each blueprint and recent code changes

This allows it to answer questions, generate accurate content, and detect inconsistencies.

The agent can:

• Draft and refine blueprint content
• Generate and update Mermaid diagrams
• Review blueprints for gaps, ambiguity, or conflicts
• Answer architectural questions grounded in documentation
• Assist with syncing blueprints to PRDs and code
• Highlight issues using flagged comments
• Guide users through structured decision-making workflows

Software Factory continuously analyzes changes in the requirements and codebase to detect drift from existing blueprints. When discrepancies are found, the system flags the affected blueprints and surfaces alerts in the agent panel.

Alerts and Resolution

Alerts notify you when:

• Code changes may invalidate a blueprint
• PRD updates are not reflected in feature specifications
• Foundation updates conflict with feature implementations
• Shared components should be abstracted into a Foundation

Engaging with an alert launches a guided, human-in-the-loop workflow where the agent explains the issue, suggests updates, and helps you bring everything back into alignment.

• Treat blueprints as living documents that evolve with the system.
• Use features from Requirements to scope each blueprint section clearly.
• Keep blueprints centered on system behavior and component interactions.
• Sync frequently with PRDs and code to avoid drift.
• Provide enough detail for engineers to implement confidently, without locking the design to unnecessary implementation specifics.

Agent struggling with long context? → Select only the relevant sections and restart the chat for better results.

A section fails to update from codebase? → Just ask the agent to search the code and compare its findings to the blueprint you are working on.

Ready to turn specs into tasks? Learn about Work Orders →Learn about Work Orders →