Business logic

Cross-cutting rules that apply across endpoints.

Money representation

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.
Agüita solidarity 1% Agüita's own slice, mirroring the driver's. Carved out of the commission, so it costs the client and the driver nothing. Not settable on its own — it always equals the driver's percentage.

Three slices flow into the solidarity fund, used to support the community: the client's, the driver's, and Agüita's. Any breakdown of the fund shows the three, and they add up to its total.

Cash exception — cash orders (CASH_USD) charge no solidarity at all (client, driver, nor Agüita's mirror): client_solidary_usd, driver_solidary_usd and solidary_fund_usd are 0, client_pays_usd equals base_price_usd, and driver_receives_usd equals driver_gross_usd. Online methods apply the full 1% + 1% + 1% split.

Solidarity in litres — aguita.solidary.usd_per_1000_liters (5 by default) converts fund money into the litres of water it funds. It is a presentation rate only: nothing is charged or settled from it. Setting it to 0 turns every litre figure off rather than breaking. Always convert an aggregate, never sum conversions — each call rounds to the whole litre.

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 (0 for cash orders).
client_pays_usd client What the client pays in total (= base_price_usd for cash).
aguita_commission_usd platform Agüita's revenue (percentage fee calculated over base_price_usd).
driver_gross_usd driver Driver's gross before withholdings.
driver_solidary_usd driver −1% solidarity withheld (0 for cash orders).
driver_receives_usd driver Net the driver actually receives (= driver_gross_usd for cash).
aguita_solidary_usd platform Agüita's own solidarity slice, mirroring the driver's (0 for cash orders). Carved out of aguita_commission_usd — it does not add to client_pays_usd.
solidary_fund_usd fund Total routed to the solidarity fund: client + driver + Agüita (0 for cash orders).

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:

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 in physical currency, so the platform's cut becomes an outstanding cash debt (cashDebtUSD) the driver owes.