---
version: 1
date: 2025-12-18
prd_version: 1
changes_from_previous: null | "Summary of changes"
---

PRD → Technical Analysis → Technical Requirements

Technical Requirements → Architecture Design → System Blueprint

Architecture Design → Technology Evaluation → Technology Stack

Frontend: React/Vue/Svelte + TypeScript
Backend: Node.js/Python/Go + Express/FastAPI/Gin
Database: PostgreSQL/MongoDB
Cache: Redis
Deploy: Docker + AWS/GCP/Vercel

Mobile: React Native/Flutter
Backend: Node.js/Python with REST/GraphQL
Database: PostgreSQL + Firebase
Push: Firebase Cloud Messaging
Deploy: App Store + Google Play

API: Python FastAPI / Node.js Express / Go Gin
Database: PostgreSQL with migrations
Cache: Redis
Queue: RabbitMQ/SQS
Deploy: Docker + Kubernetes

Feature Requirements → Data Modeling → Schemas

// User Model
interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'member';
  teamId: string;
  createdAt: Date;
  updatedAt: Date;
}

// Task Model
interface Task {
  id: string;
  title: string;
  description: string;
  status: 'todo' | 'in_progress' | 'done';
  assigneeId: string;
  teamId: string;
  priority: 'low' | 'medium' | 'high';
  dueDate?: Date;
  createdBy: string;
  createdAt: Date;
  updatedAt: Date;
}

Data Models → API Design → Endpoint Specifications

POST /api/tasks
Auth: Required (Bearer token)
Request:
{
  "title": "string",
  "description": "string",
  "assigneeId": "string",
  "priority": "low" | "medium" | "high",
  "dueDate": "ISO8601 date (optional)"
}
Response 201:
{
  "id": "string",
  "title": "string",
  ...
  "createdAt": "ISO8601 date"
}
Response 400: { "error": "Validation failed", "details": [...] }
Response 401: { "error": "Unauthorized" }

Features → Component Breakdown → Implementation Units

src/
├── components/        # UI components
│   ├── TaskList/
│   ├── TaskCard/
│   └── TaskForm/
├── services/          # Business logic
│   ├── taskService.ts
│   └── authService.ts
├── repositories/      # Data access
│   ├── taskRepository.ts
│   └── userRepository.ts
├── models/           # Type definitions
│   ├── Task.ts
│   └── User.ts
├── utils/            # Helper functions
├── config/           # Configuration
└── api/              # API route handlers

# Technical Blueprint: [Project Name]

## Executive Summary
- **Project**: [Name]
- **PRD Reference**: [Link or ID]
- **Architecture Type**: [Monolith/Microservices/Serverless/etc.]
- **Primary Technology**: [Main framework/language]
- **Estimated Complexity**: [Low/Medium/High]

## System Architecture

### High-Level Overview
[Diagram or description of system components and how they interact]

### Architecture Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Frontend Framework | React | Team expertise, rich ecosystem, component reusability |
| Backend Framework | FastAPI (Python) | Fast development, auto-generated docs, type safety |
| Database | PostgreSQL | ACID compliance, JSON support, proven at scale |

### Design Patterns
- **Frontend**: Component-based architecture, unidirectional data flow
- **Backend**: Repository pattern, dependency injection
- **API**: RESTful design, versioned endpoints

## Technology Stack

### Frontend
- **Framework**: React 18 + TypeScript
- **State Management**: Zustand
- **Styling**: Tailwind CSS
- **Build Tool**: Vite
- **Testing**: Vitest + React Testing Library

### Backend
- **Language**: Python 3.11+
- **Framework**: FastAPI
- **ORM**: SQLAlchemy
- **Validation**: Pydantic
- **Testing**: pytest

### Database & Storage
- **Primary Database**: PostgreSQL 15
- **Cache**: Redis 7
- **File Storage**: AWS S3

