Engineering
API & data guidelines
Naming, money, schemas, and client mapping conventions
API & data guidelines
Non-negotiables
| Rule | Detail |
|---|---|
| Money | Integer cents (Int64 / integer) — never floating currency |
| JSON | snake_case in API responses |
| Auth | Bearer JWT for shopper routes; document flows, not secrets |
| Validation | Server-side Zod (or equivalent) is source of truth |
Resource families (shopper-facing)
| Family | Typical concerns |
|---|---|
| Auth | register, login, refresh, Google, logout |
| Receipts | list, detail, line items, create/update where allowed |
| Warranties | CRUD tied to purchases / items |
| Offers | list + redemption |
| Preferences | shopper settings |
| Stream | SSE updates when enabled |
Exact paths live in the backend repo — prefer OpenAPI / route modules over duplicating every endpoint here.
Client mapping
iOS (and any web clients) should:
- Decode snake_case explicitly (
CodingKeys/ mappers). - Keep display formatting in the UI layer (
tabular-numsfor money). - Treat API errors as typed (
APIError) with user-safe messages.
Privacy-sensitive fields
| Field class | Handling |
|---|---|
| Identity bind (UCI / last4) | Validate server-side; minimize logging |
| Tokens | Keychain / httpOnly cookies — never localStorage for docs JWT (docs uses its own cookie) |
| Receipts | Least privilege; no PAN |
Versioning
Prefer /api/v1/... style versioning. Breaking changes require a new version or explicit migration notes in the backend README.