# 1. Actors & Onboarding

← Business Requirements

## (a) Business requirements #

- Three actor types: customer (the family member / payer), nurse (the independent caregiver / seller), and admin (Balinyaar back-office staff: support, finance, moderation, super-admin).
- Phone number is the primary login credential. Authentication is phone-OTP (one-time code by SMS). Email is optional/secondary (required only for admin accounts).
- The patient (care recipient) is a first-class entity distinct from the customer, because the payer (an adult child, a spouse) is frequently not the patient (an elderly parent, a newborn, a post-surgical adult). A customer may register multiple patients.
- KYC timing is role- and risk-staged, not up-front-for-everyone:
  - A customer can register and browse with only a verified phone (OTP). National-ID KYC for customers is anti-fraud only and is deferred at launch.
  - A nurse must complete the full verification pipeline (Section 2) before any of their service variants become bookable. `national_id` is populated only after the identity step passes.
  - An admin is provisioned internally with RBAC roles.
- Each successful login creates a refresh-token session that can be revoked (logout, stolen-token detection).
- As-built decisions (backend-phase-2): each refresh rotates the session (old revoked, new pair issued); a refresh token presented against an already-revoked session is treated as stolen-token reuse → all of the user's sessions are revoked and the call returns 401. Logout rotates the security stamp, so every outstanding access token dies (other devices recover by refreshing). OTP request/verify never reveal whether a phone already has an account; one OTP per phone per resend window (`auth_otp_resend_seconds`), and after `auth_otp_max_attempts` wrong codes verification refuses until a fresh OTP. `customer`/`nurse` are the only self-selectable roles (a user may hold both; grants audited via `granted_by`/`granted_at`); any admin sub-role self-assign attempt returns 403 — admin provisioning is internal-only.
- As-built decisions (frontend-phase-2 — onboarding UI): the "who is care for?" onboarding step captures the patient's relation to the payer as a stable enum — `parent` | `spouse` | `child` | `self` (the `self` case still creates a distinct patient row; the customer is never collapsed into the patient). It also collects optional condition chips (`elderly`/`post_surgery`/`diabetes`/`mobility`/`dementia`). Neither `relation` nor `conditions` exists on the `patients` table yet — they are carried client-side and requested for the backend as REQ-005 (frontend `requests/for-backend.md`); confirm/adjust the enum values when persisting.

## (b) Iran-specific considerations #

- Phone-OTP is the dominant Iranian login norm and is also the anchor for Shahkar SIM↔national-ID binding (Section 2).
- Storing `national_id` only post-KYC matches the reality that identity is verified through gated vendor APIs, not collected casually at signup.
- Cultural reality: the booking flow must let a family member act on behalf of a patient who cannot self-advocate (infant, dementia, post-anesthesia). The customer/patient split is essential, not cosmetic.

## (c) MVP vs DEFERRED #

- MVP: phone-OTP login; customer/nurse/admin roles; customer→patient (1:N); session management; admin RBAC; nurse onboarding gated on verification.
- DEFERRED: customer national-ID KYC (`customer_profiles.national_id_verified_at` exists but is optional/unused at launch); push notifications; social login; nursing-company (organization) self-onboarding.

## (d) Supporting database entities #

`users`, `user_sessions`, `roles`, `user_roles`, `nurse_profiles`, `customer_profiles`, `patients`, `customer_addresses`.

> Related: Data model — Identity & Access.

↑ Back to top