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:

EventMeaning
CollectionFood entering the system from a donor
DistributionFood leaving the system to a recipient
LoadFood moving from a hub onto a vehicle
UnloadFood moving from a vehicle into a hub
CompostFood 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:

  1. Collection event items — the receipt: per-line record of what was collected (product, quantity, weight). Immutable after creation.
  2. 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.