# 00 — Business Context

## 1. The business model

The company operates **five cafe branches**. Each branch is located **inside a
shared-workspace building** — a building that rents furnished business offices to
companies and individuals.

This location model is the defining characteristic of the system. A normal cafe sells to
strangers who pay and leave. This cafe sells to a **known, recurring, resident customer
base** that mostly does *not* pay at the counter.

```
        ┌────────────────────────────────────────────┐
        │  Shared-workspace building (office rental) │
        │                                            │
        │   Office 201 ── Tenant company A ──┐       │
        │   Office 305 ── Tenant company B ──┤       │
        │   Office 410 ── Tenant company C ──┼──▶ CAFE BRANCH
        │   Reception  ── Workspace staff  ──┤       │
        │                                    │       │
        └────────────────────────────────────┼───────┘
                                             │
                          Visitors / walk-ins┘
```

### Revenue streams

| Stream | Who | How they pay |
|---|---|---|
| **Walk-in** | Visitors, guests, passers-by | At the counter, immediately |
| **Tenant (rental) accounts** | Companies renting offices in the building | On account, billed on a cycle |
| **Workspace employees** | Individuals working in the building | On account, or immediately |

### Cost structure (all in scope)

| Cost | Nature | Notes |
|---|---|---|
| Cost of goods sold | Variable | Driven by recipes + purchase prices |
| **Branch rent** | Fixed, recurring | Each branch pays rent for its space |
| **Employee payroll** | Fixed + variable (advances, deductions) | Per branch |
| Utilities, gas, maintenance, transport | Mixed | Per branch |
| Supplier payables | Variable | Regular suppliers, possibly shared across branches |

---

## 2. Fixed constraints (given by the business)

These are not assumptions. They are stated requirements and the system may rely on them.

1. **All orders are takeaway.** There are no tables, no dine-in, no drive-thru,
   no floor plan, no table service, no course firing.
2. **There is no online ordering and no delivery outside the building.**
   All sales originate at a branch terminal.
3. **Branches are operationally independent.** Separate stock, separate staff,
   separate cash, separate rent, separate tenant lists.
4. **Suppliers may be shared between branches.** Supplier master data is therefore global;
   purchasing is per branch.
5. **Payment timing varies by customer**, including: immediately, daily,
   every N days, and monthly.
6. **Five branches**, in Baghdad, Basrah and Karbala. One is the **Main Branch**,
   where the owner is based. The Main Branch is a normal trading branch that
   additionally hosts head-office functions.
7. **Every day is a working day.** There is no fixed weekend. Non-working days exist only
   when the **owner declares one** ("tomorrow there is no work"), usually at short notice.
   The system therefore needs a **business calendar of owner-declared closures**, not a
   weekly pattern. See [10 — Cross-Cutting Rules §3](10-cross-cutting-rules.md).
8. **There are no prepaid packages or entitlements.** Tenants buy on open credit and are
   billed for what they consumed. Confirmed by the business.
9. **Employee funding policy differs per tenant office.** Some companies fund all their
   employees' consumption, some fund none, and some fund each employee up to a monthly cap.
   See [03 — Customers & Accounts §6](03-customers-and-accounts.md).

---

## 3. Actors

### Internal (system users)

| Actor | Scope | Primary jobs |
|---|---|---|
| **Owner** | All branches | Consolidated reporting, approvals, master data, credit limits |
| **Accountant** | All branches | Billing runs, collections, payables, payroll, reconciliation |
| **Branch Manager** | One branch | Daily operation, staff, stock, local reports, discount approval |
| **Cashier** | One branch, one shift | Take orders, take payment, charge to accounts, close shift |
| **Barista / Kitchen** | One branch | Prepare orders from the queue |
| **Storekeeper** | One branch | Receive goods, transfers, stock counts, waste |

### External (subjects, not users)

| Actor | Description |
|---|---|
| **Walk-in customer** | Anonymous, one-off, pays immediately |
| **Tenant company** | Rents an office; holds a credit account; is invoiced on a cycle |
| **Tenant employee** | Individual working for a tenant company; may charge to the company account |
| **Workspace employee** | Staff of the building/workspace operator; may hold an account or an allowance |
| **Supplier** | Sells inventory to one or more branches, on cash or credit terms |
| **Landlord** | Receives branch rent |

