377 lines
11 KiB
Markdown
377 lines
11 KiB
Markdown
---
|
|
name: tech-stack-architect
|
|
description: Design complete technology stack and system architecture from project requirements - generates TECH-STACK.md with frontend/backend/database/DevOps choices plus rationale, and ARCHITECTURE.md with components, data flow, and mermaid diagrams
|
|
version: 0.1.0
|
|
tags: [architecture, planning, tech-stack, design]
|
|
triggers:
|
|
- tech stack
|
|
- architecture
|
|
- technology choices
|
|
- system design
|
|
- architecture diagram
|
|
---
|
|
|
|
# Tech Stack Architect
|
|
|
|
## Purpose
|
|
Generate comprehensive technology stack selection and system architecture design from project requirements. Creates two foundational documents that guide implementation.
|
|
|
|
## When to Use
|
|
- Starting a new project after PROJECT-OVERVIEW.md is created
|
|
- Re-architecting existing systems
|
|
- Technology evaluation and selection
|
|
- Architecture documentation needed
|
|
- User mentions "tech stack", "architecture", "system design"
|
|
|
|
## Behavior
|
|
|
|
### Phase 1: Technology Stack Selection
|
|
|
|
1. **Read PROJECT-OVERVIEW.md** for:
|
|
- Project goals and constraints
|
|
- Scale requirements (users, data, traffic)
|
|
- Team skills and preferences
|
|
- Budget and timeline
|
|
- Compliance requirements
|
|
|
|
2. **Analyze requirements** across 4 categories:
|
|
- Frontend (framework, state management, UI library)
|
|
- Backend (language, framework, API style)
|
|
- Database (RDBMS, NoSQL, caching, search)
|
|
- DevOps (hosting, CI/CD, monitoring, security)
|
|
|
|
3. **Generate TECH-STACK.md** with:
|
|
- **Category tables**: Technology | Rationale | Alternatives Considered
|
|
- **Integration notes**: How technologies work together
|
|
- **Trade-offs**: What you gain/lose with this stack
|
|
- **Migration path**: How to evolve the stack
|
|
- **Team considerations**: Learning curve, hiring, support
|
|
|
|
### Phase 2: System Architecture Design
|
|
|
|
1. **Design components**:
|
|
- Client-side architecture
|
|
- API layer and services
|
|
- Data storage and caching
|
|
- Background jobs and queues
|
|
- External integrations
|
|
|
|
2. **Define data flow**:
|
|
- Request/response paths
|
|
- Authentication flow
|
|
- Data persistence patterns
|
|
- Event-driven flows (if applicable)
|
|
|
|
3. **Generate ARCHITECTURE.md** with:
|
|
- **System Overview**: High-level component diagram (C4 Context)
|
|
- **Component Details**: Responsibilities, interfaces, dependencies
|
|
- **Data Flow Diagrams**: Key user journeys with sequence diagrams
|
|
- **Scalability Strategy**: Horizontal scaling, caching, load balancing
|
|
- **Security Architecture**: Auth, encryption, OWASP considerations
|
|
- **Mermaid Diagrams**: C4, sequence, data flow, deployment
|
|
|
|
## Output Style
|
|
- Use `table-based` for technology comparisons
|
|
- Use `markdown-focused` with mermaid diagrams for architecture
|
|
- Keep rationales concise (1-2 sentences per choice)
|
|
- Include visual diagrams for clarity
|
|
|
|
## Output Files
|
|
|
|
### 1. project-management/TECH-STACK.md
|
|
```markdown
|
|
# Technology Stack
|
|
|
|
## Summary
|
|
[2-3 sentence overview of the stack philosophy]
|
|
|
|
## Frontend Stack
|
|
|
|
| Technology | Choice | Rationale | Alternatives Considered |
|
|
|------------|--------|-----------|------------------------|
|
|
| Framework | React 18 | ... | Vue, Svelte, Angular |
|
|
| State | Zustand | ... | Redux, Jotai, Context |
|
|
| UI Library | Tailwind + shadcn/ui | ... | MUI, Chakra, custom |
|
|
| Build | Vite | ... | Webpack, Turbopack |
|
|
|
|
## Backend Stack
|
|
|
|
| Technology | Choice | Rationale | Alternatives Considered |
|
|
|------------|--------|-----------|------------------------|
|
|
| Language | Python 3.11 | ... | Node.js, Go, Rust |
|
|
| Framework | FastAPI | ... | Django, Flask, Express |
|
|
| API Style | REST + OpenAPI | ... | GraphQL, gRPC, tRPC |
|
|
|
|
## Database & Storage
|
|
|
|
| Technology | Choice | Rationale | Alternatives Considered |
|
|
|------------|--------|-----------|------------------------|
|
|
| Primary DB | PostgreSQL 15 | ... | MySQL, MongoDB, SQLite |
|
|
| Caching | Redis | ... | Memcached, Valkey |
|
|
| Search | ElasticSearch | ... | Algolia, Meilisearch |
|
|
| Object Storage | S3 | ... | MinIO, CloudFlare R2 |
|
|
|
|
## DevOps & Infrastructure
|
|
|
|
| Technology | Choice | Rationale | Alternatives Considered |
|
|
|------------|--------|-----------|------------------------|
|
|
| Hosting | AWS ECS Fargate | ... | k8s, VM, serverless |
|
|
| CI/CD | GitHub Actions | ... | GitLab CI, CircleCI |
|
|
| Monitoring | DataDog | ... | Grafana, New Relic |
|
|
| Secrets | AWS Secrets Manager | ... | Vault, Doppler |
|
|
|
|
## Integration Notes
|
|
- [How frontend talks to backend]
|
|
- [Database connection pooling strategy]
|
|
- [Caching layer integration]
|
|
- [CI/CD pipeline flow]
|
|
|
|
## Trade-offs
|
|
**Gains**: [What this stack provides]
|
|
**Costs**: [Complexity, vendor lock-in, learning curve]
|
|
|
|
## Migration Path
|
|
- Phase 1: [Initial minimal stack]
|
|
- Phase 2: [Add caching, search]
|
|
- Phase 3: [Scale horizontally]
|
|
|
|
## Team Considerations
|
|
- **Learning Curve**: [Estimate for team]
|
|
- **Hiring**: [Availability of talent]
|
|
- **Support**: [Community, docs, enterprise support]
|
|
```
|
|
|
|
### 2. project-management/ARCHITECTURE.md
|
|
```markdown
|
|
# System Architecture
|
|
|
|
## Overview
|
|
[2-3 sentence description of the system]
|
|
|
|
## C4 Context Diagram
|
|
```mermaid
|
|
C4Context
|
|
title System Context for [Project Name]
|
|
|
|
Person(user, "User", "End user of the system")
|
|
System(app, "Application", "Main system")
|
|
System_Ext(auth, "Auth Provider", "OAuth2 provider")
|
|
System_Ext(payment, "Payment Gateway", "Stripe")
|
|
|
|
Rel(user, app, "Uses", "HTTPS")
|
|
Rel(app, auth, "Authenticates", "OAuth2")
|
|
Rel(app, payment, "Processes payments", "API")
|
|
```
|
|
|
|
## Component Architecture
|
|
```mermaid
|
|
graph TB
|
|
Client[React Client]
|
|
API[FastAPI Backend]
|
|
DB[(PostgreSQL)]
|
|
Cache[(Redis)]
|
|
Queue[Job Queue]
|
|
Worker[Background Workers]
|
|
|
|
Client -->|HTTPS/JSON| API
|
|
API -->|SQL| DB
|
|
API -->|GET/SET| Cache
|
|
API -->|Enqueue| Queue
|
|
Queue -->|Process| Worker
|
|
Worker -->|Update| DB
|
|
```
|
|
|
|
### Component Details
|
|
|
|
**Client (React)**
|
|
- **Responsibilities**: UI rendering, state management, client-side validation
|
|
- **Key Libraries**: React Router, Zustand, React Query
|
|
- **Interfaces**: REST API via fetch/axios
|
|
|
|
**API (FastAPI)**
|
|
- **Responsibilities**: Business logic, validation, auth, rate limiting
|
|
- **Key Modules**: auth, users, payments, notifications
|
|
- **Interfaces**: REST endpoints (OpenAPI), WebSocket (notifications)
|
|
|
|
**Database (PostgreSQL)**
|
|
- **Responsibilities**: Persistent data storage, relational integrity
|
|
- **Schema**: Users, sessions, transactions, audit logs
|
|
- **Patterns**: Repository pattern, connection pooling
|
|
|
|
**Cache (Redis)**
|
|
- **Responsibilities**: Session storage, rate limiting, job queue
|
|
- **TTL Strategy**: Sessions (24h), API cache (5m), rate limits (1h)
|
|
|
|
**Background Workers**
|
|
- **Responsibilities**: Email sending, report generation, cleanup jobs
|
|
- **Queue**: Redis-backed Celery/ARQ
|
|
- **Monitoring**: Dead letter queue, retry logic
|
|
|
|
## Authentication Flow
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant User
|
|
participant Client
|
|
participant API
|
|
participant Auth0
|
|
participant DB
|
|
|
|
User->>Client: Click "Login"
|
|
Client->>Auth0: Redirect to OAuth2
|
|
Auth0->>Client: Return auth code
|
|
Client->>API: Exchange code for token
|
|
API->>Auth0: Validate code
|
|
Auth0->>API: User profile
|
|
API->>DB: Create/update user
|
|
API->>Client: Return JWT token
|
|
Client->>Client: Store token (httpOnly cookie)
|
|
```
|
|
|
|
## Data Flow: User Registration
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client
|
|
participant API
|
|
participant DB
|
|
participant Queue
|
|
participant Worker
|
|
participant Email
|
|
|
|
Client->>API: POST /api/register
|
|
API->>API: Validate input
|
|
API->>DB: Create user (inactive)
|
|
API->>Queue: Enqueue welcome email
|
|
API->>Client: 201 Created
|
|
Queue->>Worker: Process email job
|
|
Worker->>Email: Send welcome email
|
|
Worker->>DB: Log email sent
|
|
```
|
|
|
|
## Scalability Strategy
|
|
|
|
### Horizontal Scaling
|
|
- **API**: Stateless containers (2-10 instances behind ALB)
|
|
- **Database**: Read replicas for reporting queries
|
|
- **Cache**: Redis Cluster (3+ nodes)
|
|
- **Workers**: Auto-scale based on queue depth
|
|
|
|
### Caching Strategy
|
|
- **API Responses**: Cache GET endpoints (5m TTL)
|
|
- **Database Queries**: Query result cache in Redis
|
|
- **Static Assets**: CDN (CloudFront) with edge caching
|
|
|
|
### Load Balancing
|
|
- **Application**: AWS ALB with health checks
|
|
- **Database**: pgpool for read/write splitting
|
|
- **Geographic**: Multi-region deployment (future)
|
|
|
|
## Security Architecture
|
|
|
|
### Authentication & Authorization
|
|
- **Strategy**: OAuth2 + JWT tokens (15m access, 7d refresh)
|
|
- **Storage**: httpOnly cookies for web, secure storage for mobile
|
|
- **Rotation**: Automatic token refresh
|
|
|
|
### Data Protection
|
|
- **At Rest**: PostgreSQL encryption (AWS RDS)
|
|
- **In Transit**: TLS 1.3 for all connections
|
|
- **Secrets**: AWS Secrets Manager, rotated monthly
|
|
|
|
### OWASP Top 10 Mitigations
|
|
- **Injection**: Parameterized queries (SQLAlchemy ORM)
|
|
- **Auth**: JWT validation, session management
|
|
- **XSS**: Content Security Policy, input sanitization
|
|
- **CSRF**: SameSite cookies, CSRF tokens
|
|
- **Rate Limiting**: Redis-backed (100 req/min per IP)
|
|
|
|
### Network Security
|
|
- **VPC**: Private subnets for DB/workers
|
|
- **Security Groups**: Least privilege access
|
|
- **WAF**: CloudFront WAF rules
|
|
|
|
## Deployment Architecture
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Public Subnet"
|
|
ALB[Application Load Balancer]
|
|
end
|
|
|
|
subgraph "Private Subnet - App Tier"
|
|
API1[API Container 1]
|
|
API2[API Container 2]
|
|
Worker1[Worker Container]
|
|
end
|
|
|
|
subgraph "Private Subnet - Data Tier"
|
|
DB[(RDS PostgreSQL)]
|
|
Cache[(ElastiCache Redis)]
|
|
end
|
|
|
|
Internet((Internet)) --> ALB
|
|
ALB --> API1
|
|
ALB --> API2
|
|
API1 --> DB
|
|
API2 --> DB
|
|
API1 --> Cache
|
|
API2 --> Cache
|
|
Worker1 --> DB
|
|
Worker1 --> Cache
|
|
```
|
|
|
|
## Monitoring & Observability
|
|
|
|
**Metrics**:
|
|
- API latency (p50, p95, p99)
|
|
- Error rates by endpoint
|
|
- Database connection pool usage
|
|
- Cache hit/miss ratios
|
|
|
|
**Logging**:
|
|
- Structured JSON logs (ECS logs to CloudWatch)
|
|
- Request ID tracing across services
|
|
- Error tracking (Sentry)
|
|
|
|
**Alerting**:
|
|
- API error rate >1%
|
|
- Database connections >80%
|
|
- Job queue depth >1000
|
|
|
|
## Future Considerations
|
|
|
|
**Phase 2 Enhancements**:
|
|
- GraphQL API option
|
|
- WebSocket real-time updates
|
|
- ElasticSearch for full-text search
|
|
|
|
**Phase 3 Scale**:
|
|
- Multi-region deployment
|
|
- Event-driven microservices
|
|
- CQRS for read-heavy workloads
|
|
```
|
|
|
|
## Guardrails
|
|
- Keep technology choices pragmatic (avoid hype-driven development)
|
|
- Consider team skills when selecting stack
|
|
- Prefer managed services over self-hosted for DevOps
|
|
- Include alternatives to show deliberate choice
|
|
- Use mermaid for all diagrams (portable, version-controllable)
|
|
- Keep each document under 400 lines
|
|
- Link to official docs for each technology
|
|
|
|
## Integration
|
|
- Run after PROJECT-OVERVIEW.md is created
|
|
- Feed into `/lazy plan` for user story creation
|
|
- Reference during `/lazy code` for implementation consistency
|
|
- Update during `/lazy review` if architecture evolves
|
|
|
|
## Example Prompt
|
|
> Design the tech stack and architecture for this project
|
|
|
|
## Validation Checklist
|
|
- [ ] TECH-STACK.md has all 4 categories (Frontend, Backend, Database, DevOps)
|
|
- [ ] Each technology has rationale and alternatives
|
|
- [ ] ARCHITECTURE.md has system overview + 3+ mermaid diagrams
|
|
- [ ] Authentication and data flow are documented
|
|
- [ ] Scalability and security sections are complete
|
|
- [ ] Trade-offs and migration path are clear
|