ADR-0008: Adopt supastarter-nextjs as the foundation

• Date: 2026-09-18
• Status: Accepted
• Deciders: the owner, Claude
• Tags: infra strategy

Context

The owner asked for a proven foundation instead of a bespoke seed. Speed to the wedge (Phase 1) is the binding constraint, and the bespoke Cloudflare-first seed (ADR-0002) would have spent Phase 0 re-implementing what a mature starter already ships: multi-tenant organizations, authentication with passkeys and 2FA, subscription billing, i18n, mail, storage, an admin area, and a documentation app. supastarter-nextjs provides all of this on Next.js 16 App Router, React 19, Tailwind v4, Base UI, oRPC + Hono, Better Auth, Prisma + Drizzle, next-intl, Turborepo, and pnpm, with an AGENTS.md that encodes its conventions.

Decision

Adopt supastarter-nextjs as the foundation of this monorepo.

• The starter is imported as git remote upstream; the ability to merge upstream releases is preserved by keeping supastarter's package boundaries and conventions (AGENTS.md).
• Demo content is stripped: sample logos, testimonials, portraits, blog posts, "built with" credits, the olive theme, unused locales (de, es, fr), and the payment providers other than Stripe (LemonSqueezy, Polar, Creem, Dodo). Stripe stays as the reference implementation; a moyasar provider is added for the Saudi market.
• Our seed survives as packages on top: @repo/core (module contract, events, Sector Packs, tenant context), @repo/module-registry, @repo/sms, and the extended Organization + Location models.
• Authentication: Better Auth with phone OTP (added), email + password, magic link, Google, passkeys, 2FA; GitHub removed. The organization is the tenant (requireOrganization: true).
• Design: every surface follows the glass design contract in docs/design/glass-design-system.md; fonts IBM Plex Sans Arabic; accent OKLCH hue 165.
• Documentation: the repo's docs/ folder is the handbook, rendered by apps/docs (Fumadocs), in English (ADR-0009).
• Runtime: Node.js Next.js. The production target (Vercel, Docker, or Cloudflare via OpenNext) is still open. Cloudflare remains the edge layer for DNS, Cloudflare for SaaS, R2, and the planned storefront / jobs Workers.

Consequences

• Positive — Phase 0 shrinks to configuration and branding; auth, billing, organizations, i18n, and admin arrive tested; upstream fixes can be merged.
• Negative — we inherit supastarter's opinions (Prisma as schema owner, Node runtime, Base UI); upstream merges will conflict where we diverge (design system, removed providers); the module contract must be layered on rather than designed in.
• Licence — supastarter is a commercial licence owned by the founder; do not redistribute the starter code. Third-party add-ons in the Marketplace must be built against our public contract, never by copying the repository.
• Revenue impact (monthly, confidence) — indirect but large: brings first revenue (the plan prices in packages/payments/config.ts) forward by an entire foundation phase and removes the risk of a home-grown auth or billing defect (high confidence).

Rejected alternatives

• Continue the bespoke Cloudflare-first seed (ADR-0002): months of scaffolding before the wedge, with untested auth and billing.
• Other starters (generic shadcn / T3 / Supabase templates): no organization model, no billing, or no i18n out of the box; each would need the same layering with less coverage.
• A headless BaaS (Supabase / Firebase) as the core: pulls the domain model into a vendor and complicates the choice of Postgres region.

References

• AGENTS.md, ADR-0002, ADR-0009, docs/design/glass-design-system.md