Developers

Welcome. This section is for the people who build and review Surplus: contributors writing code, engineers evaluating the platform, and technical reviewers who need to understand how everything fits together.

If you want to understand Surplus from a user's perspective first — what food rescue is and what the app does — start with the Platform docs. This section assumes that context and focuses on the implementation.

The 60-second mental model

Surplus is a single Bun monorepo. Everything lives in one repository and shares one dependency graph:

• A web client (apps/client) — a React single-page app that staff, drivers, and partners use in the browser.
• An API server (apps/server) — a Hono service that handles every read and write, backed by PostgreSQL.
• This documentation site (apps/docs) — the site you're reading now.
• Shared packages (packages/*) — the API contract, domain logic, database schema, types, and utilities that the apps build on.
• Cron workers (crons/*) — scheduled jobs for analytics caching and backups.

The single most important idea: the client and server never speak in hand-written REST calls. They share a typed contract, and every endpoint flows through the same four predictable layers. Once that clicks, the rest of the codebase reads quickly. We cover it in Request lifecycle.

Start here

If you're new, read in this order:

1. Quickstart — clone the repo, install, and get the stack running locally.
2. Architecture overview — the big picture, with a diagram of how the pieces connect.
3. Request lifecycle — how a single API call travels from the browser to the database and back.
4. The Stack — a guided tour of each app and package.

After that, dip into whatever you need: the data model, the API and contracts, our conventions, or the contributing guide.

What you can rely on

Surplus is built around a small set of non-negotiables that keep the codebase consistent. You'll see them everywhere:

• Bun only — Bun is the runtime, package manager, and test runner. There is no Node.js step and no separate TypeScript compile.
• End-to-end type safety — types flow from the database schema through shared packages to both the client and the server. We do not use any.
• Contract-first APIs — the ORPC contract is the single source of truth for every endpoint, and it generates the public OpenAPI spec for free.
• camelCase everywhere — tables, columns, files, and variables.

The Conventions page covers these in full.

Looking for security details?

Reviewers and auditors evaluating authentication, access control, data protection, or infrastructure should head to the dedicated Security & Compliance section. This Developers section explains how the system is built; the Security section explains how it's protected.