# Money & shared types on the wire

## Money — IRR Rials, integer, no floats
- All monetary values are **IRR Rials as integers** (`BIGINT` server-side). There are **no floats** on
  the money path anywhere — not in the DB, not in the API, not in the client.
- Because IRR amounts exceed JS's safe integer range in some aggregates and to avoid float coercion,
  represent money on the wire as a **string of digits** (e.g. `"23300000"`) unless the published
  `swagger.json` shows otherwise; the client parses with `BigInt`/integer-safe helpers and formats for
  display. **Toman is display-only** and is converted to/from Rials **only** inside a provider adapter
  at its boundary — never in shared contracts or the client's own math.
- The three booking amounts always satisfy `gross_price_irr = balinyaar_commission_irr + nurse_payout_amount`.

## Dates & times
- Timestamps are **UTC ISO-8601** (`DATETIME2(7)` server-side). Persian-calendar (Shamsi) display is a
  **client** concern. The exception is bank-closure scheduling, which the server resolves via the
  holiday calendar — the client never computes payout dates.
- `day_of_week` for availability uses the **Shamsi week (0 = Saturday … 6 = Friday)**, not ISO Monday-start.

## Enums (string-valued, stable codes)
Enums cross the wire as their stable string code (e.g. `male`/`female`/`any`, `per_hour`/`per_session`/
`per_half_day`/`per_day`/`per_24h`, booking/verification/payment statuses, `refund_channel` =
`psp_card`/`bnpl_revert`/`manual`). Each domain contract doc lists the exact set it uses. The frontend
mirrors them as string-literal union types and **never** hardcodes a display label off the code — labels
are i18n keys.

## Identifiers
- Entity IDs are integers/`BIGINT` (serialized per the published schema). Human-facing references
  (`reference_code` on tickets, `invoice_number`) are strings shown to users — treat as opaque.

## PII & sensitive fields
- Encrypted-at-rest fields (phone, national_id, IBAN, addresses, clinical notes) are returned **only**
  to authorized callers and often **masked** (e.g. last 4 of an IBAN). Contracts must state when a field
  is masked vs. full, and the two-stage clinical-disclosure rule (full care instructions only after a
  booking is confirmed, to the assigned nurse + admin) applies to the relevant payloads.

## Gender (load-bearing)
- `gender` (`male`/`female`) drives **same-gender caregiver matching** — a near-hard requirement. It is
  present on users/patients and on the booking request as `required_caregiver_gender`
  (`male`/`female`/`any`). Never default or drop it silently.
