Developers

Surplus is a Bun monorepo: a React client, a Hono API server, shared packages for schema and domain logic, and scheduled jobs. This section covers the technical implementation — for product-level understanding of what Surplus does, see the docs home.

Getting started

If you're new to the codebase, read in this order:

1. Getting started — clone, install, run locally
2. Monorepo layout — what lives in each top-level folder
3. Architecture overview — ORPC, services, and data access patterns

Apps and packages

• Apps and services — apps/client, apps/server, apps/docs, crons, storage
• Shared packages — contracts, types, postgres, and related libraries

Reference

• Database model — schema design and relationships
• Dependency graph — how packages reference each other
• Code style — naming, patterns, and conventions
• Build and deploy — CI/CD, Docker, Railway
• Operations — monitoring, debugging, and maintenance

API and schema

• OpenAPI — generated from ORPC contracts; interactive UI at /openapi and JSON at /openapi.json on a running server (sidebar links target https://surplus-api.sharingexcess.com by default in production; override with NEXT_PUBLIC_SURPLUS_API_BASE_URL if needed).
• Database — Drizzle definitions under packages/postgres/src/schema/; narrative in docs/data-model.md on GitHub.

Product context

For understanding what Surplus does from a user perspective (useful for making design decisions):

• What is Surplus? — platform overview
• How it works — the food rescue lifecycle
• Key concepts — organizations, routes, events, inventory
• Terminology — glossary of all domain terms

Deeper reference for schema and workflows lives in the repo's Markdown (docs/architecture.md, docs/data-model.md, docs/workflows.md, docs/rules.md) — this site summarizes and links out where useful.