tuyv 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 |
| 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
- One framework, one DB, one ORM, one auth lib across all products. Consistency > per-product optimization.
- Pin it in
.great_cto/PROJECT.mdat scaffold time (stack:line) so every later agent reads it instead of guessing — and an existing PROJECT.md's stack always wins. - Money in integer cents; timestamps tz-aware; IDs are stable (compose with
migration-ready-schema). - 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.
- 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>