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 = 149900

Formatting 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 - base

Dates & 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.

API response envelope

Every JSON API responds with one of two shapes.

Tab Title
Tab Title

{
  "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.

Last modified on June 29, 2026

Overview

Product

Features

Engineering

System design

Engineering standards

API reference

Application surface

Platform

Quality & security

Operations

Reference

Conventions

Conventions

Money — integer paise

Dates & time

Layer rules (strict)

API response envelope

Error codes

​Conventions

​Money — integer paise

​Dates & time

​Layer rules (strict)

​API response envelope

​Error codes

​Related Pages

Conventions

Money — integer paise

Dates & time

Layer rules (strict)

API response envelope

Error codes

Related Pages