---

## 4. Glossary

| Term | Meaning in this system |
|---|---|
| **Branch** | One cafe location. The unit of operational and financial separation. |
| **Building** | The shared-workspace property a branch sits inside. Source of tenant accounts. |
| **Account** | A customer entity that can buy on credit and be billed later. |
| **Charge** | An on-account sale. Increases the account's balance. Not yet invoiced. |
| **Billing cycle** | The rule deciding when unbilled charges are closed into an invoice. |
| **Billing run** | The scheduled process that converts charges into invoices. |
| **Invoice / Statement** | The document issued at cycle close, listing charges and the amount due. |
| **Settlement** | Any act that discharges what is owed — payment now, or payment against an invoice. |
| **Tender** | A means of payment: cash, card, mobile wallet, bank transfer, on-account. |
| **Shift** | A cashier session with an opening float and a counted close. |
| **86'd** | Temporarily unavailable at a branch (sold out today). |
| **Modifier** | A per-item choice affecting preparation and price (size, milk, sugar, extra shot). |
| **Recipe** | The mapping from a menu item to the inventory it consumes. |
| **GRN** | Goods Received Note — confirmation that ordered stock physically arrived. |
| **Advance** (سلفة) | Salary taken by an employee before payday, deducted at payroll. |
| **Aging** | Breakdown of outstanding receivables by how overdue they are. |

---

## 5. Assumptions made (flag if wrong)

Engineering decisions taken where the brief was open. Safe defaults; revisit freely.

| # | Assumption | Consequence if wrong |
|---|---|---|
| ~~A1~~ | **RESOLVED.** "Workspace employees" means **staff of the building operator** — the company that runs the shared-workspace building. They are modelled as authorized persons on the **building operator's own company account**, which is an ordinary account with its own billing terms and funding policy. | — |
| A2 | Primary currency is **IQD**; **USD** may be accepted. Both supported, with a recorded exchange rate. | If USD is never used, the FX fields stay unused. |
| A3 | Tenants sometimes want coffee brought to their office. Modelled as a **fulfilment attribute** (office/floor) on a takeaway order — not a new order type. | Minor. |
| A4 | An account normally belongs to one building/branch, but cross-branch charging is possible for multi-site tenants, controlled by a flag. | Minor. |
| A5 | Payroll is calculated and recorded here, but salary *disbursement* happens outside the system (cash or bank). | Would need a disbursement/payment integration. |
| A6 | The system is a source of truth for **management** accounting, not a statutory ledger. It exports to accounting rather than replacing it. | Would require full double-entry GL. |

---

## 6. Open questions for the business

Answers change scope; none block starting Phase 1.

1. Is the cafe operator the **same company** as the workspace operator? If yes, tenant
   master data could be imported from the rental system instead of re-entered.
2. Is a **printed/stamped invoice** legally required for tenant billing, and in Arabic?
3. ~~Does any branch need **VAT / sales tax** on the receipt?~~ **Answered — see below.**
4. Are salaries paid **monthly on a fixed date** for everyone, or per-employee schedules?
5. Is an owner-declared non-working day a **paid day** for staff? Assumed yes, configurable
   per closure ([08 §4](08-expenses-payroll.md)).

### Answered

| Question | Answer | Effect |
|---|---|---|
| VAT / sales tax | **None — no VAT or sales tax at any branch** (owner, 2026-08-05) | `tax_class` (doc 02 §2) and `tax_total` (doc 04 §2) stay dormant at zero; receipts (Phase 3) and invoices (Phase 6) carry no tax line |
| Working week / weekend | **Every day is a working day**; closures are declared ad hoc by the owner | Business calendar replaces a weekly pattern |
| Prepaid packages / entitlements | **None** | Open credit only; no drawdown model needed |
| Who are "workspace employees" | **Staff of the building operator** | Authorized persons on the operator's company account |
| Per-employee spending limits | **Varies per office**: all funded / none funded / capped per employee | Funding policy + per-person caps |