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

•
Read PROJECT-OVERVIEW.md for:
- •Project goals and constraints
- •Scale requirements (users, data, traffic)
- •Team skills and preferences
- •Budget and timeline
- •Compliance requirements
•
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)
•
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

•
Design components:
- •Client-side architecture
- •API layer and services
- •Data storage and caching
- •Background jobs and queues
- •External integrations
•
Define data flow:
- •Request/response paths
- •Authentication flow
- •Data persistence patterns
- •Event-driven flows (if applicable)
•
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

code


## 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