/stack-baseline

name: stack-baseline
description: The pinned default technology stack for SMB Product-Builder products. One source of truth so the architect, app-scaffolder, auth-engineer, and senior-dev never re-decide the stack per build — they build ON it. Covers framework, ORM/DB, auth, UI, payments/email/SMS, files, jobs, testing, hosting, and observability, with the chosen default + the one sanctioned alternative for each. Applied whenever a new product is scaffolded or a stack choice would otherwise be improvised. Re-deciding the stack every build is the biggest silent time sink; this kills it.
when_to_use: |
  Apply when:
  - architect writes the Components / stack section of ARCH-{slug}.md
  - app-scaffolder stands up a new product skeleton
  - auth-engineer or senior-dev would otherwise pick a library/provider ad hoc
  Do NOT override a choice already pinned in PROJECT.md (an existing project's stack wins).
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - ".great_cto/**"

Stack baseline — decide once, build on it

Every SMB product builds on the SAME proven stack unless there's a concrete reason not to. Re-deciding framework/ORM/auth/host per build wastes the first hour of every project and fragments the codebase across products. **This is the default; deviate only with a written reason in ARCH.**

The pinned stack

| Layer | Default | Sanctioned alternative | Notes | |---|---|---|---| | **Framework** | Next.js (App Router, TS) | Remix | Server actions + RSC; one repo front+back | | **UI** | Tailwind + shadcn/ui | — | matches the site; design-advisor tokens map to it | | **Charts** (dashboard/analytics) | ECharts (shipped) | Recharts | polished specs generated at **build time via Flint → compiled to native ECharts**; Flint is dev-only, never a runtime dep. Contract: `references/dashboard-viz.md` | | **DB** | Postgres | — | the only DB; integer cents, tz-aware timestamps | | **ORM / migrations** | Drizzle | Prisma | typed schema + SQL migrations; migration-ready-schema applies | | **Auth** | Auth.js (NextAuth v5) | Clerk (fast path, per-MAU cost) | owned by **auth-engineer**; session + RBAC + multi-tenant | | **Payments** | Stripe (+ Connect) | — | owned by subscription-billing-engineer / integrations-engineer | | **Email** | Resend | Postmark | transactional; SPF/DKIM/DMARC via lifecycle-messaging | | **SMS** | Twilio (Messaging Service) | Telnyx | 10DLC; consent via lifecycle-messaging | | **File storage** | Cloudflare R2 / S3 | — | private buckets, presigned URLs | | **Background jobs** | Inngest | a Postgres-backed queue | reminders, syncs, dunning | | **Testing** | Vitest (unit) + Playwright (e2e) | — | senior-dev unit; e2e-test-engineer browser | | **Hosting** | Vercel | Cloudflare Pages/Workers | Next.js-native; preview per PR | | **DB host** | Neon (serverless PG) | Supabase | branchable; env-wired by infra-provisioner | | **Observability** | Sentry | — | errors + traces on the deployed product | | **Analytics** | privacy-light (Plausible) | — | no heavy 3rd-party trackers |

Rules

1. **One framework, one DB, one ORM, one auth lib** across all products. Consistency > per-product optimization. 2. **Pin it in `.great_cto/PROJECT.md`** at scaffold time (`stack:` line) so every later agent reads it instead of guessing — and an existing PROJECT.md's stack always wins. 3. **Money in integer cents; timestamps tz-aware; IDs are stable** (compose with `migration-ready-schema`). 4. **Auth, payments, email/SMS, jobs are owned by their specialist** (auth-engineer, billing/integrations, lifecycle-messaging) — this skill only names the default library; the specialist owns the contract. 5. **Deviation needs a written reason** in ARCH's Components section (e.g. "Clerk over Auth.js because the customer needs SSO/SCIM on day one").

Output

When applied, write the stack into ARCH's Components section and PROJECT.md:

## Stack (baseline)
framework: Next.js (App Router, TS) · UI: Tailwind + shadcn
db: Postgres (Neon) · orm: Drizzle · auth: Auth.js (→ auth-engineer)
payments: Stripe · email: Resend · sms: Twilio · files: R2 · jobs: Inngest
test: Vitest + Playwright · host: Vercel · obs: Sentry
deviations: <none | reason>