Mauza Order Rules — Canonical Reference

The single authoritative description of how an order works: every happy path, every unhappy path, who is responsible at each step, the time limits, who gets told what, and who bears the cost. Written to be readable by non-engineers.

Audiences & how to use this doc

• Investors / leadership — §1 (the model), §2 (happy path), §4 (how failures are handled and why the platform stays solvent).
• Employees / new hires — read top to bottom; it's the mental model of the product.
• Customer service / operations — §3 (states & timeouts), §4 (failure playbook), §6 (reason codes), §7 (who-pays) are the day-to-day reference.
• System fine-tuning meetings — §3 and §8 are the tunable parameters.
• Customer / restaurant / carrier communication & agreements — §5 are the plain-language rules for each party; §7 is the cost/liability allocation that belongs in the terms.
• Documenters — this is the source; user-facing help articles derive from §5.

Status of the rules. ✅ = built and live. 🔜 = rule defined here, mechanism (mostly money) built later (docs/order-completion-and-capture.md, docs/dispute-and-accountability.md, docs/payments.md). Parameters marked (tunable) are platform defaults that operations adjusts from real data.

1. The model in one picture

An order moves through a sequence of states. Each non-final state is a promise: someone has to do something, by a deadline. If they do it, the order advances. If they don't, the platform steps in automatically. Every order ends — always — in one of four final states. Nothing is ever left hanging.

   placed ─► confirmed ─► preparing ─► ready ─► carrier ─► at        ─► picked ─► DELIVERED ✅
   (cust)    (rest.)      (rest.)      (rest.)  assigned   restaurant     up        (carrier)
                                                (carrier)  (carrier)    (carrier)

   any non-final state can also end in:   REJECTED ✗   CANCELLED ✗   FAILED ✗

• DELIVERED — the happy ending: the customer got their food.
• REJECTED — the restaurant declined the order (only at the very start).
• CANCELLED — someone (customer, restaurant, or platform) cancelled it.
• FAILED — the platform could not complete it despite trying (e.g. no carrier was ever available, or a carrier took the food and never delivered).

Three parties act, plus the platform: customer (orders), restaurant (cooks), carrier (delivers), Mauza (coordinates, and steps in when something stalls).

2. The happy path — start to finish ✅

At every step the relevant parties are kept informed in real time (see §4 for the exact "who gets told what").

3. The states, their deadlines, and the safe default

Every non-final state has a time limit and an automatic action if the limit passes. These are the platform's safety net: the order never sits forever. All timeouts are platform defaults — (tunable) per the fine-tuning meetings.

Carrier matching parameters (tunable): the platform first searches within 2 km, then widens to 5 km; each carrier has 60 seconds to accept an offer before it moves to the next; up to 5 attempts before giving up.

These numbers are first-pass defaults to tune against real Helsinki data — the exact values are an operations decision, not a code change.

4. The unhappy paths — every way an order can go wrong, and what happens ✅

The governing principle (the Automagic chain): detect the problem → fix it automatically if possible → offer the affected person a choice if one exists → fall back to a safe default → only involve a human when nothing else resolves it. And always: inform every affected party what is happening and why.

4.1 Restaurant problems

4.2 Carrier problems (the most common real-world failures)

4.3 Customer actions

4.4 Who gets told what — the notification matrix ✅

Every state change and every problem notifies the affected parties (in their own language). Today's wiring:

Rule of thumb: whenever something goes wrong, everyone involved in that order learns the new state and the reason — no one is left guessing.

5. The rules, per party (plain language — for help articles & agreements)

For customers

• You're told at every step where your order is.
• If the restaurant can't take your order, you're told why and not charged.
• If the restaurant doesn't respond in 5 minutes, your order is cancelled and refunded automatically.
• If no carrier can be found, we keep trying; if we genuinely can't, you're refunded (or offered self-pickup) — you never pay for food you didn't get.
• If your food never arrives, you're made whole. 🔜
• You can cancel early; cancelling after cooking has started may not be fully refundable (policy 🔜).
• If something's wrong with a delivered order (cold, wrong, missing, didn't arrive), report it — we record it and look into it. Repeated false claims affect your standing 🔜.

