Domain model
This page summarizes the domain nouns you'll see in API and MCP responses. For a full glossary with user-facing definitions, see Terminology.
Organizations
- Donors — organizations that donate food, with one or more donor locations (pickup addresses).
- Recipients — organizations that receive food, with recipient locations (delivery addresses).
- Carriers — logistics providers that supply vehicles and drivers under contract.
- Hubs — system-owned warehouses where food is stored, sorted, and redistributed.
People and access
- Users — anyone with a Surplus login. Each user has one permission:
admin,advisor,partner,driver, or suspended (null). - Partners are users linked to a donor or recipient organization — they see only their org's data.
Events — how food moves
Food movement is recorded as events, usually tied to a route stop or a hub action:
| Event | Meaning |
|---|---|
| Collection | Food entering the system from a donor |
| Distribution | Food leaving the system to a recipient |
| Load | Food moving from a hub onto a vehicle |
| Unload | Food moving from a vehicle into a hub |
| Compost | Food removed from inventory as waste |
A route is a vehicle's ordered journey (stops). Each stop corresponds to one of the events above. Routes are logistics; events carry the food data.
Inventory — two layers
Integrators working with inventory data should understand two distinct layers:
- Collection event items — the receipt: per-line record of what was collected (product, quantity, weight). Immutable after creation.
- Items — the operational layer: physical partitions with quantity, location, status (
active,allocated,distributed,composted), and optional internal quality.
Splits shrink a source item row and insert a new row — there is no parent/child item tree.
Analytics and impact
Impact metrics count food that completed distribution to recipients — not food merely collected or sitting in a warehouse. Holding partners (staging recipients) are excluded from unscoped totals to prevent double-counting.
Related guides
- Terminology — complete glossary
- App API — how the app's server calls work
- MCP integration — read-only tools for analytics and operational queries
