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.

Blueprint types

Software Factory organizes Blueprints into three categories.

Container Blueprint

A Container Blueprint describes a single deployable or runnable unit of the system, such as a web application, API server, database, background worker, or build pipeline. It captures the container's technology stack, runtime characteristics, and cross-cutting concerns such as authentication, error handling, and observability.

Container Blueprints are infrastructure-focused and feature-agnostic. They establish the operational context that Component Blueprints build within.

Component Blueprint

A Component Blueprint describes a reusable system capability composed of multiple components such as services, controllers, hooks, and strategies that together power one capability, for example identity and session management or notification delivery.

Component Blueprints are feature-agnostic and commonly span multiple containers. They describe what the system can do, not what any single feature uses.

Feature Blueprint

A Feature Blueprint describes how capabilities from Component Blueprints combine, plus any feature-specific components, to satisfy product Requirements. Each Feature Blueprint corresponds to a Feature Requirements Document: Requirements say what, while the Feature Blueprint says how.

Feature Blueprints are composition-first. They connect shared capabilities, configure them for the feature, and document feature-specific glue. Together, the blueprint types form a technical narrative spanning infrastructure, reusable capabilities, and feature implementation.

Agent capabilities

Edit suggestions

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

Context awareness

The agent has context across:

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

This context lets the agent answer questions, generate accurate content, and detect inconsistencies.

Skills and workflows

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
• Help synchronize blueprints with requirements and code
• Highlight issues using flagged comments
• Guide structured decision-making workflows

Synchronizing Blueprints with code and requirements

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

Alerts and resolution

Alerts notify you when:

• Code changes may invalidate a blueprint.
• Requirements updates are not reflected in feature specifications.
• Container or Component updates conflict with feature implementations.
• Reusable components in a Feature Blueprint should be abstracted into a Component Blueprint.

Opening an alert starts a guided, human-in-the-loop workflow. The agent explains the issue, suggests updates, and helps bring the documentation and implementation back into alignment.

Best practices

• Treat blueprints as living documents that evolve with the system.
• Use features from Requirements to scope each blueprint section clearly.
• Center blueprints on system behavior and component interactions.
• Sync frequently with requirements and code to avoid drift.
• Include enough detail for confident implementation without locking the design to unnecessary specifics.

Troubleshooting

The agent is struggling with long context. Select only the relevant sections and restart the chat.

A section fails to update from the codebase. Ask the agent to search the code and compare its findings with the blueprint you are editing.

Ready to turn specifications into tasks? Learn about Work Orders.