GuidesDevelopers
Monorepo layout
Surplus is a single Bun workspace at the repository root. High-level layout (from docs/architecture.md):
| Path | Role |
|---|---|
apps/client/ | React 19 + TanStack Router + Vite; primary staff/driver UI |
apps/server/ | Hono + ORPC API; mounts generated OpenAPI and Scalar at /openapi |
apps/docs/ | This documentation site (Next.js + Fumadocs) |
packages/contracts/ | ORPC procedure contracts shared by client and server |
packages/postgres/ | Drizzle schema, migrations tooling, Neon client wiring |
packages/services/ | Domain services (classes) — business logic, DI-friendly |
packages/types/ | Zod schemas and inferred TS types |
packages/utils/ | Pure helpers and constants |
packages/redis/ | Redis / Upstash client factory |
packages/sharedDeps/ | Curated dependency re-exports |
crons/ | Scheduled workers (analytics cache, backups, …) |
scripts/ | One-off and migration utilities |
tests/ | Playwright end-to-end tests |
Naming: camelCase everywhere (tables, columns, files, CSS variables). IDs: UUID primary keys. Timestamps: Unix epoch integers in the data model.