Conventions
Money, dates, layering, and the API response envelope used across the platform.
Conventions
These rules are enforced across the codebase — follow them in any new work. The three that break things hardest if ignored: money is integer paise (never float), layer imports only point inward, and every API response uses the success/error envelope.
Money — integer paise
All monetary values are stored and computed as integer paise (₹1 = 100 paise). Never use floating point for money.
// ₹1,499.00 is stored as:
const pricePaise = 149900Formatting to rupees happens only at display time, in Indian digit grouping:
formatINR(149900) // → "₹1,499.00"GST is 18% and inclusive — back-calculated from the displayed price:
const base = Math.round(inclusivePaise / 1.18)
const gst = inclusivePaise - baseDates & time
- Stored as
timestamptz(UTC); displayed in IST (UTC+5:30). - Display format is DD/MM/YYYY via
formatDateIN. - API payloads use ISO-8601 strings.
Layer rules (strict)
API routes are thin orchestrators: parse → Zod safeParse → call business
logic / queries → return JSON. No DB queries live in route handlers' own logic
beyond calling the query layer.
Prop
Type
API response envelope
Every JSON API responds with one of two shapes.
{
"success": true,
"data": { },
"meta": { "page": 1, "totalPages": 5, "totalCount": 92 }
}meta is present only on paginated list endpoints.
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"statusCode": 400,
"requestId": "req_a1b2c3d4e5f6",
"retryable": false,
"details": { }
}
}code— a stable machine-readable code from the error registry.requestId—req_+ nanoid, for log correlation.retryable— present when the caller may safely retry (e.g. transient 5xx).details— present on validation errors (field → message map).
Background-job routes (/api/jobs/*) are the exception: they return a minimal
{ processed } body and a non-2xx status on failure so QStash can retry. They
do not use the success/error envelope.
Error codes
Codes come from a central registry (@rgss/errors). Expand for the common ones — domain-specific codes for booking, membership, invoice, gems, offer, and branch rules are documented on each API page.
Related Pages
Data Model
Schema conventions, enums, and ID formats
Error Handling
The AppError class and handler pattern
API Reference
Per-endpoint codes and contracts
Was this page helpful?