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

# 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

# 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

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

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

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

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