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.

Container Blueprints

A Container Blueprint describes one C4 container: a separately deployable or runnable unit such as a web application, API server, database, background worker, or build pipeline. It documents the container's technology stack, runtime characteristics, cross-cutting concerns such as 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 in which Component Blueprints operate.

Component Blueprints

A Component Blueprint 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, and the paragraphs between them describe the relationship edges.

Component Blueprints are feature-agnostic and commonly span multiple C4 containers. In modern systems, most capabilities cross container boundaries because end-to-end behavior combines interfaces, APIs, background processing, and persistence.

Feature Blueprints

A Feature Blueprint describes how capabilities from Component Blueprints, plus any feature-specific components, combine 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 high-level architecture through 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
• Artifacts
• 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.
• Foundation updates conflict with feature implementations.
• Shared components should be abstracted into a Foundation.

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.