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>