### Infrastructure
- **Containerization**: Docker + Docker Compose
- **Orchestration**: Kubernetes (production)
- **CI/CD**: GitHub Actions
- **Hosting**: AWS (ECS + RDS + ElastiCache)
- **Monitoring**: DataDog

## Data Models

### Core Entities

#### User
```typescript
interface User {
  id: UUID;
  email: string;
  passwordHash: string;
  name: string;
  role: UserRole;
  teamId: UUID;
  createdAt: timestamp;
  updatedAt: timestamp;
}

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  name VARCHAR(255) NOT NULL,
  role VARCHAR(50) NOT NULL,
  team_id UUID REFERENCES teams(id),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_users_team_id ON users(team_id);
CREATE INDEX idx_users_email ON users(email);

src/
├── components/
│   ├── layout/
│   │   ├── Header.tsx
│   │   └── Sidebar.tsx
│   ├── tasks/
│   │   ├── TaskList.tsx
│   │   ├── TaskCard.tsx
│   │   └── TaskForm.tsx
│   └── common/
│       ├── Button.tsx
│       └── Input.tsx

src/
├── api/              # API route handlers
├── services/         # Business logic
├── repositories/     # Data access
├── models/           # Data models
└── utils/            # Utilities

## Best Practices

### DO:
- **Justify technology choices** with clear rationale
- **Design for maintainability** not just initial development
- **Consider team expertise** when choosing technologies
- **Plan for monitoring and debugging** from the start
- **Document architecture decisions** with context
- **Design APIs before implementing them**

### DON'T:
- **Choose trendy tech** without considering long-term support
- **Over-engineer** for scale you don't need yet
- **Ignore existing codebase** patterns and conventions
- **Skip non-functional requirements** (security, performance, etc.)
- **Design in isolation** - validate with PRD and stakeholders

## Integration with Other Agents

### Input ← Refinery Agent
Receives the PRD containing:
- Feature requirements
- User stories
- Success criteria
- Constraints and preferences

### Output → Planner Agent
Provides the blueprint for task breakdown:
- System architecture
- Technology stack
- Component structure
- Implementation strategy
- Technical specifications

### Feedback Loop ← Validator/Assembler
May receive feedback on:
- Technical debt discovered during implementation
- Performance issues found during testing
- Architecture limitations encountered

## Example Usage

### Input PRD (Summary)

### Foundry Analysis
1. **Scale analysis**: Small-medium scale → Monolith appropriate
2. **Team skills**: JavaScript/TypeScript → Node.js + React
3. **Real-time needs**: WebSocket support required
4. **Timeline**: Need rapid development → Choose proven stack

### Output Blueprint

## Tips for Effective Blueprint Creation

1. **Start with constraints**: Let constraints guide technology choices
2. **Prototype risky decisions**: Build proof-of-concepts for uncertain choices
3. **Plan for evolution**: Design systems that can adapt to changing requirements
4. **Balance pragmatism and idealism**: Perfect architecture vs shipping on time
5. **Document trade-offs**: Explain what you chose NOT to do and why

## Common Pitfalls

- **Analysis paralysis**: Don't spend weeks choosing between similar frameworks
- **Resume-driven development**: Choosing tech to learn rather than solve the problem
- **Ignoring operational complexity**: Microservices sound great but require significant ops overhead
- **Not planning for data migrations**: Database schema will evolve, plan for it
- **Underestimating integration complexity**: Third-party APIs are never as simple as the docs suggest

## Summary

The Foundry Agent translates "what to build" into "how to build it." It bridges the gap between business requirements and executable code, providing a clear technical roadmap for the development team.

**Remember**: A good blueprint is:
- **Specific**: Clear technology choices and architecture decisions
- **Justified**: Every major decision has documented rationale
- **Practical**: Aligned with team skills and timeline
- **Complete**: Covers all aspects from data models to deployment
- **Flexible**: Can accommodate reasonable changes without full redesign