Terminology

This glossary covers every key term used in Surplus. Terms are grouped by category and cross-linked to relevant guides. If you encounter a word in the app or documentation that isn't here, check Key concepts for a narrative explanation.

Organizations

Donor

An organization that donates food. Donors can be farms, retailers, restaurants, wholesalers, caterers, event venues, or any entity with surplus food to give. Each donor can have multiple donor locations (physical addresses where pickups happen). In the app, donors are managed by admins and see their own donor dashboard.

Recipient

An organization that receives food to serve the community. Recipients include food banks, shelters, school meal programs, community fridges, soup kitchens, and similar organizations. Each recipient has recipient locations where deliveries are made or food is picked up. Recipients access their recipient dashboard.

Carrier

A third-party logistics provider that supplies vehicles and drivers under contract. Not all programs use carriers — some rely on volunteer drivers — but when a carrier is assigned to a route, only that carrier's registered drivers can be assigned. Carriers are organizational entities; individual drivers are users linked to a carrier.

Hub

A system-owned warehouse where food is received, stored, sorted, and redistributed. Hubs are the operational center of Surplus logistics — food arrives via route unloads or direct donor drop-offs, gets sorted and staged, then leaves via route loads or direct recipient pickups. See Hub operations.

Compost partner

A recipient organization configured as a hub's compost destination. When food is sorted and trim/waste needs to be recorded, the compost partner receives those items as a completed compost event. Each hub has one configured compost partner.

Holding partner

