| name | project-blueprint |
| description | Generate or regenerate the master architecture document (specs/MASTER_BLUEPRINT.md) — the single source of truth for tech stack, data model, API patterns, auth, UI conventions, and module relationships. Use when starting architecture, changing stack decisions, or after significant research that affects the technical approach. |
| effort | high |
Project Blueprint Skill
This skill creates or updates the Master Architecture Blueprint, the foundational architecture document for your project. Use it when:
- Starting a new project (Phase 4 of project-init)
- Making significant technology stack changes
- After completing domain or technical research that changes approach
- Quarterly architecture reviews
The skill reads existing project context, verifies technology versions, finds production examples, and generates a comprehensive blueprint.
Pre-Blueprint Review
Before generating the blueprint, gather existing project context:
-
Read existing specs:
specs/PROJECT_BRIEF.md (if exists) — project vision and constraints
specs/RESEARCH.md (if exists) — technology recommendations
specs/MODULES.md (if exists) — module decomposition
CLAUDE.md (if exists) — project coding patterns
- Any architecture decision records (ADRs)
-
Identify decision blockers:
- Is the tech stack already decided?
- Have key frameworks/databases been chosen?
- Are there hard constraints (budget, compliance, performance)?
-
Determine research needs:
- If tech stack is undefined, proceed to "Stack Detection" section below
- If partial stack exists, identify gaps (frontend, backend, database, deployment)
- If stack is defined, proceed directly to "Technology Verification" section
Stack Detection (if not yet decided)
If the technology stack is not yet defined, answer these 4 core questions to guide choices:
Question 1: What Frontend Framework Aligns with UI Complexity and Team Skills?
Options to Research:
React
- Use if: Complex UI state, component reusability, large ecosystem, team familiarity
- Search: "React 2024 latest version" +
ref_search_documentation
- Considerations: Large bundle size, steep learning curve, ecosystem fragmentation
Vue
- Use if: Progressive enhancement, gentle learning curve, good balance
- Search: "Vue 3 official documentation" +
ref_search_documentation
- Considerations: Smaller ecosystem than React, focused on single-file components
Svelte
- Use if: Minimal JavaScript, performance critical, smaller app
- Search: "Svelte documentation" +
ref_search_documentation
- Considerations: Smaller ecosystem, less community content
Solid or Astro (for content-heavy sites)
- Use if: Static content dominance, island architecture, fast load times
- Search: "Astro vs Next.js comparison" +
web_search_exa
- Considerations: Different paradigm, less suitable for complex SPAs
Decision Criteria:
- Team skill level and learning curve tolerance
- Application complexity and state management needs
- Performance requirements and bundle size
- Community size and available resources
- Deployment target (Vercel, traditional server, edge)
Question 2: What Backend Stack? (Language + Framework + Runtime)
JavaScript/Node.js Options:
- Next.js (React meta-framework): Full-stack React, API routes, edge functions
- Search: "Next.js 15 latest version" +
ref_search_documentation
- Express.js: Minimal, flexible, requires more setup
- Search: "Express.js best practices 2024" +
web_search_exa
- Fastify: High-performance, modern, TypeScript-first
- Search: "Fastify documentation" +
ref_search_documentation
Python Options:
- Django: Feature-rich, batteries-included, ORM, admin panel
- Search: "Django 5.0 official documentation" +
ref_search_documentation
- FastAPI: Modern, async, automatic API docs, very fast
- Search: "FastAPI documentation" +
ref_search_documentation
Other Runtimes:
- Go (Echo/Gin): High performance, compiled, good for microservices
- Search: "Go web framework comparison" +
web_search_exa
- Rust (Actix/Axum): Safety and performance, steep learning curve
- Search: "Rust web framework 2024" +
web_search_exa
Decision Criteria:
- Team language expertise
- Performance requirements
- Development speed vs. production optimization
- Available libraries and frameworks
- Hosting and deployment options
Question 3: What Database? (Primary Data Store)
Relational (SQL):
- PostgreSQL: Mature, feature-rich, free, excellent JSON support
- Search: "PostgreSQL latest version documentation" +
ref_search_documentation
- MySQL/MariaDB: Widely hosted, simpler than PostgreSQL
- SQL Server: Enterprise, Windows-centric
Document (NoSQL):
- MongoDB: Flexible schema, scales horizontally, document-oriented
- Search: "MongoDB Atlas documentation" +
ref_search_documentation
Graph:
- Neo4j: Relationship-heavy data, social networks, recommendations
- Search: "Neo4j documentation" +
ref_search_documentation
Vector (for AI/ML):
- Pinecone/Weaviate: Vector embeddings, AI search
- Search: "Pinecone vs Weaviate comparison" +
web_search_exa
Cache/Sessions:
- Redis: In-memory, fast, sessions, caching, real-time features
- Search: "Redis latest version" +
ref_search_documentation
Decision Criteria:
- Data structure: Highly relational → SQL; flexible → MongoDB; relationships → Graph
- Scale: Billions of records → consider distributed options
- Consistency: ACID requirements → SQL; eventual consistency ok → NoSQL
- Query patterns: Complex joins → SQL; simple lookups → NoSQL
Question 4: What Deployment Target? (Infrastructure)
Serverless/Edge:
- Vercel: Next.js native, edge functions, preview deployments
- Search: "Vercel documentation" +
ref_search_documentation
- AWS Lambda: Scalable, pay-per-use, complex to manage
- Cloudflare Workers: Edge execution, global distribution
Container-Based:
- Docker + Kubernetes: Full control, operational complexity
- Docker + Docker Compose: Simpler for small teams
Traditional Servers:
- AWS EC2, DigitalOcean, Linode: Full control, manage updates
- Heroku: PaaS, simpler but less control, higher cost
Decision Criteria:
- Operational complexity tolerance
- Scaling needs: Sudden spikes → serverless; steady → traditional servers
- Cost model: Sporadic usage → serverless; always-on → traditional
- Control requirements: Full → traditional/k8s; happy with managed → serverless/Vercel
- Team DevOps experience
Technology Verification
Once stack options are identified or decided, verify current versions and best practices:
For Each Chosen Technology:
-
Find Official Documentation:
- Use
ref_search_documentation with query: "{{framework}} official documentation"
- Record the current stable version (not beta, not EOL)
- Note any deprecations or major API changes
-
Verify Production Patterns:
- Use
get_code_context_exa with query: "{{framework}} {{pattern}} production example"
- Look for: Real-world repos, large projects, proven patterns
- Record: URL to example repo, key takeaways
-
Check Version Compatibility:
- Frontend + Backend: Are they compatible? (e.g., React 19 + Next.js 15)
- Database drivers: Are they updated for the database version?
- Build tools: Updated recently? Any major breaking changes?
-
Document Rationale:
- For each technology, record:
- Version number
- Why chosen (from stack detection Q1-Q4)
- Trade-offs vs. alternatives
- Source URL
Master Blueprint Generation
Step 1: Gather Information
Collect the following before filling the blueprint:
From Project Brief:
- Problem statement and solution overview
- Target users and success criteria
- Scope boundaries and constraints
From Research:
- Market landscape context
- Competitor positioning
- Technical recommendations
- Regulatory/compliance requirements
From Stack Detection:
- Frontend framework choice and rationale
- Backend language, framework, runtime
- Primary database choice
- Deployment target
- Secondary technologies (cache, auth, CDN, etc.)
From Tech Verification:
- Current stable versions for each technology
- Documentation URLs
- Production example repos
- Known gotchas or migration paths
Step 2: Fill Blueprint Template
Use the template at ../project-init/blueprint-template.md.
Fill each section systematically:
- 1. Project Overview: Copy from PROJECT_BRIEF.md
- 2. Tech Stack: List technologies with versions from stack detection + verification
- 3. Data Model: Define core entities as TypeScript interfaces
- 4. API Design Patterns: Choose REST/GraphQL/tRPC; define error format, auth method
- 5. Shared UI Patterns: Design system basics, navigation pattern, accessibility level
- 6. Modules: List from MODULES.md with dependencies
- 7. Infrastructure & Deployment: Hosting, CI/CD, monitoring, backups
- 8. Security & Compliance: Auth method, encryption, compliance requirements
- 9. Open Questions: Known unknowns to resolve before implementation
Step 3: Create Example Data Model
Define the core entities that represent your domain:
Example: E-commerce
interface User {
id: string;
email: string;
passwordHash: string;
role: "customer" | "admin";
createdAt: Date;
updatedAt: Date;
}
interface Product {
id: string;
name: string;
description: string;
price: number;
inventory: number;
categoryId: string;
createdAt: Date;
updatedAt: Date;
}
interface Order {
id: string;
userId: string;
items: OrderItem[];
status: "pending" | "processing" | "shipped" | "delivered";
totalPrice: number;
createdAt: Date;
updatedAt: Date;
}
Blueprint Review & Approval
Prepare Summary for Team Review
Create a 1-page summary covering:
Key Technology Decisions:
- Frontend: {{Framework}} v{{Version}} — chosen because {{Rationale}}
- Backend: {{Language/Framework}} v{{Version}} — chosen because {{Rationale}}
- Database: {{Technology}} — chosen because {{Rationale}}
- Deployment: {{Platform}} — chosen because {{Rationale}}
Architectural Highlights:
- Data Model: {{Key entities and relationships}}
- API Style: {{REST/GraphQL/etc}} — {{Key design decision}}
- Authentication: {{Method}} — {{Implementation approach}}
Known Constraints & Trade-offs:
- {{Constraint 1}} — Impact: {{Impact}}
- {{Constraint 2}} — Impact: {{Impact}}
Open Questions Requiring Decision:
- {{Question 1}} — Decision needed by {{Date}}
- {{Question 2}} — Decision needed by {{Date}}
Present & Discuss
- Share Summary with the team
- Walk through the 9 sections of the blueprint
- Discuss trade-offs — for each major decision, explain alternatives and why this won
- Identify Risks — what could go wrong with this architecture?
- Gather Feedback — are there concerns? Missing considerations?
Approval Gates
Before finalizing, confirm:
Save & Version
Once approved:
- Save to:
specs/MASTER_BLUEPRINT.md
- Version Control: Commit with message: "feat: create master blueprint for {{project}}"
- Reference Specs: Link from PROJECT_BRIEF.md and module specs
- Update LEARNINGS.md: Document key architectural decisions and rationale
Common Blueprint Patterns
Pattern: Monolithic + API
When to Use: Startup MVP, single team, simple domain
Frontend (React) → Backend (Next.js) → Database (PostgreSQL)
↓
Cache (Redis)
Pattern: Full-Stack Frameworks
When to Use: Web apps with tight frontend-backend coupling
Next.js (frontend + backend) → Postgres + Redis
↓
Vercel (deploy)
Pattern: Microservices
When to Use: Scale, multiple teams, independent deployments
Frontend (React) → API Gateway → Service 1 (Node.js) → DB1
→ Service 2 (Python) → DB2
→ Service 3 (Go) → DB3
Pattern: Async Workers
When to Use: Long-running jobs, background processing
Frontend → Backend API → Queue (Redis/Bull) → Workers
↓
Database
Choose the pattern that matches your scale, team size, and complexity.
Handling Changes to the Blueprint
If circumstances change during development:
- Minor Changes (new field in data model): Update blueprint, create ADR if significant
- Moderate Changes (database technology swap): Re-run tech verification, update blueprint, get team approval
- Major Changes (backend framework swap): Repeat full blueprint process with research
Always maintain the blueprint as current source of truth.
Template & Resources
- Template:
../project-init/blueprint-template.md
- Example Blueprints: Reference blueprints in
docs/examples/
- Technology Docs: Use
ref_search_documentation to find official guides
- Production Examples: Use
get_code_context_exa for real-world implementations
Next Steps
After blueprint approval:
- Create Module Specs — Each module gets detailed SPEC.md using
../project-init/module-spec-template.md
- Create Module CLAUDE Guides — Each module gets CLAUDE.md for implementation patterns
- Create Implementation Roadmap — Priority and sequencing of work
- Set Up Infrastructure — Deploy databases, auth system, CI/CD
- Begin Implementation — Modules in priority order