Entities

Reference for the main data models in the API. Each entry says what the entity is and why it exists; the per-endpoint docs define the exact field schema of each response.

Relationship overview

User (identity: phone)
 ├─ ClientProfile        one-to-one — the customer side of a user
 ├─ Driver               one-to-one — the cisternero side of a user
 │   ├─ Vehicle          the truck (capacity, hose, motopump, radius)
 │   └─ DriverDocument*  KYC documents (ID, vehicle photos, …)
 └─ Wallet               balance, pending payout, cash debt

Order (placed by a client, served by a driver)
 ├─ OrderOffer*          driver candidacies / counter-offers
 ├─ OrderBreakdown       money split (base, commission, solidarity, payout)
 ├─ OrderStatusChange*   status transition log
 ├─ OrderIncident*       disputes / problems raised on an order
 ├─ Payment*             charge attempts (online methods)
 └─ Rating               client → driver score after delivery

Admin (back-office operator)  ── scoped to one or more City
City ─ Community                geographic segmentation
FillingStation                  water sources (with StationComment / StationReport)

Identity & profiles

Entity	Description
`User`	Base identity. Authenticates by phone (OTP). May own a client profile, a driver profile, or both.
`ClientProfile`	The customer facet of a user: aggregate stats (total orders, total liters ordered, total solidarity).
`Driver`	The cisternero facet: KYC state, online status, available liters, rating, certification.
`Admin`	Back-office operator with a separate auth token. May be super admin or scoped to specific cities.

Fleet & KYC

Entity	Description
`Vehicle`	The driver's truck: plate, `capacity_liters`, hose length, motopump, operation radius.
`DriverDocument`	KYC documents uploaded by a driver, each with a review `status`.

Orders

Entity	Description
`Order`	A water request: location, liters, water type, payment method, and the resulting money breakdown. Drives the whole lifecycle.
`OrderOffer`	A driver's candidacy for an order — accept-at-price or a counter-offer with its own gross/ETA.
`OrderBreakdown`	Per-order money split (base price, Agüita commission, solidarity, driver payout).
`OrderIncident`	A problem/dispute raised against an order.
`Rating`	Client → driver score (plus comment/tags) recorded after delivery.

Money

Entity	Description
`Wallet`	Per-user balance, pending payout, and cash debt (with a cap that gates going online).
`WalletTransaction`	Ledger entry for every wallet movement.
`Payment`	A charge attempt for online payment methods (e.g. Pago Móvil / Sypago).
`PaymentMethod`	Catalog of integrations that can be toggled on/off.
`PaymentForm`	Manual payment instructions a customer can pay against (`PAYMENT_FORM`).
`Payout` / `PayoutConfig`	Driver payouts and their configuration.
`SolidaryContribution`	Records each contribution to the solidarity fund.
`Currency`	Currency catalog and exchange rate used to display/convert amounts.

Geography

Entity	Description
`City`	Operating city; admins are scoped to one or more cities.
`Community`	Sub-area within a city.
`SavedAddress`	A customer's reusable delivery addresses.

Stations & other

Entity	Description
`FillingStation`	Water source where drivers refill, with `StationComment` and `StationReport`.
`SurplusListing`	Surplus water a driver offers outside the normal order flow.
`ChatMessage`	In-order chat between client and driver.
`PlatformSetting`	Admin-tunable platform settings.