Business logic

Cross-cutting rules that apply across endpoints.

Money representation

The base currency is USD.
API responses expose monetary amounts as a decimal _usd value (e.g. client_pays_usd).

Commission & solidarity

Configurable defaults:

Knob	Default	Meaning
Agüita commission	`18%`	Platform fee taken on an order.
Client solidarity	`1%`	Added on top of what the client pays; feeds the solidarity fund.
Driver solidarity	`1%`	Withheld from the driver's gross; feeds the solidarity fund.

Both solidarity slices flow into the solidarity fund, used to support the community.

Order money breakdown

A delivered order's receipt exposes the full split (see Orders → receipt):

Field	Side	Meaning
`base_price_usd`	—	The water price the client set when ordering.
`client_solidary_usd`	client	+1% solidarity added on top.
`client_pays_usd`	client	What the client pays in total.
`aguita_commission_usd`	platform	Agüita's revenue (18%).
`driver_gross_usd`	driver	Driver's gross before withholdings.
`driver_solidary_usd`	driver	−1% solidarity withheld.
`driver_receives_usd`	driver	Net the driver actually receives.
`solidary_fund_usd`	fund	Total routed to the solidarity fund.

Order lifecycle

An order moves through the following statuses:

BROADCASTING ─▶ COUNTER_OFFERED ─▶ WAITING_FOR_PAYMENT ─▶ CONFIRMED
                                            │                  │
                                            └──── cash ────────┘  ▼
                                                              IN_PROGRESS ─▶ ARRIVED ─▶ DELIVERED

                       any pre-delivery state ─▶ CANCELLED
                       broadcast with no taker ─▶ EXPIRED

Status	Meaning
`BROADCASTING`	Just created; offered to nearby online drivers.
`COUNTER_OFFERED`	At least one driver replied with a counter-offer.
`WAITING_FOR_PAYMENT`	Accepted via an online method; awaiting payment confirmation.
`CONFIRMED`	Payment guaranteed. Cash orders skip straight here (collected on delivery).
`IN_PROGRESS`	Driver started the trip.
`ARRIVED`	Driver reached the destination (within 500 m).
`DELIVERED`	Water delivered and confirmed with the 4-digit delivery PIN.
`CANCELLED`	Cancelled by client/driver/admin before delivery.
`EXPIRED`	Broadcast lapsed with no accepted offer.

Notes:

Initial status by method — cash → CONFIRMED; any online method → WAITING_FOR_PAYMENT.
Capacity reservation — statuses WAITING_FOR_PAYMENT, CONFIRMED, IN_PROGRESS, ARRIVED reserve the driver's liters.
Delivery PIN — exposed to the client only once the order is paid (CONFIRMED/IN_PROGRESS/ARRIVED); the driver submits it to mark delivery.

Broadcast & expiry

Knob	Default	Meaning
Broadcast radius	`15 km`	Radius used to pick nearby online drivers.
Order expiry	`5 min`	Lifetime of a broadcast before it expires.

Driver wallet & cash debt

Cash orders are collected by the driver, so the platform's cut becomes a debt the driver owes. Each wallet has a cash-debt cap (default $20.00). Above the cap the driver cannot go online until the debt is settled.