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.

Name	Type	Description
`Presentation`	`apps/web/src/app, components`	May import: business, db, types, errors. Must not import: nothing restricted.
`API (thin)`	`apps/web/src/app/api`	May import: business, db, types, errors. Must not import: UI components.
`Business logic`	`packages/business`	May import: types, errors. Must not import: db, framework, UI.
`Data access`	`packages/db`	May import: types. Must not import: business, framework, UI.
`Types`	`packages/types`	May import: nothing. Must not import: everything else.

API response envelope

Every JSON API responds with one of two shapes.

Success
Error

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

VALIDATION_ERROR — 400

Zod validation failed. The details field carries the field → message map.

UNAUTHENTICATED — 401

No valid session.

FORBIDDEN — 403

Authenticated but insufficient role.

NOT_FOUND — 404

Resource does not exist.

CONFLICT — 409

State conflict (e.g. double-book).

BUSINESS_RULE_VIOLATION — 409/422

A domain rule was violated.

RATE_LIMITED — 429

Too many requests.

SERVICE_UNAVAILABLE — 503

A dependency (e.g. Ably) is not configured.

INTERNAL_ERROR — 500

Unexpected error (retryable).

Data Model

Schema conventions, enums, and ID formats

Error Handling

The AppError class and handler pattern

API Reference

Per-endpoint codes and contracts

Getting started

System design

Standards

Application surface

Platform

Quality & security

Operations

Money — integer paise

Dates & time

Layer rules (strict)

API response envelope

Error codes

Data Model

Error Handling

API Reference

​Money — integer paise

​Dates & time

​Layer rules (strict)

​API response envelope

​Error codes

​Related Pages

Data Model

Error Handling

API Reference

Money — integer paise

Dates & time

Layer rules (strict)

API response envelope

Error codes

Related Pages