# Cafe Management System — Functional Documentation

Functional specification for a **multi-branch cafe operating inside shared-workspace
(office rental) buildings** in Iraq.

The repository contains the functional specification (docs 00–11), the platform decision
(doc 12), the ten-phase implementation plan (doc 13), and the **Phase 1 implementation**:
the shared kernel, dual-dialect test suite, sync contract, CI, release pipeline and
central backup job. Phase status is tracked in
[docs/17-phase-1-checklist.md](docs/17-phase-1-checklist.md).

---

## What this system is

| It IS | It is NOT |
|---|---|
| An in-store Point of Sale (takeaway only) | An online / delivery ordering platform |
| An Accounts Receivable system for office tenants | An e-commerce store |
| A per-branch inventory & purchasing system | A full accounting package (it feeds one) |
| A branch profitability tracker (rent + payroll + COGS) | An HR / recruitment system |

Five branches across **Baghdad, Basrah and Karbala**, one of which is the **Main Branch**
where the owner sits. Branches operate independently but may share suppliers and are
reported on together.

---

## Document index

| # | Document | Covers |
|---|---|---|
| 00 | [Business Context](docs/00-business-context.md) | Business model, actors, glossary, assumptions, open questions |
| 01 | [Organization & Access](docs/01-organization-and-access.md) | Branches, buildings, users, roles, permissions |
| 02 | [Catalog](docs/02-catalog.md) | Menu, modifiers, recipes, per-branch pricing & availability |
| 03 | [Customers & Accounts](docs/03-customers-and-accounts.md) | Walk-in, tenant companies, workspace employees, billing terms, credit |
| 04 | [Sales & POS](docs/04-sales-and-pos.md) | Order lifecycle, settlement, office delivery, voids & refunds |
| 05 | [Receivables & Billing](docs/05-receivables-and-billing.md) | Billing cycles, invoices, statements, payments, aging, collections |
| 06 | [Cash & Shifts](docs/06-cash-and-shifts.md) | Shift open/close, float, cash drops, variance |
| 07 | [Inventory & Suppliers](docs/07-inventory-and-suppliers.md) | Stock, purchase orders, receiving, transfers, waste, stock counts |
| 08 | [Expenses & Payroll](docs/08-expenses-payroll.md) | Branch rent, salaries, advances, utilities, supplier payables |
| 09 | [Reporting](docs/09-reporting.md) | Operational, financial and anti-fraud reports; branch P&L |
| 10 | [Cross-Cutting Rules](docs/10-cross-cutting-rules.md) | Money & IQD/USD handling, IDs, offline sync, audit, Arabic/RTL |
| 11 | [Roadmap](docs/11-roadmap.md) | Build order, phase scope, definition of done |
| 12 | [Stack & Platform](docs/12-stack-and-platform.md) | PHP everywhere, branch/centre architecture, hosting constraints, risks |
| 13 | [Implementation Plan](docs/13-implementation-plan.md) | Ten-phase build plan expanding the roadmap |
| 14 | [Conventions](docs/14-conventions.md) | Engineering conventions + decision log (enforced in review) |
| 15 | [Sync Contract](docs/15-sync-contract.md) | Versioned branch↔centre sync API (v1.0.0) |
| 16 | [Kernel API](docs/16-kernel-api.md) | The frozen shared kernel — reference and freeze policy |
| 17 | [Phase 1 Checklist](docs/17-phase-1-checklist.md) | Exit-criteria status, external actions, drill log |
| 18 | [Phase 2 Checklist](docs/18-phase-2-checklist.md) | Master data, access & catalog — status and deferrals |

---

## The five decisions everything else depends on

1. **Offline-first per branch.** A branch must keep selling with no internet.
   Sales are written locally and synced to the centre. Nothing on the POS blocks on network.
2. **Every record carries `branch_id`.** Enforced at the data-access layer, not by convention.
3. **A sale is either settled now or becomes a receivable.** There is no third state.
   This single rule generates the entire billing module.
4. **Financial documents are immutable.** Corrections are new opposing records
   (void, refund, credit note) — never edits.
5. **Branch profit = Sales − COGS − Rent − Payroll − Other Opex.**
   Rent and payroll are in scope precisely so this number exists.

---

## Reading order for a newcomer

Read `00` → `03` → `04` → `05`. Those four documents contain everything unusual about
this business. The rest is conventional cafe/retail functionality. Developers then read
`12` → `14` → `16` before writing code.

---

## Development quick start

Requirements: PHP ≥ 8.2 with `pdo_sqlite`, `pdo_mysql`, `mbstring`, `curl`; Composer;
a local MySQL 8 with a `cafe_test` database (see `phpunit.xml.dist` for credentials).

```bash
composer install
cp .env.example .env          # fill in local values
vendor/bin/phpunit            # full suite — runs against BOTH SQLite and MySQL
php bin/migrate.php central   # apply central migrations from .env
php bin/create-owner.php --phone="+964..." --name-ar="..." --name-en="..." --password="..."
php -S 127.0.0.1:8080 -t public public/index.php   # back office at /admin/login
php cron/run.php backup:dump  # run the backup job once
```

The suite must be green on **both** dialects before any merge
([docs/14-conventions.md §10](docs/14-conventions.md)).