06 — Roadmap (by deliverable, no durations)

Every phase has a measurable exit criterion. We do not move on before it is met.

Phase 0 — Foundation on supastarter

• supastarter-nextjs adopted as the upstream (ADR-0008); demo content, unused locales, and unused payment providers removed; upstream remote kept for merges.
• Monorepo runs (pnpm + Turborepo), CI, dev / preview environments.
• Core in place: organization = merchant (extended with CR / VAT / sector / phone / city), Location model, memberships and roles, Better Auth with phone OTP, plans in SAR, @repo/core module contract + @repo/module-registry, outbox event names.
• Glass design system implemented in tooling/tailwind and packages/ui per docs/design/glass-design-system.md.
• Exit criteria:
  1. The glass design system renders on every surface of apps/saas, apps/marketing, and apps/docs, with the documented fallbacks.
  2. ar (default, RTL) and en locales work end to end; no physical-direction utilities in touched code.
  3. A merchant signs up with a phone number (OTP), creates their organization (the merchant business), and lands on an empty dashboard in their brand.
  4. Plans starter / growth / pro are priced in SAR and attached to the organization; a trial subscription can be billed.
  5. The Mahalli Handbook (this docs/ folder) renders in apps/docs in English with ADRs.
  6. pnpm lint, pnpm format:check, and pnpm type-check pass.
• Status (2026-09-18):
  • 1 — done: glass renders on saas, marketing, and docs in light and dark (screenshots reviewed); fallbacks compiled but not yet exercised under reduced transparency / forced colors.
  • 2 — done: ar and en bundles are structural mirrors (574 leaves); the cohesion audit finds no physical-direction utilities in touched code.
  • 3 — partial: phone OTP sign-in verified end to end against the local Postgres (send → verify → session with phoneNumberVerified); organization creation and the branded empty dashboard come from upstream and were not exercised in this pass.
  • 4 — partial: plans are configured in SAR and attached to the organization; billing a trial needs a PSP that serves Saudi merchants (open question Q2 / Q13 — Stripe is the reference implementation only).
  • 5 — done: the Handbook renders from the root docs/ folder.
  • 6 — done: format, lint, type-check (22 tasks) and unit tests (99) pass.

Phase 1 — The wedge: storefront + payments

• sites v1: <slug>.mahalli.sa, one template for each of 4 sectors, catalog / menu, branches on a map, WhatsApp (implemented).
• payments v1: payment links / QR, mada + Apple Pay + cards through the PSP (Moyasar), Tabby and Tamara as payment methods, ZATCA simplified invoice (QR) (implemented).
• presence v0: GBP connection and sync of hours / photos / branches.
• Wathq CR verification in onboarding with automatic Sector Pack suggestion and primary location seeding (implemented).
• Exit: 50 paying merchants (Design Partners), ≥ 60% of them have collected at least one payment, NPS ≥ 40.

Phase 2 — Presence and content

• presence v1: reviews + AI replies + Posts + presence report.
• social v1: brand-bound templates, text / image generation, scheduling and publishing to IG / X / Snap / TikTok, unified inbox.
• Custom domain (Cloudflare for SaaS, planned apps/storefront) + the Growth upgrade.
• Weekly summary over WhatsApp (Copilot v0).
• Exit: 30% of merchants on Growth or above, ≥ 4 posts / month per active merchant.

Phase 3 — Local ads

• ads v1: Google / Snap / TikTok connection, 3 campaign templates, consented customer audiences, ROAS report, waste alerts.
• Exit: 20% of merchants have launched a campaign; reported average ROAS ≥ 3× on store-visit templates.

Phase 4 — Marketplace and accounting

• marketplace v1: add-on catalog, install / uninstall, add-on billing.
• Accounting add-on through an embedded partner (invoice and expense sync, VAT return), and a bookings add-on.
• Partner API + documented webhooks.
• Exit: 30% of merchants with at least one add-on; first third-party add-on published.

Phase 5 — Scale

• Copilot v1 (tools across all modules), SoftPOS, additional Sector Packs, agent / reseller programme, small chains (multi-location dashboards).
• Exit: 1,000 paying merchants, churn ≤ 3%, gross margin ≥ 70%.

What we do not build in any of these phases

• A full POS, an online store with shipping and warehouses, full payroll, financing / lending, a standalone customer app (a PWA from the storefront is enough).