Correspondents/docs/stack-decisions.md

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.