Mahalli Handbook
What Mahalli is, how this handbook is organised, and the rules for contributing to it.
Mahalli Handbook
Mahalli (Arabic wordmark: محلّي) is the shop operating system for physical businesses in Saudi Arabia: be seen, get paid, stay in control — from one place. It gives a café, salon, clinic, workshop, or retail shop a storefront, a payment link that accepts mada, Apple Pay, Tabby, and Tamara, a managed Google presence, local marketing, and a marketplace of add-ons, all from a phone, in Arabic first.
This handbook is the source of truth for product strategy and architecture. It lives in the repository's docs/ folder and is rendered by apps/docs.
How the handbook is organised
| Section | What you will find |
|---|---|
| 00 — Vision | The original idea, its critique, positioning, ideal customer, the wedge, and the non-negotiable principles. |
| 01 — Core, Modules, and Sector Packs | What belongs in the core, the six product modules, the Copilot, and Sector Packs. |
| 02 — Architecture | The supastarter-based monorepo, technical decisions, multi-tenancy, custom domains, events, the module contract. |
| 03 — Domain Model | Entities and fixed rules, and how they map onto Better Auth organizations and Prisma. |
| 04 — Business Model | Revenue channels, plans in SAR, cost model, and the revenue impact of each module. |
| 05 — Compliance | ZATCA, SAMA, PDPL, CST, and the other Saudi regulatory constraints. |
| 06 — Roadmap | Phases by deliverable with exit criteria. |
| 07 — Go-to-Market | Channels, sequence, and messages. |
| 08 — Open Questions | Decisions still waiting on the owner. |
| Design | The glass design system contract that binds tooling/tailwind, packages/ui, and the apps. |
| ADRs | Architecture Decision Records. |
Contribution rules
- English. Everything in the repository — docs, comments, commit messages, pull requests — is written in English (ADR-0009). Arabic appears only as data: the wordmark, sector labels, and UI translations.
- Revenue first. Every recommendation states its expected impact in SAR / month, a confidence level (low / medium / high), and the revenue channel it affects (R1–R6 in
04-business-model.md). - No unverified claims. Compliance, data-residency, and performance statements are marked as open until verified with the authority or provider.
- Frontmatter. Every page carries
titleanddescription. Ordering is controlled bymeta.jsonin each folder. - MDX safety. Placeholders such as
<slug>.mahalli.saand objects such as{ tenantId }go in backticks or code fences.
The ADR process
- Copy
adr/0000-template.mdtoadr/NNNN-verb-object.mdwith the next number. - Fill in context, decision, consequences (including the revenue impact line), rejected alternatives, and references.
- Open it as Proposed. The owner's approval moves it to Accepted.
- A later decision that replaces it sets the old record to Superseded by ADR-NNNN with a short note; records are never deleted.
- Add the new page to
adr/meta.jsonin numeric order.