For restaurants

• You see and accept (or decline) each order. Declining records a reason; it's fine to decline when you can't fulfil.
• Accept or decline within 5 minutes — unanswered orders auto-cancel.
• Mark preparing then ready so we can get a carrier on time.
• You are paid for food you made in good faith. If a carrier fails to deliver, that is not your loss — you are paid, the customer is refunded, and the platform covers the gap. 🔜
• You only bear a cost when the fault is yours (wrong / cold / missing items).
• If you run out of something, signal it — don't let the order stall.

For carriers

• You receive delivery offers; you have 60 seconds to accept each.
• Once you accept, you're committed to that pickup — if you genuinely can't continue, release the order with a reason so we can reassign it fast.
• Accepting and then going silent, or not delivering, counts against you. Repeated failures lead to suspension. Genuine accidents/emergencies are logged but not held against you — frequency is what matters. 🔜
• You are paid for good-faith work, including a delivery attempt that fails through no fault of yours. 🔜
• Report problems (food not ready, can't reach the customer) rather than abandoning the order.

For Mauza (the platform's promises)

• Every order reaches a clear conclusion — we never leave one hanging.
• We keep all three parties informed, with reasons, in real time.
• We make every innocent party whole and put the cost on the party at fault; where no one is at fault, we back-stop it. 🔜
• We track reliability and suspend chronically failing carriers — that's what keeps the guarantee affordable and the service trustworthy.

6. Reason codes (the structured "why" recorded on every non-happy outcome) ✅

Every cancellation, rejection, failure, and complaint records a code, so reports, customer service, and disputes work from facts, not guesses.

• Restaurant declines/cancels: out_of_stock, too_busy, closing, item_unavailable, kitchen_problem, duplicate_order, customer_request, other.
• Carrier failures: accident, vehicle_breakdown, cannot_reach_restaurant, cannot_reach_customer, customer_unavailable, address_wrong, food_damaged, personal_emergency, no_show, abandoned, other.
• Customer cancels: changed_mind, too_slow, ordered_by_mistake, wrong_items, duplicate, other.
• Customer complaints: never_arrived, missing_items, wrong_items, cold_food, quality, damaged, late, other.
• System (automatic): confirm_timeout, prep_timeout, no_carrier_available, dispatch_exhausted, delivery_timeout, handoff_timeout, admin_forced.

Alongside each, a fault tag is recorded — carrier / restaurant / customer / none / unknown — captured at the time, used later to decide cost.

7. Who bears the cost (liability allocation — for the agreements) 🔜

The mechanism (refunds/payouts) is built later; the rules are settled now and belong in the terms each party signs. Governing principle: whoever did real work in good faith is paid; the party at fault bears the cost; the platform back-stops so no innocent party is left short.

This is an insurance-style model: the platform makes innocent parties whole and recovers from the at-fault party. It stays solvent because (a) failure rates are kept low by tracking reliability and suspending chronic failers, (b) evidence (proof-of-delivery 🔜) lets the platform catch fraud, and (c) a small reserve from commission funds the back-stop.

8. The tunable parameters (for fine-tuning meetings)

One table of every knob, its current default, and who owns it. Changing these is configuration, not a rewrite.

Strike thresholds (how many carrier failures before auto-suspension) and refund amounts are open decisions — see §7 and docs/dispute-and-accountability.md.

9. What is built vs. what's coming

• ✅ Built & live: the full state machine incl. the failed terminal; every timeout and auto-action (the completion engine); reason + fault capture on every outcome; multi-party notifications; carrier release / report-problem; customer complaint. End-to-end tested with virtual users across every path.
• 🔜 Coming (rules defined here, mechanism later): money movement (charge/refund/payout), the who-pays matrix as executed transactions, proof-of-delivery capture (photo + GPS), the dispute/case system, and carrier reliability statistics → automatic suspension.

This document is the contract between the rules and everything built on them — keep it in sync as parameters are tuned and the 🔜 items land.

Engineering detail behind this reference: docs/order-flow-analysis.md, docs/order-completion-and-capture.md, docs/order-lifecycle-policy.md, docs/dispute-and-accountability.md, docs/payments.md.