What belongs in the core, the six product modules (payments, presence, social, ads, sites, marketplace), the cross-cutting Copilot, and how Sector Packs extend the product with data rather than code.

01 — Core, modules, and Sector Packs

1. The core — what must never be a module

Component	Responsibility
Tenant & Locations	The business (commercial registration, VAT, activity) and its branches (coordinates, hours, phone). Implemented as a Better Auth `Organization` extended with CR / VAT / sector / phone / city, plus a `Location` model (see `03-domain-model.md`).
Identity & Access	Phone OTP, email, Google, passkeys, and 2FA via Better Auth; roles (owner / manager / staff / accountant), invitations, sessions; Nafath verification later.
Brand Kit	Logo, colours (OKLCH), fonts, tone, key images. Read by the storefront, posts, and ads.
Catalog	Categories, items (product / service), variants, VAT-inclusive prices, images, per-branch availability.
Customers & Consent	Customers, tags, interaction log, PDPL consent per channel (SMS / WhatsApp / email).
Money (ledger-lite)	Orders, payments, payment methods, refunds, ZATCA simplified invoices. Holds no balance.
Assets	Media library on S3-compatible storage (R2) with image transformations.
Billing & Entitlements	Platform subscription, plans, add-ons, entitlements (paid feature flags). Billing is attached to the organization.
Events & Jobs	Outbox → queue → consumers. Every module publishes and consumes only through it.
Notifications	WhatsApp Business API, SMS (Unifonic / Msegat via `@repo/sms`), email, in-app push.
Copilot Runtime	Runs Claude with tenant-scoped tools, guardrails, and an audit log.

2. Modules — each one a package under `modules/` that implements `ModuleManifest`

2.1 `payments` — get paid any way

Payment links and QR codes per branch / order; a checkout page in the shop's name.
Methods: mada, Apple Pay, cards, STC Pay, Tabby, Tamara through the PSP (Moyasar / HyperPay / Geidea / PayTabs — open decision) and BNPL partner programmes.
BNPL onboarding assistant: collects Tabby / Tamara requirements from the merchant's data, submits the application, and tracks its status.
Automatic simplified invoice (QR TLV) for every payment, sent to the customer over WhatsApp.
Later: SoftPOS (Tap to Pay) on the phone.

2.2 `presence` — be seen on the map

Google Business Profile connection: sync hours / photos / branches, publish Posts, AI-assisted review replies, alerts on negative reviews.
Apple Business Connect, Snap Map (subject to API availability).
Local presence report (searches, calls, directions).

Design templates bound to the Brand Kit (offers, product, occasion, Ramadan / National Day / season).
A lightweight editor (text / image / short video) plus AI text and image generation.
Scheduling and publishing: Instagram, X, Snapchat, TikTok, Google Posts. A unified comments and messages inbox.
A suggested monthly content calendar per sector.

2.4 `ads` — one-click local ads

Connect ad accounts (OAuth): Google Ads, Snap Ads, TikTok Ads, Meta.
Local campaign templates: store visits (Performance Max), seasonal offer (Snap / TikTok), retargeting of paying customers (hashed audiences with consent).
Unified budget, ROAS report, waste alerts.
Billing on the merchant's own ad account at first (no fund custody); centralised spend management later.

2.5 `sites` — your storefront on your domain

A site generator with sector templates (menu, booking, catalog, gallery, contact) fed by the catalog, branches, and Brand Kit.
<slug>.mahalli.sa immediately, then a custom domain through Cloudflare for SaaS (automatic SSL, host-based routing).
The dashboard always stays on app.mahalli.sa (ADR-0004).
Local SEO (Schema.org LocalBusiness, sitemap, branch pages), contact forms, WhatsApp button, simple booking.

2.6 `marketplace` — the add-on store inside the product

First add-ons: accounting (embedded partner: Qoyod / Daftra / Wafeq — open decision), bookings, loyalty and coupons, light inventory, payroll (Mudad / GOSI) later.
Every add-on is a module with the same contract, a pricing plan, and entitlements. The platform takes a share of third-party add-ons.
A partner API and webhooks open the store to developers in a later phase.

3. The Copilot — cross-cutting across modules

"Weekly summary" over WhatsApp: sales, reviews, ad performance, and one suggested action.
"Write my offer post" / "Reply to this review" / "How much should I budget for a Ramadan campaign?".
Tenant-scoped tools, every call logged, no training on merchant data (ADR-0007).

4. Sector Packs — data, not code

Each pack is a configuration object (packages/core/src/domain/sectors.ts) that defines:

The catalog schema (example: restaurant = dishes + extras; salon = services + duration + staff member).
Site, post, and campaign templates.
Default KPIs (average ticket, returning customers, reviews).
Recommended modules and their order in onboarding.
Additional compliance requirements (example: clinic = patient consent).

Initial sectors: restaurant_cafe, salon_barber, clinic_small, retail_shop, auto_workshop, fitness_studio, education_center, services_generic.

Key	Arabic label	English label
`restaurant_cafe`	مطعم / كافيه	Restaurant / café
`salon_barber`	صالون / حلاق	Salon / barber
`clinic_small`	عيادة صغيرة	Small clinic
`retail_shop`	محل تجزئة	Retail shop
`auto_workshop`	ورشة سيارات	Auto workshop
`fitness_studio`	نادٍ رياضي	Fitness studio
`education_center`	مركز تدريب	Education centre
`services_generic`	خدمات عامة	Generic services

Core, Modules, and Sector Packs