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

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

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

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)

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

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

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