A recipient organization flagged as a staging or holding entity rather than a final community recipient. Distributions to holding partners are excluded from unscoped analytics totals to prevent double-counting (the food hasn't reached its final destination yet).

People

User

Anyone with a Surplus login. Users have permissions that control what they can see and do (driver, admin, partner access, etc.). A single user can have multiple roles — for example, someone who both drives and manages a recipient location. Users are linked to organizations through association records, not a single "type" field.

Driver

A user with driver permissions who executes routes in the field. Drivers can be volunteers (using personal vehicles) or employees of a carrier. In the app, drivers see their assigned routes and personal impact.

Admin

A user with administrative permissions who manages the full operation — routes, hubs, organizations, analytics, and settings.

Partner user

A user linked to a donor or recipient organization who accesses the partner dashboard. They see only their own organization's data.

Logistics

Route

A vehicle's physical journey for a day or shift. A route has an ordered list of stops, assigned drivers, timing, and a status lifecycle (scheduled → active → completed). Routes are about movement — they connect events (collections, distributions, loads, unloads) into one executable plan. See Managing routes.

Stop (route stop)

A single point on a route with a sequence number and type. Stops must be completed in order. Each stop references one event (a collection, distribution, load, or unload). See Completing a route.

Collection

Food entering the Surplus system from a donor. A collection records what was received (products, weights, quantities) as collection event items. Collections happen on routes (driver pickup) or at hubs (donor drop-off). Also called a "pickup" in casual conversation. See Hub collections.

Distribution

Food leaving the Surplus system to a recipient. Items must be allocated to a distribution before it can be completed. Distributions happen on routes (driver delivery) or at hubs (recipient pickup). Also called a "delivery" or "drop-off." See Hub distributions.

Load

Food moving from a hub warehouse onto a route vehicle. Loads are stops on a route that physically transfer custody of staged inventory from the warehouse to the driver. Until a load is completed, linked items stay at the hub even if they're allocated.

Unload

Food moving from a route vehicle into a hub warehouse. Unloads transfer items from the vehicle back into warehouse inventory. Used when food collected on a route needs to go through a hub before redistribution, or for hub-to-hub transfers.

Hub-connected distribution

A distribution that has both a hubId (source warehouse) and a routeId. This means the food is sourced from hub inventory, loaded onto a route, and delivered to a recipient. The route must have a load stop at the hub before the distribution stop.

Inventory

Collection event item

A line on the donation receipt — one row per product type in a collection. Records the product, quantity, and weight as reported by the donor/driver. This is the permanent record of what was donated. Collection event items are never destroyed by splits or downstream operations.

Item (operational partition)

The logistics tracking layer. Each item row represents a physical portion of food with:

• Status — where it is in the lifecycle
• Location — which hub (hubId) or route (routeId) it's on
• Quantity and weight — how much food this partition represents
• Collection event item ID — links back to the donation receipt line

Multiple items can exist under a single collection event item (from splits). Items are the rows that move, get allocated, and change status.

Status (item status)

The lifecycle state of an inventory item:

Split

Dividing one item row into two. The source row's quantity is reduced (shrunk) and a new row is inserted with the carved-off portion. Both rows share the same collectionEventItemId. Splits are used for partial allocations, partial sorts, and hub-to-hub transfers of partial quantities.

Merge

Combining two compatible item rows into one. The inverse of a split — used to consolidate rows that share the same identity (product, lot code, quality, location, status). Merges keep inventory clean and reduce row proliferation.

Sort

Processing a hub inventory item by weighing the usable portion separately from waste. Sorting sets isSorted = true on the item, updates its weight to the usable amount, and creates a compost partition for the trim. To sort only part of a batch, split first, then sort the portion.

Allocation

Reserving inventory for a specific distribution by setting the item's status to allocated and linking it to a distribution event ID. Allocation is not movement — the item stays where it is until the distribution (or its upstream load) completes.

Lot code

A tracking identifier for a batch of food. The base lot code comes from the collection event item (generated or explicit). When items are split for sorting, the new partition gets a lot code with a sort suffix (e.g., BASE-S1).

Quality

An optional field on items for internal logistics purposes (grading, condition notes). Quality is tracked on operational items, not on collection event items — it's a logistics concern, not a donation record concern.

Events and statuses

Event status lifecycle

Most events follow:

scheduled → completed
         ↘ cancelled

Routes add an intermediate state:

scheduled → active → completed
                  ↘ cancelled
         ↘ cancelled

Scheduled

The event is planned but hasn't happened yet. Items can be allocated to scheduled events, stops can be modified, and the event can be cancelled.

Active (routes only)

The route is in progress — a driver is on the road. Stops can be completed in sequence.

Completed

The event has been executed successfully. Depending on the event type, completion triggers physical inventory movement (loads, unloads) or status finalization (distributions → distributed).

Cancelled

The event has been abandoned. Cancellation is terminal — a cancelled event cannot be re-scheduled. Cancellation typically triggers cleanup: releasing allocations, reverting inventory movements, etc.

Un-complete (admin action)

Admins can revert a completed event back to its pre-completion state to fix errors. This undoes the completion's side effects (inventory movements, status changes) where possible.

Impact and analytics

Pounds rescued

Total weight of food successfully distributed to recipients. Calculated as sum(quantity × weight) across all distributed items. See Impact Measurement.

Meals made possible

Estimated community servings: sum(round(line_lbs / 1.2)). A communication tool using the Feeding America conversion factor, not a literal meal count.

Retail value

Estimated dollar value based on food category reference prices from ReFED/USDA data. Varies by product type.

Fair market value

Flat-rate per-pound valuation ($1.92/lb) from the Feeding America benchmark. Used for tax receipts and funder reporting.

Downstream emissions prevented (CO₂e)

Estimated CO₂ equivalent prevented from entering the atmosphere by diverting food from landfills. Category-based sum using EPA WARM v16 landfill factors (0.25–1.09 lbs CO₂e/lb depending on food type). Prevents methane-generating decomposition.

Upstream emissions diverted (CO₂e)

Estimated production-phase CO₂ equivalent represented by rescued food kept in use. Flat rate of 3.66 lbs CO₂e/lb from EPA WARM v16 Food Waste production emissions factor — carbon already emitted to produce food that would otherwise be wasted.

Waste cost savings

Estimated disposal costs avoided: sum(line_lbs × 0.05). Represents tipping fees and collection costs prevented.

Technical terms (brief)

ORPC

The RPC framework used for all client-server communication in Surplus. Defines typed contracts between frontend and backend.

Drizzle

The TypeScript ORM used for database schema definition and queries. The schema in packages/postgres/src/schema/ is the source of truth for the database.

Service

A domain-scoped module in packages/services/ that implements business logic. Services receive dependencies (database, storage, etc.) via injection and are called by server routes.