Hober

What it owns

Hober owns mutable runtime state. Mallow owns the finalised ledger — the Invoice that the Order becomes on close. They are deliberately different entities: different audiences (KDS reads Order, finance reads Invoice), different lifecycles (Order mutable, Invoice immutable), different timing (Order exists from open to close, Invoice exists from close forever).

On close, Hober triggers: Mallow Invoice generation, Trantor inventory consume per RecipeIngredient, Payments transaction reconciliation, and a Speaker receipt — all in one transaction. Any failure rolls back the close.

Concepts

Order

The live tab. Carries orderType (dine_in, takeout, delivery, retail_quick_sale, online_pickup, online_delivery), optional table ref (a Trantor DiscreteResource), party size, server, customer, and a denormalised total cache.

OrderLine

One item on the order. Snapshots unitPriceCents, displayName, and kitchenName at add-time, locking the price the customer saw. Status moves pending → fired → ready → served, with branches for cancelled, comped, and returned.

OrderLineModifier & CompositeFill

Modifiers attach to a line with a snapshotted price delta. Combo slots create sub-lines (parentLineId) rather than embedded data — KDS routes naturally, modifiers on the side work via the normal modifier table.

OrderPayment

An applied tender. Multiple per order for split-tender. Carries the tip (tip lives on the payment, not the order, so split tenders each carry their own tip). Optional appliedToLineIds for split-by-item, or an even-split endpoint that does server-authoritative N-way share math with exact penny-remainder distribution — the third split shape alongside split-by-item and split-by-seat.

OrderRefund & returns

A post-close refund / return path. An OrderRefund flips its lines to returned and books the reversal exactly once — either a Mallow CreditNote or a Payments refund, never both — with an optional card disbursement and a durable outbox subscriber that restocks Trantor inventory. A ledger-readiness probe hard-fails the refund up front when the tenant's Mallow accounts aren't seeded, rather than failing silently at posting time.

Subscriptions (v0)

Recurring revenue as a real state model. A Plan defines what recurs (price, cadence); a Subscription binds a customer to it; each billing period books a SubscriptionPeriodCharge. The billing cycle charges, invoices into Mallow, and advances the period — with pause / resume / cancel as first-class transitions. Beth reads subscriptions and operators manage them from the Demerzel console.

Lifecycle

OPEN → CLOSING → CLOSED, with VOIDED as the abandon branch. CLOSING blocks new lines while payment is in flight. CLOSED is terminal — voids, comps, and returns on closed orders become status changes on lines or new compensating orders, never deletes.

Table state

A dine-in table is held "until the tab closes," not "for a 90-minute window." Modelled as a state flag on the Trantor Resource with the Order id in linkRef, not as a ResourceHold. Different physics, different storage.

Snapshot at add-time

Every line, modifier, and composite fill captures priceCents and display names at the moment it was added. Catalog changes mid-order never move the goalposts on what the customer agreed to pay.

API surface

Endpoints are versioned under /order/v1/ — the wire namespace uses the descriptive name even though the primitive is "Hober," to match how POS UIs and integrations talk about orders.

Example: open, add, fire, pay, close

POST /order/v1/orders
{
  "orderType":  "dine_in",
  "tableId":    "res_table_07",
  "serverId":   "per_alice…",
  "partySize":  2
}
→ 201 Created  Order  ord_01JAZB…

POST /order/v1/orders/ord_01JAZB…/lines
{
  "productVariantId": "pvar_burger_single",
  "quantity": 2,
  "modifiers": [
    { "modifierId": "mod_medium_rare" },
    { "modifierId": "mod_add_bacon" }
  ]
}

POST /order/v1/orders/ord_01JAZB…/fire
POST /order/v1/orders/ord_01JAZB…/payments
{ "tenderType": "card", "amountCents": 3500, "tipCents": 500,
  "paymentMethodId": "pm_visa_4242" }
POST /order/v1/orders/ord_01JAZB…/close
→ 200 OK  Invoice  in_01JAZC…   (Mallow)

How it fits with the rest

flowchart LR
  Server[Server / customer] --> Ho(Hober Order)
  Ho -. catalog .-> Ha[Hardin]
  Ho -. table / inventory .-> T[Trantor]
  Ho -. identity .-> Te[Terminus]
  Ho -- close --> M[Mallow Invoice]
  Ho -- tender --> Pa[Payments]
  Ho -- receipt --> Sp[Speaker]
  Ho -- KDS --> D[Daneel]
            

Hardin is the catalog that lines reference and snapshot from. Trantor provides the table (as DiscreteResource state) and the inventory that close-time consume decrements. Terminus is the identity ref for server and customer. Payments processes each tender via an OrderPayment. Mallow generates the Invoice on close. Daneel runs the kitchen routing, coursing, and comp-approval workflows wired to OrderLine status events. Speaker sends the receipt, gated by Terminus consent.