# Stack Decisions Log

Use this document to capture the "why" behind platform and tooling choices. Treat each entry as a lightweight ADR (Architecture Decision Record).

## Template baseline
- **Framework**: Next.js + TypeScript (edge-friendly, hybrid rendering, great DX)
- **Testing**: Vitest (fast unit/integration runner with React ecosystem support)
- **Styling**: Tailwind CSS or CSS Modules (choose one per project)
- **Deployment**: Cloudflare Pages + Workers (immutable deploys, global edge)
- **Database**: PostgreSQL (Supabase/Neon friendly), accessed via ORM of choice
- **Storage**: S3-compatible buckets (AWS S3, Cloudflare R2)

## Recording a decision
1. Title — short phrase (`Adopt Drizzle ORM`, `Switch CI to Woodpecker`)
2. Context — what problem are you solving? Mention constraints, stakeholders, and trade-offs.
3. Decision — what did you pick and why?
4. Status — proposed, accepted, deprecated, superseded.
5. Consequences — positive and negative effects, migrations required, follow-up work.

## Example entry
```
## Adopt Drizzle ORM
Status: Accepted (2024-02-12)
Context: Need a type-safe query builder that works in serverless environments without generating heavyweight clients.
Decision: Replace Prisma with Drizzle ORM because it offers SQL-first migrations, small runtime footprint, and better edge compatibility.
Consequences:
- Rewrite existing Prisma migrations → Drizzle SQL migrations.
- Update CI to run `drizzle-kit push` instead of `prisma migrate deploy`.
- Developers need to learn the new query builder API.
```

Keep this log close to the code. When you revisit a project months later, these notes will save hours of rediscovery.