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 the Mahalli 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 non-Saudi payment providers (LemonSqueezy, Polar, Creem, Dodo). Stripe stays as the reference implementation; a moyasar provider skeleton is added (Q13).
• 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 merchant (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 Mahalli 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 Q12. 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 (SAR / month, confidence) — indirect but large: brings first revenue (R1 subscriptions at 99 / 249 / 499 SAR) 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 Postgres-region decision (Q5).

References

• AGENTS.md, docs/02-architecture.md, docs/06-roadmap.md, ADR-0002, ADR-0009, docs/design/glass-design-system.md