# System Context

> **KB version:** 2.0 · **Code baseline:** `b71c156` · **Last reviewed:** 2026-10-26
> **Epic:** EP-TBD · **Status:** Pending PO review
> **Pending PO review:**
> - Order lines can be customised before being added (ingredient replacement with optional extra charge, ingredient removal, add-ons sold as their own order lines).
> - External platforms push catalog data (ingredients, items with recipes, replacements, add-ons) into Dinex, so the menu catalog is partly owned outside Dinex.
> **Related flags:** TBD (requires As-Built Spec cross-reference, out of scope this pass) · **Open decisions:** none

---

# Dinex — Business Knowledge Base

> **Purpose of this document:** Single source of truth for the business logic of the Dinex restaurant POS platform, reverse-engineered from the codebase (Laravel backend, API-only).
> It is written for Product Owners, Business Analysts, and new engineers joining after the original developers left.
> Every rule below was inferred from actual code (controllers, services, repositories, validations, migrations, seeders, config). Nothing is invented; anything uncertain is listed under *Open Questions*.

> **Provenance:** The whole knowledge base is reverse-engineered from the Dinex codebase. Each module file's own header carries the commit it was read against (`Code baseline`) and the date it was last reviewed; dated history of what changed and why lives in `docs/KB_CHANGELOG.md`.

---

## System Context (read this first)

**Dinex is a multi-branch restaurant Point-of-Sale (POS) and back-office system for a UAE restaurant business** (the seeded brand is "Asparagus"). It consists of:

| Surface | Consumers | Route file |
|---|---|---|
| **POS API** (`/api/v1/pos/...`) | Cashier & Kitchen (chef) touch-screen apps in branches | `routes/api/v1/pos.php` |
| **Dashboard API** (`/api/v1/dashboard/...`) | Head-office back office (admins) | `routes/api/v1/dashboard.php` |
| **Auth API** (`/api/v1/auth/...`, `/api/v1/platform/...`) | All clients + external platforms | `routes/api/v1/auth.php` |
| **Marketplace webhooks** (`/api/v1/webhooks/noon/...`) | Noon delivery fleet | `routes/marketPlaceWebhooks.php` |

**Core business flows:**
1. Cashier builds an order from a menu (categories/items), applies discounts/promo codes, takes payment (possibly split across payment methods), and prints a thermal invoice (PDF). Each menu line can be customised before it is added — a recipe ingredient can be swapped for a configured alternative (which may carry an extra charge) or removed where the recipe allows it, and add-ons can be sold alongside a meal as order lines of their own (see Modules 3 and 4).
2. A kitchen screen ("chief" role) tracks preparation status separately from the financial status.
3. At end of business day, the cashier "closes the day": a Daily Sales Report (DSR) is generated, the order-number sequence resets, and orders are frozen for reporting.
4. External orders arrive from the **Asparagus Mobile App** (a "Platform") via an authenticated platform API; the cashier approves or rejects them; approved *delivery* orders are handed to **Noon** (third-party delivery fleet) and tracked via webhooks.
5. Head office monitors sales, discounts, tax, payments, and branch performance via reports and charts.
6. Authenticated external platforms also push **catalog** data into Dinex — ingredients, and items with their recipes, ingredient replacements and add-ons — so the menu catalog is only partly owned inside Dinex; CostControl and the mobile app are upstream owners of parts of it (see Modules 3 and 5).

**Money model:** All amounts are implicitly **AED** (UAE). VAT is **5%**, and menu prices are always **VAT-inclusive**. Time is business-relevant in **Asia/Dubai** timezone.

**A "business day" is not a calendar day.** It runs from the first open order until the cashier closes the day (see Module 6). All reporting pivots on `related_date` — the date the business day *opened*.

---