Production: product-dev-blueprint.vercel.app
Product Dev Blueprint is a schema-first product planning application for turning a rough software idea into a focused build-readiness plan. It helps a Product Manager, Solution Architect, founder, or engineering lead pressure-test an idea before development starts, then generates a traceable artifact bundle that can be handed to an engineering team or coding agent.
The application includes a Python DeepAgents AI Agent for LLM-backed blueprint proposals and deterministic TypeScript generators for final artifacts. The core UI can still load without model keys, but the AI Agent requires server-side model configuration.
There is no recorded demo video checked into the repo yet. Instead, this README includes a screenshot-based demo captured from the current production UI. The assets live in docs/assets and can be replaced by a real video later.
The landing page now presents the product as a decision and readiness workspace, not as a large pile of documents. It highlights the scorecard, scenario coverage, product ownership, architecture ownership, and build handoff groups.
The new-project page separates responsibility between Product Manager, Solution Architect, and Engineering. Template cards show stack direction, cloud, auth, data model, architecture pattern, governance, compliance, and scale signals.
After selecting a template, the app creates a project, marks the seeded intake complete, and opens generated artifacts. The readiness report is the default artifact; supporting documents are grouped for product, architecture, delivery, and governance review.
Product Dev Blueprint is designed to answer four questions before a team commits engineering time:
- Should we build this? Validate the problem, market, user, buyer, urgency, and confidence level.
- What can break this? Surface operational, legal, security, data, scale, AI, and adoption risks early.
- What should the MVP contain? Convert the idea into a constrained build slice with validation gates.
- How should engineering build it? Produce HLD, LLD, schema, APIs, security posture, roadmap, tests, and coding-agent prompts.
- Product Managers defining PRDs and MVP scope
- Founders validating a SaaS or marketplace idea
- Business Analysts converting business concepts into implementation-ready detail
- Solution Architects designing HLD, LLD, schema, APIs, auth, and deployment topology
- Engineering Managers estimating risk and sequencing delivery
- Pre-sales and transformation teams creating client-facing solution blueprints
- Developers using Cursor, Codex, or similar tools to build from structured specs
| Area | Current implementation |
|---|---|
| UI | Next.js 14 App Router, React, TypeScript, Tailwind CSS |
| Persistence | Browser localStorage through Zustand |
| Blueprint Agent | Python DeepAgents runtime at /api/agent that returns reviewable schema proposals |
| Artifact generation | Deterministic TypeScript generators in src/lib/generators |
| HLD / LLD | Generated from user inputs through the system-design generator |
| Lifecycle plan | Generated PM → UX → engineering → security → deployment → analytics execution plan |
| Mermaid diagrams | Rendered as visual diagrams in generated architecture artifacts |
| Exports | Markdown, DOCX, JSON, and zip bundle |
| Auth | Not implemented |
| Backend database | Not implemented |
| Live LLM calls | Implemented for Blueprint Agent proposals when server model env vars are configured |
| DeepAgents | Integrated in ai_agents/blueprint_agent with memory, skills, and subagents |
Required to use the AI Agent: AI_AGENT_MODEL and the matching server-side provider key. For OpenAI, use:
AI_AGENT_MODEL=openai:gpt-5.4-mini
OPENAI_API_KEY=sk-...See SETUP.md for the full local and Vercel configuration.
flowchart LR
A["Start with blank idea or template"] --> B["Complete PM-owned intake"]
A --> G["Run Python DeepAgents Blueprint Agent"]
G --> H["Review questions, assumptions, and proposed schema changes"]
H --> B
B --> C["Complete Solution Architect intake"]
C --> I["Complete lifecycle readiness"]
I --> D["Generate readiness report"]
D --> E["Review product, architecture, risk, lifecycle, and delivery artifacts"]
E --> F["Export Markdown, DOCX, JSON, scaffold, and coding-agent prompts"]
- Start from a rough idea and generate a reviewable LLM-backed schema proposal.
- Trigger the agent from project creation, overview, intake, or artifacts.
- Choose a full completion pass, Product Manager pass, Solution Architect pass, or readiness review.
- Review proposed changes, assumptions, confidence, follow-up questions, and touched domains before applying.
- Preserve the exact artifact bundle format by writing accepted changes back to the canonical
Projectschema. - Use dedicated Python agent files under
ai_agents/blueprint_agent, includingAGENTS.md, skills, and subagents.
- Problem, audience, buyer, market timing, alternatives, differentiation, pricing, and success criteria
- Build-readiness scorecard across desirability, feasibility, viability, risk readiness, and decision confidence
- Critical gaps and assumptions that should block or narrow implementation
- Validation experiments and MVP guardrails
- Personas and jobs-to-be-done
- Functional and non-functional requirements
- Feature backlog with acceptance criteria, edge cases, security notes, audit needs, dependencies, and release grouping
- KPI and success-measure definition
- Marketing and GTM brief
- SOW and executive summary outputs
- High-level architecture and low-level architecture
- Schema design and domain modeling
- API contract notes and integration boundaries
- OAuth, SSO, RBAC, authorization, tenancy, and audit posture
- Infra, cloud services, networking, CI/CD, Terraform/IaC, observability, DR, scaling, and release gates
- Architecture tradeoff matrix covering build-vs-buy, events, caching, realtime, privacy, security, data residency, and operational risk
- Persona handoff from Product Manager to UX Designer, Software Engineer, Security Engineer, Data/Growth Analyst, and Solution Architect
- Prototype/wireframe source and UX handoff notes
- Cloud deployment target, managed services, MCP/documentation sources, skills, and subagents
- Security review checklist and deployment approval gate
- Analytics feedback loop for post-launch product improvement
- A Google Cloud feedback-app template covering Cloud Run, Firestore, BigQuery, Looker, Cloud Logging/Monitoring, IAM/service accounts, and Claude on Google Cloud / Vertex AI
For AI use cases, the app captures:
- Agent framework direction, including LangGraph and DeepAgents
- RAG pipeline, vector database, embeddings, retrieval, evals, and guardrails
- Prompt-injection and AI safety review areas
- Model observability and tracing options
- Human-in-the-loop escalation and approval flows
- DeepAgents content-writer architecture, with server-side memory, skills, and subagents
- Download individual
.mdor.docxartifacts - Download full bundle as
.zip - Download raw
project.json - Copy markdown directly from the artifact viewer
- Use coding-agent prompts as structured input for Cursor, Codex, Lovable, Replit, or other development tools
The app does generate a large supporting bundle, but the UI and README intentionally group it by outcome so users do not experience it as a wall of documents.
| Group | Artifacts |
|---|---|
| Decision brief | Build readiness report, executive summary, implementation roadmap, cost estimate |
| Product definition | PRD, SOW, marketing/GTM brief |
| Architecture blueprint | Engineering specification, architecture blueprint, AI architecture, data/interface spec, ADR pack |
| Delivery package | Feature specification, requirements traceability matrix, test strategy, launch/operations plan |
| Governance | Risk register, security/compliance checklist |
| Coding handoff | Coding-agent prompt pack, lifecycle execution plan, and scaffold bundle |
Stable IDs are assigned across the project schema and reused in generated artifacts:
FR-001, NFR-001, FEAT-001, ADR-001, RISK-001, ASM-001,
Q-001, INT-001, ENT-001, SLO-001, KPI-001
The app keeps a schema-first flow: the Python AI Agent proposes schema changes, browser state stores accepted inputs, and deterministic generators render final artifacts.
flowchart TB
Browser["Browser"]
UI["Next.js App Router UI"]
Store["Zustand localStorage store"]
Schema["Canonical Project schema"]
Agent["Python DeepAgents /api/agent"]
AgentFiles["ai_agents memory, skills, subagents"]
Generators["Deterministic artifact generators"]
Renderer["Markdown / Mermaid / DOCX renderer"]
Exporter["Zip, JSON, Markdown, DOCX exports"]
Browser --> UI
UI --> Store
UI --> Agent
Agent --> AgentFiles
Agent --> Schema
Store --> Schema
Schema --> Generators
Generators --> Renderer
Generators --> Exporter
Future server-side capabilities such as accounts, shared projects, long-running background generation, and durable agent history should be added behind server APIs or workers. Provider keys must never be exposed to browser bundles. See docs/architecture/agent-runtime.md for the agent backend path.
| Layer | Technology |
|---|---|
| Framework | Next.js 14 App Router |
| Language | TypeScript |
| AI Agent Runtime | Python DeepAgents Vercel Function |
| UI | React, Tailwind CSS |
| State | Zustand with browser persistence |
| Markdown | react-markdown, remark-gfm |
| DOCX export | docx |
| Zip export | jszip |
| Deployment | Vercel |
| CI | GitHub Actions |
Prerequisites:
- Node.js 20 or newer
- Python 3.12 for the Vercel Python AI Agent runtime
- npm
- Optional: Vercel CLI for manual deployments
Install and run the UI only:
nvm use
npm ci
npm run devOpen:
http://localhost:3000
For full-stack local development with the Python /api/agent function:
Create .env.local with this OpenAI-backed agent configuration:
AI_AGENT_MODEL=openai:gpt-5.4-mini
OPENAI_API_KEY=sk-...Python dependencies for the Vercel function are declared in requirements.txt. Vercel installs them for deployment and npx vercel dev.
If you want to run Python checks outside Vercel:
python3 -m pip install -r requirements.txt
python3 -m py_compile api/agent.py ai_agents/blueprint_agent/*.pyStart the full stack:
npx vercel devRun production checks:
npm run typecheck
npm run build
python3 -m py_compile api/agent.py ai_agents/blueprint_agent/*.pyScripts:
| Script | Purpose |
|---|---|
npm run dev |
Start the local Next.js UI server |
npm run build |
Build the production app |
npm run start |
Serve the built app locally |
npm run typecheck |
Run TypeScript without emitting files |
npm run lint |
Legacy lint command; see SETUP.md before relying on it |
No .env.local file is required to load the UI, templates, deterministic artifacts, or exports.
The AI Agent requires server-only model configuration:
AI_AGENT_MODEL=openai:gpt-5.4-mini
OPENAI_API_KEY=sk-...Use the matching provider key for the selected AI_AGENT_MODEL. Never expose provider keys through NEXT_PUBLIC_*.
OpenAI's current public docs list gpt-5.4-mini as the mini model for high-volume workloads. If your account has access to a private or future model slug, set AI_AGENT_MODEL to the exact LangChain provider string accepted by that provider.
See SETUP.md for:
- Current runtime requirements
- AI Agent model/provider variables
- Vercel deployment variables
- Auth/database variables for a future multi-user version
- Troubleshooting notes
Production runs on Vercel through the GitHub integration.
| Event | Result |
|---|---|
| Pull request opened | Vercel preview deployment |
| Push to PR branch | Preview redeploy |
Merge to main |
Production deployment |
| GitHub Actions | Type-check and production build |
Production URL:
https://product-dev-blueprint.vercel.app
Manual production deploy from a linked and authenticated machine:
npx vercel deploy --prod --yes.github/
workflows/ci.yml # Type-check and build
dependabot.yml # Dependency update checks
pull_request_template.md
api/
agent.py # Python Vercel Function for the LLM Blueprint Agent
ai_agents/
blueprint_agent/ # DeepAgents memory, skills, subagents, and schema contract
docs/
assets/ # README demo screenshots
src/
app/
page.tsx # Landing page
settings/page.tsx # Import/export/clear settings
projects/
page.tsx # Project dashboard
new/page.tsx # Template selection
[id]/page.tsx # Project overview
[id]/intake/page.tsx # Guided intake wizard
[id]/artifacts/page.tsx # Generated artifacts and export actions
components/
ui.tsx # Shared UI primitives
ThemeToggle.tsx # Theme switcher
MermaidDiagram.tsx # Mermaid rendering and enlarge view
wizard/
WizardShell.tsx # Wizard layout, progress, navigation
steps.tsx # Core intake steps
steps-extended.tsx # Platform, features, system design, AI, compliance
lib/
schema.ts # Canonical Project type
store.ts # Zustand store and localStorage persistence
ids.ts # Stable ID allocation
options.ts # Intake option catalog and guidance
architecture-scenarios.ts # Tradeoff and architecture scenario catalog
feature-suggestions.ts # Rule-based feature seeding
scaffold.ts # Stack-aware scaffold export
templates/gcp-feedback-app.ts # Google Cloud feedback-app reference scenario
docx.ts # Markdown to DOCX rendering
export.ts # Zip and JSON export helpers
generators/ # Deterministic artifact generators
- Projects are stored in the browser only.
- Data is not synchronized across devices or users.
- Clearing browser/site data can delete local projects.
- There is no server-side backup in the current implementation.
- The AI Agent sends the current project context to the configured server-side model provider.
- Model provider keys must stay server-side and must never use
NEXT_PUBLIC_*. - Generated artifacts are drafts and should be reviewed before use in production delivery.
For a production multi-user version, add auth, a database, server-side exports, access controls, audit logs, and backup/retention policies before storing real customer or regulated data.
Before merging:
npm run typecheck
npm run build
python3 -m py_compile api/agent.py ai_agents/blueprint_agent/*.pyCI runs the same required checks on pull requests and pushes to main.
Near-term product improvements:
- Persist projects server-side with accounts and shared workspaces
- Add version history, comments, and review workflow
- Persist agent runs, messages, feedback, and approved case studies
- Add uploaded context documents for deeper artifact generation
- Add richer diagram export options
- Add Linear/Jira/GitHub issue export
- Add team roles for Product Manager, Solution Architect, Engineering, Security, and Reviewer
The current app keeps these capabilities out of the browser until a secure server-side runtime is introduced.
- Branch from
main. - Make focused changes.
- Run
npm run typecheckandnpm run build. - Open a pull request.
- Merge after CI and preview deployment pass.
This repository is licensed under the PolyForm Noncommercial License 1.0.0.
Commercial use is not permitted under this license. Any commercial use, including resale, SaaS hosting, paid client work, embedding this repository in a paid product, or using it to provide paid services, requires separate written permission from the copyright holder. See COMMERCIAL.md for the repository's commercial-use notice.
This is a source-available non-commercial license, not an OSI open-source license. AGPL was not used because AGPL permits commercial use when its license conditions are followed.