Data model overview

Surplus tracks food from donation through warehouse and route logistics to distribution (or composting when applicable). The database is PostgreSQL with schema defined in Drizzle (packages/postgres/src/schema/).

Concepts (external summary)

• Donors and recipients are organizations; donor locations and recipient locations are addresses and site metadata.
• Collections record food entering the system; distributions record food leaving it.
• Collection event items are donation line items (product, weight, quantity).
• Items are operational partitions under a collection event item (location, status, quantity, optional internal quality). Inventory moves, splits, allocations, and terminal statuses are modeled at this layer.
• Routes, stops, loads, and unloads describe vehicle and hub movement.

Conventions

• UUIDs for primary keys.
• Unix epoch seconds for timestamps (not timestamp with time zone in application shape).
• camelCase SQL identifiers in the Drizzle layer.

Where to go deeper

• Authoritative columns and constraints — Drizzle sources linked from the repo: packages/postgres/src/schema.
• Long-form narrative for engineers and agents — docs/data-model.md in the Surplus repository (companion to the schema, not a second source of truth).

This documentation site intentionally keeps database content short; follow the links above when you need exact field names or relationship detail.