Engineering start here¶
SAGIO is a Bun/Turbo monorepo with four web/backend workspaces and one Android application.
| App | Stack | Purpose | Local port |
|---|---|---|---|
| API | Hono + Bun | REST API, payments, auth, integrations | 8787 |
| Merchant | React 19 + Vite | Analytics and merchant operations | 3000 |
| Wallet | React 19 + Vite + Capacitor | Consumer wallet | 3001 |
| Terminal | Android / Kotlin | Merchant POS | — |
| Landing | React 18 + Vite | Marketing site | 5173 |
Local development¶
Use bun for all JavaScript package interactions. Do not substitute npm, Yarn, or pnpm.
API pattern¶
New API behavior normally requires service logic, a controller, route registration, Zod validation, OpenAPI updates, and focused tests.
Loyalty accrual, refund compensation, and recovery invariants are documented in Loyalty ledger integrity.
Cross-cutting behaviour¶
The dashboard and the wallet never talk to each other; every shared feature is a pair of API endpoints over the same rows. Merchant ↔ consumer interop lists those seams, the order state machine, and two behaviours that read differently from how they work — order chat is closed while an order is unpaid, and "your order is ready" is delivered by email and push rather than the in-app notification feed.
The repository must be able to rebuild production's schema from nothing. Database schema of record covers how a database is built, what is deliberately allowed to differ, and how to verify a rebuild.
Deployment, the migration gate that fails closed, and what CI does and does not check are in Deploy pipeline.
Before a pull request¶
Run the affected tests, typecheck, lint, and build. For API changes, verify OpenAPI. For money or external side effects, verify authorization, tenancy, exact representation, idempotency, uncertain outcomes, and recovery.