baya-monorepo/product/database-model.md

Balinyaar — Database Model

Platform Summary

Balinyaar is a hybrid home nursing marketplace in Iran. Independent nurses (and in future, nursing company employees) register, list configurable services with their own pricing, and undergo a multi-step verification pipeline. Families search, pick a nurse and service variant, submit a booking request, and pay through the platform after the nurse accepts. The platform holds payment in escrow and releases weekly payouts to nurses after service completion is confirmed via EVV. All post-booking communication runs through a ticket system inspectable by admins.

---

Design Principles

1. Monetary values stored as BIGINT in Iranian Rials (IRR). Toman conversion is a display concern only.
2. PII fields (national ID, IBAN, phone, addresses, clinical data) are marked (encrypted) — column-level or application-level encryption; actual mechanism is implementation-specific.
3. Soft deletes on users and nurse_profiles via deleted_at. Audit and payment records are never deleted.
4. Audit trail is append-only. All state transitions on bookings, payments, verifications, and reviews produce a row in audit_logs.
5. Enum-like fields use NVARCHAR(50) with application-enforced constraints. Admin-managed catalog tables (ServiceCategory, VerificationStepType) are rows, not enums — they can be extended without schema changes.
6. Platform fee is captured at booking time and never derived from current config, so historical records remain accurate after fee changes.
7. Snapshot fields (e.g., variant_snapshot_json, address_snapshot_json on bookings) protect historical accuracy from future edits to linked records.
8. Multi-language — all admin-managed catalog tables carry name_fa / name_en pairs.
9. All timestamps are DATETIME2(7) in UTC. Persian calendar display is a UI concern.
10. String fields use NVARCHAR throughout to support Persian/Arabic characters.

---

Entity Catalog

---

Domain 1 — Identity & Access

---

users

The single identity record for every human actor on the platform: nurses, customers, and admin staff. Role determines which profile sub-table is populated. Phone number is the primary login credential (OTP); email is secondary. National ID is populated only after the KYC step completes.

Field	Type	Notes
id	BIGINT PK IDENTITY
email	NVARCHAR(255) UNIQUE NULL	(encrypted) — optional at registration; required for admin accounts
phone	NVARCHAR(20) UNIQUE NOT NULL	(encrypted) — used for OTP login and Shahkar matching
national_id	NVARCHAR(20) UNIQUE NULL	(encrypted) — populated after KYC identity step passes
national_id_verified_at	DATETIME2 NULL
first_name	NVARCHAR(100) NOT NULL
last_name	NVARCHAR(100) NOT NULL
avatar_url	NVARCHAR(512) NULL	Object-storage URL
role	NVARCHAR(20) NOT NULL	nurse / customer / admin
is_active	BIT NOT NULL DEFAULT 1	False = account suspended (not deleted)
email_verified_at	DATETIME2 NULL
phone_verified_at	DATETIME2 NULL	Set on first successful OTP
last_login_at	DATETIME2 NULL
last_login_ip	NVARCHAR(45) NULL	IPv4 or IPv6
preferred_language	NVARCHAR(5) NOT NULL DEFAULT 'fa'	fa / en
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL
deleted_at	DATETIME2 NULL	Soft delete — NULL = active

---

user_sessions

Auth session records for refresh token management. Each login creates a session. Logging out or detecting a stolen token invalidates the session.

Field	Type	Notes
id	BIGINT PK IDENTITY
user_id	BIGINT FK → users NOT NULL
refresh_token_hash	NVARCHAR(64) NOT NULL	SHA-256 of the issued refresh token
device_info	NVARCHAR(500) NULL	User-agent string
ip_address	NVARCHAR(45) NULL
is_revoked	BIT NOT NULL DEFAULT 0
revoked_at	DATETIME2 NULL
expires_at	DATETIME2 NOT NULL
created_at	DATETIME2 NOT NULL

---

roles

RBAC roles for admin staff. Nurses and customers do not use this table — their permissions are determined by the users.role field.

Field	Type	Notes
id	BIGINT PK IDENTITY
name	NVARCHAR(50) UNIQUE NOT NULL	super_admin / admin / support / finance / moderator
description	NVARCHAR(500) NULL
created_at	DATETIME2 NOT NULL

---

user_roles

Assignment of admin roles to admin users. A user may hold multiple roles. Revoked roles retain history.

Field	Type	Notes
id	BIGINT PK IDENTITY
user_id	BIGINT FK → users NOT NULL	Must be a user with role=admin
role_id	BIGINT FK → roles NOT NULL
granted_by_user_id	BIGINT FK → users NULL
granted_at	DATETIME2 NOT NULL
revoked_at	DATETIME2 NULL	NULL = still active

---

nurse_profiles

Extended data for users with role = nurse. Separated from users to avoid a bloated base table. Denormalized aggregates (average_rating, total_completed_bookings) are maintained on every review publication and booking completion — never calculated on-the-fly in search queries.

Field	Type	Notes
id	BIGINT PK IDENTITY
user_id	BIGINT FK → users UNIQUE NOT NULL	1:1
bio	NVARCHAR(2000) NULL	Displayed on nurse profile page
years_of_experience	SMALLINT NULL
education_level	NVARCHAR(50) NULL	bachelor / master / phd / associate
education_field	NVARCHAR(200) NULL	e.g., "پرستاری — دانشگاه تهران"
specializations_json	NVARCHAR(MAX) NULL	JSON array of specialization tag strings
is_verified	BIT NOT NULL DEFAULT 0	True only when all required verification steps pass
verification_status	NVARCHAR(30) NOT NULL DEFAULT 'not_started'	not_started / pending / in_review / approved / rejected / suspended
is_accepting_bookings	BIT NOT NULL DEFAULT 0	Nurse can toggle without losing verified status
average_rating	DECIMAL(3,2) NULL	Denormalized; recalculated on each published review
total_reviews	INT NOT NULL DEFAULT 0	Denormalized count of published reviews
total_completed_bookings	INT NOT NULL DEFAULT 0	Denormalized
response_rate	DECIMAL(5,2) NULL	% of booking requests responded to before expiry
avg_response_time_hours	DECIMAL(5,2) NULL	Rolling average for display on profile
profile_completion_score	SMALLINT NOT NULL DEFAULT 0	0–100, shown in backoffice to surface incomplete profiles
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL
deleted_at	DATETIME2 NULL	Soft delete

---

customer_profiles

Extended profile for users with role = customer. Intentionally lightweight — most customer data lives in their bookings and patients.

Field	Type	Notes
id	BIGINT PK IDENTITY
user_id	BIGINT FK → users UNIQUE NOT NULL	1:1
national_id_verified_at	DATETIME2 NULL	Anti-fraud KYC for high-value customers (optional at launch)
default_emergency_contact_name	NVARCHAR(200) NULL	(encrypted) — overridable per booking
default_emergency_contact_phone	NVARCHAR(20) NULL	(encrypted)
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

patients

The person receiving care. Fully separated from the customer because the payer (adult child, spouse) is often not the patient (elderly parent, newborn, post-surgical adult). A customer may register multiple patients. Patient medical data is encrypted at rest.

Field	Type	Notes
id	BIGINT PK IDENTITY
customer_id	BIGINT FK → customer_profiles NOT NULL	Record owner
display_name	NVARCHAR(200) NOT NULL	e.g., "پدر", "مادر بزرگ", "نوزاد"
first_name	NVARCHAR(100) NULL
last_name	NVARCHAR(100) NULL
birth_date	DATE NULL
gender	NVARCHAR(10) NULL	male / female
blood_type	NVARCHAR(5) NULL	A+, A-, B+, B-, O+, O-, AB+, AB-
initial_medical_notes	NVARCHAR(MAX) NULL	(encrypted) — baseline context set by the family
is_active	BIT NOT NULL DEFAULT 1	Soft-archivable
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

customer_addresses

Saved service locations for a customer. Used in booking requests to tell the nurse where to go. The full address is encrypted. Coordinates are stored for EVV distance matching at check-in.

Field	Type	Notes
id	BIGINT PK IDENTITY
customer_id	BIGINT FK → customer_profiles NOT NULL
title	NVARCHAR(100) NOT NULL	e.g., "خانه", "خانه‌ی پدری"
address_line1	NVARCHAR(500) NOT NULL	(encrypted)
address_line2	NVARCHAR(500) NULL	(encrypted)
city_id	BIGINT FK → cities NOT NULL
district_id	BIGINT FK → districts NULL
postal_code	NVARCHAR(20) NULL
latitude	DECIMAL(10,7) NULL	For EVV match tolerance check
longitude	DECIMAL(10,7) NULL
access_notes	NVARCHAR(500) NULL	(encrypted) — door code, building instructions, unit number
is_primary	BIT NOT NULL DEFAULT 0	One primary per customer
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

nurse_bank_accounts

Banking details for nurse payout. IBAN (Sheba) is encrypted. Multiple accounts allowed; exactly one marked primary receives weekly payouts. Verified by admin before first payout.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_id	BIGINT FK → nurse_profiles NOT NULL
bank_name	NVARCHAR(100) NOT NULL
account_holder_name	NVARCHAR(200) NOT NULL	(encrypted)
iban	NVARCHAR(34) NOT NULL	(encrypted) — IR + 24 digits (Sheba)
is_primary	BIT NOT NULL DEFAULT 0
is_verified	BIT NOT NULL DEFAULT 0	Admin confirmed the account exists and matches nurse identity
verified_by_admin_id	BIGINT FK → users NULL
verified_at	DATETIME2 NULL
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

Domain 2 — Geographic Data

---

provinces

Field	Type	Notes
id	BIGINT PK IDENTITY
name_fa	NVARCHAR(100) NOT NULL
name_en	NVARCHAR(100) NOT NULL
is_active	BIT NOT NULL DEFAULT 1

---

cities

Field	Type	Notes
id	BIGINT PK IDENTITY
province_id	BIGINT FK → provinces NOT NULL
name_fa	NVARCHAR(100) NOT NULL
name_en	NVARCHAR(100) NOT NULL
is_active	BIT NOT NULL DEFAULT 1
sort_order	SMALLINT NOT NULL DEFAULT 0	For ordered dropdowns

---

districts

Sub-city units (محله / منطقه). Granularity varies: in Tehran these map to the 22 official municipal districts; in smaller cities they may be major neighborhoods. Districts are optional — nurses can cover a whole city without specifying districts.

Field	Type	Notes
id	BIGINT PK IDENTITY
city_id	BIGINT FK → cities NOT NULL
name_fa	NVARCHAR(200) NOT NULL
name_en	NVARCHAR(200) NULL
is_active	BIT NOT NULL DEFAULT 1

---

nurse_service_areas

Defines where a nurse is willing to travel. A nurse can cover multiple cities and optionally specific districts within each. A row with district_id = NULL means the nurse covers the entire city. This table drives the geographic filter in nurse search.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_id	BIGINT FK → nurse_profiles NOT NULL
city_id	BIGINT FK → cities NOT NULL
district_id	BIGINT FK → districts NULL	NULL = entire city
created_at	DATETIME2 NOT NULL

Index: (nurse_id, city_id, district_id) UNIQUE — prevents duplicate area declarations.

---

Domain 3 — Nurse Services & Pricing

The service model has three admin-defined layers (category → option groups → option values) and two nurse-defined layers (variant → variant options). This design lets admins add new configurable dimensions (e.g., "shift length", "number of patients") without schema changes, and lets each nurse price every combination they choose to offer independently.

---

service_categories

Admin-managed top-level care types. These are the primary search dimension for customers.

Examples: مراقبت از سالمند (Elderly Care), مراقبت پس از جراحی (Post-Surgery Recovery), مراقبت از نوزاد (Infant/Newborn Care), مدیریت بیماری مزمن (Chronic Illness Management), همراهی و کمک روزمره (Companionship/Daily Living — future tier).

Field	Type	Notes
id	BIGINT PK IDENTITY
name_fa	NVARCHAR(200) NOT NULL
name_en	NVARCHAR(200) NOT NULL
description_fa	NVARCHAR(1000) NULL	Shown to customers in search
icon_url	NVARCHAR(512) NULL
is_active	BIT NOT NULL DEFAULT 1
sort_order	SMALLINT NOT NULL DEFAULT 0
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

service_option_groups

Admin-defined configurable dimensions per category. Each group represents one axis the nurse can configure. A NULL service_category_id means the option group applies across all categories (e.g., shift type).

Field	Type	Notes
id	BIGINT PK IDENTITY
service_category_id	BIGINT FK → service_categories NULL	NULL = cross-category
name_fa	NVARCHAR(200) NOT NULL	e.g., "تعداد بیمار", "نوع شیفت"
name_en	NVARCHAR(200) NOT NULL
description_fa	NVARCHAR(500) NULL	Instructions shown to nurse when setting up a listing
is_required	BIT NOT NULL DEFAULT 1	If true, nurse must select a value from this group per variant
sort_order	SMALLINT NOT NULL DEFAULT 0
is_active	BIT NOT NULL DEFAULT 1

---

service_option_values

Concrete choices within an option group. The nurse selects from these when creating a variant.

Field	Type	Notes
id	BIGINT PK IDENTITY
option_group_id	BIGINT FK → service_option_groups NOT NULL
label_fa	NVARCHAR(200) NOT NULL	e.g., "۱ نفر", "۲ نفر", "شبانه‌روزی"
label_en	NVARCHAR(200) NULL
sort_order	SMALLINT NOT NULL DEFAULT 0
is_active	BIT NOT NULL DEFAULT 1

---

nurse_service_variants

The atomic bookable unit on the platform. Each variant is a specific offering by a nurse: a service category with a particular combination of option values, at a specific price. These rows are indexed for search and displayed on the nurse's public profile. A nurse may have many variants per category (one per combination they choose to offer).

Example: Nurse A → Elderly Care → 2 patients → Full-day shift → 3,200,000 IRR per day

The display_name is auto-generated from the selected option labels but can be customized by the nurse. The price_unit determines how the price is shown (per hour, per session, per day, etc.). For hourly variants, estimated_duration_hours gives the minimum or typical commitment so customers can estimate total cost.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_id	BIGINT FK → nurse_profiles NOT NULL
service_category_id	BIGINT FK → service_categories NOT NULL
display_name	NVARCHAR(300) NOT NULL	Shown on profile and search results
price	BIGINT NOT NULL	In IRR. Never null — every variant must have a price.
price_unit	NVARCHAR(20) NOT NULL	per_hour / per_session / per_half_day / per_day / per_24h
estimated_duration_hours	DECIMAL(5,2) NULL	For hourly variants, helps customer estimate total cost
description	NVARCHAR(1000) NULL	Nurse's optional notes about this specific variant
is_active	BIT NOT NULL DEFAULT 1	Nurse can deactivate without deleting; deactivated variants cannot be booked
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

nurse_service_variant_options

Records which option values apply to a variant. Together, these rows define the full configuration of a variant. A variant covering two option groups (e.g., patient count + shift type) will have two rows here.

Field	Type	Notes
id	BIGINT PK IDENTITY
variant_id	BIGINT FK → nurse_service_variants NOT NULL
option_group_id	BIGINT FK → service_option_groups NOT NULL
option_value_id	BIGINT FK → service_option_values NOT NULL

Constraint: (variant_id, option_group_id) UNIQUE — one value per dimension per variant.

---

nurse_availability_slots

Recurring weekly availability windows declared by the nurse. These inform the customer's search (e.g., "available Saturdays 8am–6pm") but are soft constraints — the nurse still accepts or rejects each individual booking request. They do not block booking requests for times outside these slots; they are guidance only.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_id	BIGINT FK → nurse_profiles NOT NULL
day_of_week	TINYINT NOT NULL	0=Saturday, 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday (Shamsi week)
start_time	TIME NOT NULL
end_time	TIME NOT NULL
is_active	BIT NOT NULL DEFAULT 1
created_at	DATETIME2 NOT NULL

---

nurse_availability_exceptions

Date-specific overrides to the recurring weekly schedule. Used for vacations, public holidays the nurse wants to block, or one-time extra availability on a normally-off day.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_id	BIGINT FK → nurse_profiles NOT NULL
exception_date	DATE NOT NULL
is_available	BIT NOT NULL	False = day blocked; True = day open (even if absent from weekly slots)
reason	NVARCHAR(200) NULL	e.g., "تعطیلات عید نوروز"

Constraint: (nurse_id, exception_date) UNIQUE.

---

Domain 4 — Nurse Verification

The verification pipeline is a sequence of steps. Each step type is admin-configurable (new steps can be added as rows, no code change). Steps can be automated (KYC API call) or manual (admin reviews uploaded document). The overall nurse_verifications record aggregates the step outcomes into a single status.

---

nurse_verifications

Master verification record for a nurse — one row per nurse, created when the nurse first submits for verification. Every status transition here is captured in audit_logs. When all required verification_steps reach passed, this record's status moves to approved and nurse_profiles.is_verified flips to true.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_id	BIGINT FK → nurse_profiles UNIQUE NOT NULL	1:1
status	NVARCHAR(30) NOT NULL DEFAULT 'not_started'	not_started / pending / in_review / approved / rejected / suspended
submitted_at	DATETIME2 NULL	First submission timestamp
approved_at	DATETIME2 NULL
rejected_at	DATETIME2 NULL
suspended_at	DATETIME2 NULL
rejection_reason	NVARCHAR(1000) NULL	Shown to the nurse in the app
reviewed_by_admin_id	BIGINT FK → users NULL	Last admin to act on this record
internal_notes	NVARCHAR(2000) NULL	Admin-only; not shown to nurse
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

verification_step_types

Admin-configurable catalog of what steps exist in the pipeline. Adding a new step type (e.g., "professional liability insurance") requires only inserting a row here — no code change needed. The code is a stable machine key referenced by application logic for automated steps.

Field	Type	Notes
id	BIGINT PK IDENTITY
code	NVARCHAR(100) UNIQUE NOT NULL	e.g., identity_kyc, moh_license, ino_membership, criminal_record, bank_account_verification
name_fa	NVARCHAR(200) NOT NULL	Shown in backoffice
name_en	NVARCHAR(200) NOT NULL
description_fa	NVARCHAR(500) NULL	Instructions shown to nurse for this step
is_required	BIT NOT NULL DEFAULT 1	Non-required steps are advisory; they don't block approval
is_automated	BIT NOT NULL DEFAULT 0	If true, platform calls an external API for this step
automation_provider	NVARCHAR(100) NULL	e.g., finnotech, u_id, jibbit, manual
requires_document_upload	BIT NOT NULL DEFAULT 0	If true, nurse must upload at least one document
sort_order	SMALLINT NOT NULL DEFAULT 0	Processing order shown to nurse
is_active	BIT NOT NULL DEFAULT 1
created_at	DATETIME2 NOT NULL

---

verification_steps

One row per step per nurse. Tracks individual step status as the nurse moves through the pipeline. The external_response_json stores the raw API response for automated steps — critical for dispute and compliance audit. For manual steps, reviewed_by_admin_id and review_notes capture who reviewed and what they decided.

expires_at supports time-limited steps: the criminal record certificate (گواهی عدم سوء پیشینه) is valid for a limited period; when it expires, the step reverts to pending and a support alert is raised.

Field	Type	Notes
id	BIGINT PK IDENTITY
nurse_verification_id	BIGINT FK → nurse_verifications NOT NULL
step_type_id	BIGINT FK → verification_step_types NOT NULL
status	NVARCHAR(30) NOT NULL DEFAULT 'pending'	pending / submitted / processing / passed / failed / expired
is_automated	BIT NOT NULL	Snapshot from step_type at creation; stored so historical records survive step_type edits
external_provider	NVARCHAR(100) NULL	KYC vendor that processed this step
external_reference_id	NVARCHAR(200) NULL	Provider's session/transaction ID
external_response_json	NVARCHAR(MAX) NULL	Full API response for audit
reviewed_by_admin_id	BIGINT FK → users NULL	NULL for automated steps
review_notes	NVARCHAR(1000) NULL	Admin rationale for pass/fail decision
submitted_at	DATETIME2 NULL	When nurse submitted this step
completed_at	DATETIME2 NULL	When step reached terminal state
expires_at	DATETIME2 NULL	For time-limited steps (e.g., criminal record cert)
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

Constraint: (nurse_verification_id, step_type_id) UNIQUE.

---

verification_documents

Documents uploaded as evidence for a verification step. File contents live in object storage (S3-compatible). This table holds the metadata, reference key, and integrity hash. Access to the actual file must be through signed/time-limited URLs — never a direct public URL.

Field	Type	Notes
id	BIGINT PK IDENTITY
verification_step_id	BIGINT FK → verification_steps NOT NULL
document_type	NVARCHAR(50) NOT NULL	national_id_front / national_id_back / moh_license / ino_certificate / criminal_record / selfie / liveness_video
storage_key	NVARCHAR(512) NOT NULL	Object-storage path — access-controlled, no public URL
file_hash	NVARCHAR(64) NOT NULL	SHA-256 of raw file bytes for integrity verification
file_size_bytes	INT NULL
mime_type	NVARCHAR(100) NULL
is_valid	BIT NULL	NULL = pending review; True/False after admin assessment
uploaded_at	DATETIME2 NOT NULL

---

Domain 5 — Booking & Scheduling

The booking lifecycle has two distinct phases: the request phase (before payment) and the booking phase (after payment). Separating them into two tables keeps each table focused and makes lifecycle transitions explicit. A booking only exists if payment succeeded.

Request lifecycle: pending_nurse_response → nurse accepts → accepted_awaiting_payment → payment received → converted (Booking created) pending_nurse_response → nurse rejects → rejected_by_nurse pending_nurse_response → deadline passes → expired_no_response accepted_awaiting_payment → 30-min payment window passes → payment_deadline_expired Any pre-payment state → customer cancels → cancelled_by_customer

Booking lifecycle: pending_payment → payment captured → confirmed confirmed → nurse checks in → in_progress in_progress → nurse checks out → completed confirmed → cancelled before service → cancelled completed → disputed → disputed disputed → resolved → closed

---

booking_requests

A customer's intent to book a nurse for a specific service, date, and time slot. Created when the customer submits a request. Multiple requests can exist for the same customer/nurse pair (e.g., first one rejected, a new one submitted later). No money is involved at this stage.

The nurse_response_deadline_at is computed from platform_configs.nurse_response_deadline_hours at creation time and stored so it is immune to config changes. Similarly, payment_deadline_at is set when the nurse accepts and reflects the 30-minute window from that moment.

Field	Type	Notes
id	BIGINT PK IDENTITY
customer_id	BIGINT FK → customer_profiles NOT NULL
nurse_id	BIGINT FK → nurse_profiles NOT NULL
patient_id	BIGINT FK → patients NOT NULL
variant_id	BIGINT FK → nurse_service_variants NOT NULL	The specific service + options the customer wants
customer_address_id	BIGINT FK → customer_addresses NOT NULL
requested_date	DATE NOT NULL
requested_time_start	TIME NOT NULL
requested_time_end	TIME NOT NULL
customer_notes	NVARCHAR(1000) NULL	Additional context the customer sends with the request (visible to nurse)
status	NVARCHAR(50) NOT NULL DEFAULT 'pending_nurse_response'	See lifecycle above
nurse_response_deadline_at	DATETIME2 NOT NULL	After this, job transitions to expired_no_response automatically
payment_deadline_at	DATETIME2 NULL	Set when nurse accepts; 30-minute countdown starts
nurse_rejection_reason	NVARCHAR(500) NULL	Optional message from nurse on rejection
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

bookings

Confirmed service engagement. Created when nurse accepts AND payment is successfully captured within the deadline. This is the source of truth for the actual service event. The variant_snapshot_json and address_snapshot_json freeze the service details and address at booking time, protecting historical records from future edits to those referenced entities.

The fee fields capture the exact split at the moment of booking: gross_amount (what the customer pays), platform_fee_amount (platform's share), and nurse_payout_amount (what the nurse will receive). The platform_fee_rate is stored so auditors can reconstruct how the split was calculated even after the fee schedule changes.

Field	Type	Notes
id	BIGINT PK IDENTITY
booking_request_id	BIGINT FK → booking_requests UNIQUE NOT NULL	1:1 — the request that created this booking
customer_id	BIGINT FK → customer_profiles NOT NULL	Denormalized for query performance
nurse_id	BIGINT FK → nurse_profiles NOT NULL
patient_id	BIGINT FK → patients NOT NULL
variant_id	BIGINT FK → nurse_service_variants NOT NULL	Reference — see snapshot below for historical accuracy
variant_snapshot_json	NVARCHAR(MAX) NOT NULL	Full JSON of variant + option labels at booking time
customer_address_id	BIGINT FK → customer_addresses NOT NULL
address_snapshot_json	NVARCHAR(MAX) NOT NULL	(encrypted) — full address at booking time
scheduled_date	DATE NOT NULL
scheduled_time_start	TIME NOT NULL
scheduled_time_end	TIME NOT NULL
gross_amount	BIGINT NOT NULL	Total charged to customer (IRR)
platform_fee_amount	BIGINT NOT NULL	Platform's cut
platform_fee_rate	DECIMAL(5,4) NOT NULL	e.g., 0.1500 = 15% — captured at booking time
nurse_payout_amount	BIGINT NOT NULL	gross_amount - platform_fee_amount
status	NVARCHAR(30) NOT NULL DEFAULT 'pending_payment'	See lifecycle above
confirmed_at	DATETIME2 NULL	When payment was captured
cancelled_at	DATETIME2 NULL
cancellation_reason	NVARCHAR(500) NULL
cancelled_by	NVARCHAR(20) NULL	customer / nurse / admin / system
completed_at	DATETIME2 NULL	When booking status moved to completed
payout_released	BIT NOT NULL DEFAULT 0	True when this booking is included in a processed payout batch
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

booking_care_instructions

Clinical and logistical context provided by the family at booking time. Separated from bookings to keep the financial/scheduling table clean and because this data has stricter access controls (encrypted, visible only to the assigned nurse and admin). The nurse reads this before the visit.

Field	Type	Notes
id	BIGINT PK IDENTITY
booking_id	BIGINT FK → bookings UNIQUE NOT NULL	1:1
current_conditions	NVARCHAR(MAX) NULL	(encrypted) — active diagnoses
current_medications	NVARCHAR(MAX) NULL	(encrypted) — drug names, doses, schedule
allergies	NVARCHAR(1000) NULL	(encrypted)
special_instructions	NVARCHAR(2000) NULL	(encrypted) — care protocol, family preferences
emergency_contact_name	NVARCHAR(200) NULL	(encrypted)
emergency_contact_phone	NVARCHAR(20) NULL	(encrypted)
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

visit_verifications

Electronic Visit Verification (EVV). The nurse clocks in and out via the app; GPS coordinates and timestamps are recorded. This is the authoritative record of whether a visit occurred and for how long. It is required for payout release. If a nurse does not check in by a configurable threshold after the scheduled start time, a support_alerts record is created and the family is notified.

check_in_address_match is a computed boolean: did the nurse's GPS at check-in fall within an acceptable radius of the booking address? This flag is advisory for admin — a mismatch triggers a review but does not automatically cancel the booking.

Field	Type	Notes
id	BIGINT PK IDENTITY
booking_id	BIGINT FK → bookings UNIQUE NOT NULL	1:1
check_in_at	DATETIME2 NULL
check_in_latitude	DECIMAL(10,7) NULL
check_in_longitude	DECIMAL(10,7) NULL
check_in_address_match	BIT NULL	Did GPS match booking address within tolerance?
check_out_at	DATETIME2 NULL
check_out_latitude	DECIMAL(10,7) NULL
check_out_longitude	DECIMAL(10,7) NULL
actual_duration_minutes	INT NULL	Computed: check_out_at - check_in_at
status	NVARCHAR(20) NOT NULL DEFAULT 'pending'	pending / checked_in / completed / missed / disputed
nurse_checkout_notes	NVARCHAR(500) NULL	Optional note from nurse at checkout
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

Domain 6 — Payments

---

payment_gateways

Configuration for each PSP connected to the platform. Credentials are encrypted. Multiple gateways may be active simultaneously (e.g., standard IPG for direct payment, a BNPL gateway for installments, a failover gateway). The type field determines which payment flow applies.

Field	Type	Notes
id	BIGINT PK IDENTITY
code	NVARCHAR(50) UNIQUE NOT NULL	e.g., zarinpal, idpay, payping, bnpl_hamrah, bnpl_toranj
name	NVARCHAR(100) NOT NULL	Display name
type	NVARCHAR(30) NOT NULL	standard / bnpl
is_active	BIT NOT NULL DEFAULT 1
config_json	NVARCHAR(MAX) NULL	(encrypted) — merchant ID, API keys, webhook secret, callback URLs
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

payment_transactions

Records every payment attempt against a booking. A booking may have multiple rows here (failed first attempt, successful retry). The row where status = 'succeeded' is the one that triggers booking confirmation. The gateway_response_json stores the full PSP response — essential for dispute, chargebacks, and Shaparak reconciliation.

ip_address and user_agent at payment time are retained for fraud detection and dispute evidence.

Field	Type	Notes
id	BIGINT PK IDENTITY
booking_id	BIGINT FK → bookings NOT NULL
customer_id	BIGINT FK → customer_profiles NOT NULL
gateway_id	BIGINT FK → payment_gateways NOT NULL
amount	BIGINT NOT NULL	Amount charged in this transaction (IRR)
currency	NVARCHAR(5) NOT NULL DEFAULT 'IRR'
status	NVARCHAR(30) NOT NULL DEFAULT 'initiated'	initiated / pending / succeeded / failed / cancelled / refunded / partially_refunded
gateway_transaction_id	NVARCHAR(200) NULL	PSP's transaction identifier
gateway_reference_code	NVARCHAR(200) NULL	Shaparak reference code — the definitive payment proof
gateway_response_code	NVARCHAR(50) NULL	PSP result code
gateway_response_json	NVARCHAR(MAX) NULL	Full PSP response
is_installment	BIT NOT NULL DEFAULT 0	True if funded via a BNPL plan
initiated_at	DATETIME2 NOT NULL	When the payment flow was started
paid_at	DATETIME2 NULL	When PSP confirmed success
failed_at	DATETIME2 NULL
failure_reason	NVARCHAR(500) NULL	Human-readable from PSP
ip_address	NVARCHAR(45) NULL	Customer's IP at payment time
user_agent	NVARCHAR(500) NULL
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

refunds

Refund requests and their resolution. Refunds are always admin-initiated — there is no customer self-service refund. They are typically triggered by a family request communicated through a support ticket. Default refund is 100% of the payment; admin may set a partial amount (e.g., cancellation fee deducted).

The ticket_id links to the support conversation where the refund was discussed, providing full context for dispute evidence.

Field	Type	Notes
id	BIGINT PK IDENTITY
payment_transaction_id	BIGINT FK → payment_transactions NOT NULL	The original successful payment being refunded
booking_id	BIGINT FK → bookings NOT NULL
requested_by_customer_id	BIGINT FK → customer_profiles NOT NULL
ticket_id	BIGINT FK → tickets NULL	Support conversation that led to this refund
amount	BIGINT NOT NULL	Refund amount (IRR). Default = full gross_amount.
refund_percentage	DECIMAL(5,2) NOT NULL	For audit display (e.g., 100.00, 50.00)
reason_category	NVARCHAR(50) NOT NULL	nurse_no_show / quality_complaint / scheduling_error / customer_cancellation / platform_error / other
reason_notes	NVARCHAR(1000) NULL
status	NVARCHAR(30) NOT NULL DEFAULT 'pending'	pending / approved / rejected / processing / completed / failed
approved_by_admin_id	BIGINT FK → users NULL
approved_at	DATETIME2 NULL
rejected_by_admin_id	BIGINT FK → users NULL
rejected_at	DATETIME2 NULL
rejection_reason	NVARCHAR(500) NULL	Communicated to customer
gateway_refund_reference	NVARCHAR(200) NULL	PSP's refund transaction ID
processed_at	DATETIME2 NULL	When PSP confirmed refund success
admin_notes	NVARCHAR(1000) NULL	Internal only — not shown to customer
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

nurse_payout_batches

Weekly aggregation of all amounts owed to nurses for completed, unpaid bookings. Admin initiates a batch (manually or via a scheduled job). Each batch covers a specific period and produces one nurse_payouts row per nurse with earnings in that window.

Field	Type	Notes
id	BIGINT PK IDENTITY
period_start	DATE NOT NULL
period_end	DATE NOT NULL
total_amount	BIGINT NOT NULL	Sum of all nurse_payout_amount in this batch
payout_count	INT NOT NULL	Number of individual nurse payouts in this batch
status	NVARCHAR(30) NOT NULL DEFAULT 'draft'	draft / processing / completed / partially_failed / failed
initiated_by_admin_id	BIGINT FK → users NULL
processed_at	DATETIME2 NULL
failure_notes	NVARCHAR(1000) NULL
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

nurse_payouts

One row per nurse per batch. Records the exact amount transferred, which bank account was used (snapshot, not FK, because account may change), and the transfer reference for bank reconciliation.

Field	Type	Notes
id	BIGINT PK IDENTITY
batch_id	BIGINT FK → nurse_payout_batches NOT NULL
nurse_id	BIGINT FK → nurse_profiles NOT NULL
bank_account_id	BIGINT FK → nurse_bank_accounts NOT NULL	Primary account at time of payout
iban_snapshot	NVARCHAR(34) NOT NULL	(encrypted) — IBAN at time of payout; in case account is later changed
amount	BIGINT NOT NULL	Total paid to nurse in this batch (IRR)
booking_count	INT NOT NULL	How many bookings this covers
status	NVARCHAR(30) NOT NULL DEFAULT 'pending'	pending / processing / paid / failed
transfer_reference	NVARCHAR(200) NULL	Bank/ACH reference for reconciliation
paid_at	DATETIME2 NULL
failure_reason	NVARCHAR(500) NULL
created_at	DATETIME2 NOT NULL

---

nurse_payout_booking_links

Join table linking each payout to the specific bookings it covers. Enables per-booking reconciliation and prevents double-paying the same booking in a future batch.

Field	Type	Notes
id	BIGINT PK IDENTITY
payout_id	BIGINT FK → nurse_payouts NOT NULL
booking_id	BIGINT FK → bookings UNIQUE NOT NULL	UNIQUE ensures a booking can only appear in one payout
amount	BIGINT NOT NULL	nurse_payout_amount for this booking

---

Domain 7 — BNPL / Installments

When a customer pays via BNPL, the third-party provider approves the installment plan and pays the platform. The customer repays the BNPL provider directly. From the platform's perspective, the payment_transactions row is succeeded with is_installment = true. The tables below track the BNPL plan details for reconciliation, reporting, and potential future collections escalation.

⚠️ Open decision before implementation: Two BNPL settlement models exist and the choice affects this schema:

• Immediate full settlement — the provider pays the platform the full booking amount (possibly net of their own fee) in one transfer at approval time. In this case payment_transactions.amount is the booking's gross_amount, and installment_plans.total_amount may be higher (the provider charges the customer more than the booking price to cover their financing fee). The current schema handles this correctly — the two amounts live in separate fields on separate tables.

• Tranched settlement — the provider pays the platform in installments as the customer pays them. In this case a single payment_transactions row is insufficient; you would need either multiple rows in payment_transactions (one per provider settlement) or a dedicated bnpl_settlement_entries table linked to installment_plans. The current schema does not handle this — it would require an additive migration.

Confirm which model your chosen BNPL provider uses before building the payment integration.

---

installment_plans

Metadata about a BNPL approval linked to a specific payment transaction.

Field	Type	Notes
id	BIGINT PK IDENTITY
payment_transaction_id	BIGINT FK → payment_transactions UNIQUE NOT NULL	1:1
bnpl_provider_code	NVARCHAR(50) NOT NULL	Matches payment_gateways.code
external_plan_id	NVARCHAR(200) NOT NULL	Provider's plan identifier
total_amount	BIGINT NOT NULL	Total the customer owes the provider (IRR), may include provider fee
installment_count	TINYINT NOT NULL	Number of installments
monthly_fee_rate	DECIMAL(5,4) NULL	Provider's monthly fee rate
plan_start_date	DATE NOT NULL
plan_end_date	DATE NOT NULL
status	NVARCHAR(30) NOT NULL DEFAULT 'pending_approval'	pending_approval / approved / rejected / active / completed / defaulted
approved_at	DATETIME2 NULL
last_webhook_at	DATETIME2 NULL	When last webhook was received from provider
webhook_payload_json	NVARCHAR(MAX) NULL	Last webhook payload
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

installment_entries

Individual installment records. Updated via webhook from the BNPL provider when a payment occurs or is missed.

Field	Type	Notes
id	BIGINT PK IDENTITY
plan_id	BIGINT FK → installment_plans NOT NULL
installment_number	TINYINT NOT NULL	1-based
amount	BIGINT NOT NULL	Amount due for this installment (IRR)
due_date	DATE NOT NULL
paid_at	DATETIME2 NULL	NULL = not yet paid
status	NVARCHAR(20) NOT NULL DEFAULT 'upcoming'	upcoming / due / paid / overdue / defaulted
external_reference	NVARCHAR(200) NULL	Provider's reference for this specific installment
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

Domain 8 — Messaging (Ticket System)

There is no live chat and no direct messaging between nurse and customer. All post-booking communication runs through a structured ticket system where admin can read every message. This is intentional: it protects vulnerable patients, creates a paper trail for disputes, and prevents disintermediation. Tickets can also be used by customers or nurses to contact support for any reason.

---

tickets

A support or communication thread. May be linked to a booking, refund, or stand alone. Admin assigns, responds, and resolves tickets. Customers and nurses communicate through messages on their assigned ticket.

The reference_code is a human-readable identifier (e.g., TKT-2025-001234) communicated to users for support follow-up.

Field	Type	Notes
id	BIGINT PK IDENTITY
reference_code	NVARCHAR(30) UNIQUE NOT NULL	Human-readable code for support communication
subject	NVARCHAR(300) NOT NULL
type	NVARCHAR(50) NOT NULL	booking_coordination / booking_issue / refund_request / nurse_complaint / review_dispute / verification_question / general
status	NVARCHAR(30) NOT NULL DEFAULT 'open'	open / pending_customer / pending_nurse / pending_admin / resolved / closed
priority	NVARCHAR(20) NOT NULL DEFAULT 'medium'	low / medium / high / urgent
booking_id	BIGINT FK → bookings NULL	Context link — not required
refund_id	BIGINT FK → refunds NULL
created_by_user_id	BIGINT FK → users NOT NULL	Who opened the ticket
assigned_to_admin_id	BIGINT FK → users NULL	Current admin owner
resolved_at	DATETIME2 NULL
closed_at	DATETIME2 NULL
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

ticket_participants

Controls who has access to a ticket. Every ticket has at minimum its creator and an admin. Post-booking tickets may include both the customer and the nurse.

Field	Type	Notes
id	BIGINT PK IDENTITY
ticket_id	BIGINT FK → tickets NOT NULL
user_id	BIGINT FK → users NOT NULL
participant_role	NVARCHAR(20) NOT NULL	customer / nurse / admin / support
added_at	DATETIME2 NOT NULL
removed_at	DATETIME2 NULL	NULL = still active participant

Constraint: (ticket_id, user_id) UNIQUE.

---

ticket_messages

Messages within a ticket. is_internal = true messages are admin-only notes — they are never shown to the customer or nurse. This allows admins to coordinate internally without leaving the ticket context.

Field	Type	Notes
id	BIGINT PK IDENTITY
ticket_id	BIGINT FK → tickets NOT NULL
sender_user_id	BIGINT FK → users NOT NULL
body	NVARCHAR(MAX) NOT NULL
is_internal	BIT NOT NULL DEFAULT 0	True = admin-only note
attachments_json	NVARCHAR(MAX) NULL	JSON array of {storage_key, filename, mime_type}
created_at	DATETIME2 NOT NULL

---

Domain 9 — Reviews & Patient Records

---

review_tags_master

Admin-managed standardized tags for reviews. Allows quantitative aggregation of qualitative feedback (e.g., "% of reviews tagged 'punctual'"). Nurses can later see their most common tags on their profile.

Field	Type	Notes
id	BIGINT PK IDENTITY
name_fa	NVARCHAR(100) NOT NULL	e.g., "وقت‌شناس", "مهربان", "متخصص", "غیرحرفه‌ای"
name_en	NVARCHAR(100) NULL
sentiment	NVARCHAR(10) NOT NULL	positive / negative / neutral
is_active	BIT NOT NULL DEFAULT 1
sort_order	SMALLINT NOT NULL DEFAULT 0

---

reviews

Post-booking review by the customer about the nurse. Only one review per booking. Submitted reviews enter pending_moderation and are not shown publicly until an admin (or AI moderator) approves them. A rating of 1 or 2 with negative content automatically triggers a support_alerts row so the support team can investigate.

When a review is published, nurse_profiles.average_rating and total_reviews are updated.

Field	Type	Notes
id	BIGINT PK IDENTITY
booking_id	BIGINT FK → bookings UNIQUE NOT NULL	One review per booking
customer_id	BIGINT FK → customer_profiles NOT NULL
nurse_id	BIGINT FK → nurse_profiles NOT NULL	Denormalized for query performance
rating	TINYINT NOT NULL	1–5
body	NVARCHAR(2000) NULL	Free-text content
status	NVARCHAR(30) NOT NULL DEFAULT 'pending_moderation'	pending_moderation / published / rejected / hidden
moderated_by_admin_id	BIGINT FK → users NULL	Admin or AI agent that approved/rejected
moderation_notes	NVARCHAR(500) NULL	Internal reason for rejection or hiding
published_at	DATETIME2 NULL
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

review_tag_links

Tags applied to a specific review.

Field	Type	Notes
id	BIGINT PK IDENTITY
review_id	BIGINT FK → reviews NOT NULL
tag_id	BIGINT FK → review_tags_master NOT NULL

Constraint: (review_id, tag_id) UNIQUE.

---

patient_care_records

Nurse-authored clinical notes written after completing a booking. These accumulate over time and form a longitudinal care history for the patient. When a new nurse receives a booking request for the same patient, they can read this history to understand prior care, medications, and observations — enabling continuity of care across multiple nurses.

Access to these records is strictly controlled: only the patient's owning customer, nurses with a confirmed upcoming or in-progress booking for that patient, and admin may read them. All fields are encrypted.

Field	Type	Notes
id	BIGINT PK IDENTITY
patient_id	BIGINT FK → patients NOT NULL
booking_id	BIGINT FK → bookings NOT NULL	The specific visit that generated this record
nurse_id	BIGINT FK → nurse_profiles NOT NULL	Who authored the record
observations	NVARCHAR(MAX) NULL	(encrypted) — general notes on patient state during the visit
vitals_json	NVARCHAR(MAX) NULL	(encrypted) — structured: {blood_pressure, temperature, pulse, oxygen_saturation, ...}
medications_json	NVARCHAR(MAX) NULL	(encrypted) — medications administered or observed
conditions_note	NVARCHAR(MAX) NULL	(encrypted) — new or changed conditions noted by the nurse
recorded_at	DATETIME2 NOT NULL	When nurse submitted this record
created_at	DATETIME2 NOT NULL

---

Domain 10 — Notifications

---

notifications

In-app notification records for all user types. No push notifications at launch — these are polled on page load or explicitly fetched. The data_json carries a typed payload that the front-end uses to navigate to the relevant entity (e.g., open a specific booking, ticket, or payout screen).

Field	Type	Notes
id	BIGINT PK IDENTITY
user_id	BIGINT FK → users NOT NULL	Recipient
type	NVARCHAR(80) NOT NULL	e.g., booking_request_received, booking_accepted, booking_rejected, booking_request_expired, payment_succeeded, payment_failed, booking_confirmed, review_published, review_rejected, payout_processed, ticket_new_message, verification_update, nurse_no_show_alert
title_fa	NVARCHAR(300) NOT NULL
body_fa	NVARCHAR(500) NULL
data_json	NVARCHAR(MAX) NULL	e.g., {"entity_type": "booking", "entity_id": 1234}
is_read	BIT NOT NULL DEFAULT 0
read_at	DATETIME2 NULL
created_at	DATETIME2 NOT NULL

---

support_alerts

Internal alerts visible only to the support and admin team. Not shown to customers or nurses. Automatically generated by platform rules (low review ratings, EVV no-shows, payment anomalies) or manually by admin. Each alert has an owner and a resolution trail.

Field	Type	Notes
id	BIGINT PK IDENTITY
alert_type	NVARCHAR(50) NOT NULL	low_rating_review / nurse_no_show / payment_anomaly / verification_step_expired / evv_location_mismatch / fraud_signal
severity	NVARCHAR(20) NOT NULL	info / warning / critical
entity_type	NVARCHAR(50) NOT NULL	e.g., review, booking, payment_transaction, verification_step
entity_id	BIGINT NOT NULL
description	NVARCHAR(500) NOT NULL	Human-readable summary
status	NVARCHAR(20) NOT NULL DEFAULT 'open'	open / acknowledged / resolved / dismissed
assigned_to_admin_id	BIGINT FK → users NULL	NULL = unassigned
resolved_at	DATETIME2 NULL
resolved_by_admin_id	BIGINT FK → users NULL
resolution_notes	NVARCHAR(500) NULL
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

Domain 11 — Audit & Logging

---

audit_logs

Immutable, append-only record of all state-changing operations on sensitive entities. Every insert, update, or status change on bookings, payments, refunds, verifications, reviews, and user accounts produces a row here. This table must never be updated or deleted — archive to cold storage after a retention period.

changed_fields_json stores just the names of fields that changed, enabling fast filtering ("show me all booking status changes") without parsing full old/new value diffs.

Field	Type	Notes
id	BIGINT PK IDENTITY
entity_type	NVARCHAR(100) NOT NULL	Table name: bookings, payment_transactions, refunds, nurse_verifications, verification_steps, reviews, users, nurse_profiles
entity_id	BIGINT NOT NULL	PK of the affected row
action	NVARCHAR(20) NOT NULL	created / updated / status_changed / deleted
old_values_json	NVARCHAR(MAX) NULL	Full row snapshot before change (NULL for creates)
new_values_json	NVARCHAR(MAX) NULL	Full row snapshot after change (NULL for deletes)
changed_fields_json	NVARCHAR(MAX) NULL	JSON array of field names that changed
performed_by_user_id	BIGINT FK → users NULL	NULL for system/background jobs
performed_by_role	NVARCHAR(50) NULL	Captured at action time
ip_address	NVARCHAR(45) NULL
user_agent	NVARCHAR(500) NULL
request_id	NVARCHAR(100) NULL	Correlation ID from API request for distributed tracing
created_at	DATETIME2 NOT NULL

---

system_events

Higher-volume behavioral event log for analytics, funnel analysis, and future fraud detection feature engineering. Distinct from audit_logs — audit is for compliance and accountability; system_events is for product analytics and monitoring. May be partitioned by month or archived to a data warehouse.

Field	Type	Notes
id	BIGINT PK IDENTITY
event_type	NVARCHAR(100) NOT NULL	e.g., nurse_search_performed, nurse_profile_viewed, booking_request_submitted, payment_initiated, verification_step_started
user_id	BIGINT FK → users NULL	NULL for anonymous or system events
session_id	NVARCHAR(100) NULL	App session identifier
payload_json	NVARCHAR(MAX) NULL	Event-specific properties (search filters, variant viewed, etc.)
source	NVARCHAR(30) NOT NULL	api / background_job / admin_panel / webhook
ip_address	NVARCHAR(45) NULL
created_at	DATETIME2 NOT NULL

---

Domain 12 — Platform Configuration

---

platform_configs

Key-value store for runtime-tunable business parameters. Changing a parameter (e.g., raising the platform fee, adjusting the nurse response deadline) does not require a deployment — admin edits a row and the application picks it up. Values are stored as strings; the data_type field tells the application how to parse them.

Representative keys and their purpose:

Key	Description
platform_fee_rate	Decimal — e.g., 0.1500 (15%). Used for new bookings only.
booking_payment_deadline_minutes	Integer — how long the customer has to pay after nurse accepts. Default 30.
nurse_response_deadline_hours	Integer — how long before a booking request auto-expires.
nurse_payout_interval_days	Integer — how many days after period_end before a batch is created.
default_refund_percentage	Decimal — default % refunded when admin approves. Default 100.
min_rating_for_support_alert	Integer — reviews with rating ≤ this value trigger a support_alert. Default 2.
evv_location_tolerance_meters	Integer — GPS match tolerance for check-in address verification.
review_requires_admin_approval	Boolean — whether all reviews need moderation before publish.

Field	Type	Notes
id	BIGINT PK IDENTITY
key	NVARCHAR(100) UNIQUE NOT NULL
value	NVARCHAR(500) NOT NULL
data_type	NVARCHAR(20) NOT NULL	integer / decimal / boolean / string / json
description	NVARCHAR(500) NULL
updated_by_admin_id	BIGINT FK → users NULL
updated_at	DATETIME2 NOT NULL
created_at	DATETIME2 NOT NULL

---

Domain 13 — Future Extensions (modeled now, inactive at launch)

These tables are defined now to avoid a painful migration when the features ship. They carry no data at launch but the FK relationships are already established so the rest of the schema doesn't need to change.

---

organizations

Nursing companies that may register on the platform and add their employed nurses. Each nurse remains individually verified and responsible. The organization acts as a sponsor/guarantor for its nurses and may have a separate dashboard.

Field	Type	Notes
id	BIGINT PK IDENTITY
name	NVARCHAR(300) NOT NULL
type	NVARCHAR(30) NOT NULL	nursing_company / staffing_agency
moh_license_number	NVARCHAR(100) NULL	MoH establishment permit (پروانه تأسیس)
admin_user_id	BIGINT FK → users NOT NULL	Organization's admin account
is_verified	BIT NOT NULL DEFAULT 0	Platform-verified
verified_at	DATETIME2 NULL
is_active	BIT NOT NULL DEFAULT 1
created_at	DATETIME2 NOT NULL
updated_at	DATETIME2 NOT NULL

---

organization_nurses

Membership link between a nurse and an organization. A nurse can belong to at most one active organization at a time (enforced by checking left_at IS NULL).

Field	Type	Notes
id	BIGINT PK IDENTITY
organization_id	BIGINT FK → organizations NOT NULL
nurse_id	BIGINT FK → nurse_profiles NOT NULL
joined_at	DATETIME2 NOT NULL
left_at	DATETIME2 NULL	NULL = current member
status	NVARCHAR(20) NOT NULL	active / suspended / left

---

fraud_flags

Signals from a future fraud detection service. Modeled now so the schema is ready to receive data when the detection layer is built, requiring no migration. The confidence_score field anticipates an ML model output.

Field	Type	Notes
id	BIGINT PK IDENTITY
entity_type	NVARCHAR(50) NOT NULL	user / payment_transaction / booking
entity_id	BIGINT NOT NULL
flag_type	NVARCHAR(100) NOT NULL	e.g., identity_mismatch, unusual_payment_velocity, address_anomaly, kyc_response_inconsistency
severity	NVARCHAR(20) NOT NULL	low / medium / high
confidence_score	DECIMAL(5,4) NULL	0.0000–1.0000 from detection model
details_json	NVARCHAR(MAX) NULL	Evidence from the detection model
status	NVARCHAR(30) NOT NULL DEFAULT 'open'	open / investigating / confirmed_fraud / false_positive / resolved
assigned_to_admin_id	BIGINT FK → users NULL
created_at	DATETIME2 NOT NULL
resolved_at	DATETIME2 NULL

---

recurring_booking_schedules

Future feature: allows families to establish a repeating care pattern (e.g., every Monday and Thursday morning with the same nurse). At launch, all bookings are one-off. The rrule field uses the RFC 5545 recurrence rule format, which is widely supported by scheduling libraries.

Field	Type	Notes
id	BIGINT PK IDENTITY
customer_id	BIGINT FK → customer_profiles NOT NULL
nurse_id	BIGINT FK → nurse_profiles NOT NULL
variant_id	BIGINT FK → nurse_service_variants NOT NULL
patient_id	BIGINT FK → patients NOT NULL
customer_address_id	BIGINT FK → customer_addresses NOT NULL
rrule	NVARCHAR(500) NOT NULL	RFC 5545 recurrence rule, e.g., FREQ=WEEKLY;BYDAY=MO,TH
scheduled_time_start	TIME NOT NULL
scheduled_time_end	TIME NOT NULL
effective_from	DATE NOT NULL
effective_until	DATE NULL	NULL = indefinite
is_active	BIT NOT NULL DEFAULT 1
created_at	DATETIME2 NOT NULL

---

Relationship Summary

Relationship	Type	Notes
users → nurse_profiles	1:1	role = nurse
users → customer_profiles	1:1	role = customer
customer_profiles → patients	1:N	One family, many patients
customer_profiles → customer_addresses	1:N
nurse_profiles → nurse_bank_accounts	1:N	One primary at a time
nurse_profiles → nurse_service_variants	1:N	Each variant is one bookable offering
nurse_service_variants → nurse_service_variant_options	1:N	Defines the option combination
service_option_groups → service_option_values	1:N
nurse_profiles → nurse_service_areas	1:N	Many city/district pairs
nurse_profiles → nurse_verifications	1:1
nurse_verifications → verification_steps	1:N	One per step type
verification_steps → verification_documents	1:N
booking_requests → bookings	1:1	Created on nurse accept + payment
bookings → booking_care_instructions	1:1
bookings → visit_verifications	1:1	EVV record
bookings → payment_transactions	1:N	Multiple attempts allowed
payment_transactions → refunds	1:1	One refund per transaction
payment_transactions → installment_plans	1:1	Only if is_installment = true
installment_plans → installment_entries	1:N	One per installment
nurse_payout_batches → nurse_payouts	1:N	One per nurse per batch
nurse_payouts → nurse_payout_booking_links	1:N	Detailed booking breakdown
nurse_payout_booking_links → bookings	N:1	Each booking in exactly one payout
bookings → reviews	1:1	One review per booking
reviews → review_tag_links	1:N
patients → patient_care_records	1:N	Grows with every visit
tickets → ticket_participants	1:N
tickets → ticket_messages	1:N
tickets ↔ refunds	1:1 (optional)	Refund conversation
Sensitive entities → audit_logs	*:N	Append-only change log

---

Key Design Decisions

Why booking_requests and bookings are separate tables A booking request may be rejected, expire, or have its payment deadline lapse without a booking ever being created. Merging these would require many nullable fields and complex status logic. Keeping them separate makes each table's invariants clear: a bookings row always has a successful payment.

Why variant_snapshot_json exists on bookings If a nurse later edits or deletes a variant, historical bookings must still display what the customer paid for. The FK to nurse_service_variants is kept for joins but variant_snapshot_json is the authoritative record for display and dispute.

Why monetary amounts are stored as BIGINT (IRR) Rials are the smallest unit; there are no decimal subdivisions in practice. Storing as BIGINT eliminates floating-point precision issues. All division (for fee calculation) is done in application code with explicit rounding rules.

Why platform_fee_rate is stored per booking The platform's fee schedule will change over time. Deriving the split from platform_configs would corrupt historical reporting. Every booking stores the rate that was in effect at the moment of confirmation.

Why the verification pipeline is data-driven verification_step_types rows define what steps exist and whether they're automated. Adding a new regulatory requirement (e.g., professional liability insurance in year 2) requires one INSERT, not a schema migration and code deploy.

Why there is no direct nurse ↔ customer messaging Platform safety design: all communication is ticket-based and admin-readable. This protects vulnerable patients, provides dispute evidence, and prevents disintermediation. Post-booking coordination (nurse asking about the patient's room location, customer asking about arrival time) happens through a ticket of type booking_coordination.

Why patient_care_records are nurse-authored and patient-scoped Clinical notes build a longitudinal record for the patient, not the booking. When a different nurse takes over care, they read the history before accepting the booking request, making care continuity possible without the family having to repeat everything.

Advices

Several things stand out after sitting with the full model:

1. The nurse search query will be expensive from day one

Finding nurses requires joining nurse_profiles (verified + accepting) → nurse_service_variants (category + price range) → nurse_service_variant_options → nurse_service_areas (city/district). That's already 4 joins before any sorting by rating or availability. At even modest scale this becomes slow.

Advice: build a denormalized nurse_search_index table that is updated on writes (when a nurse edits a variant, changes their area, or gets a new review). This table stores one row per variant with all search-relevant fields flat. Read path hits one table; write path maintains it. Much cheaper than adding Elasticsearch to the stack at your current stage.

2. The two-stage clinical disclosure is implicit — make it explicit

Right now booking_requests.customer_notes (1000 chars, unencrypted) is what the nurse sees when deciding to accept. The full booking_care_instructions (encrypted, medications, conditions, etc.) only exists after the booking is confirmed. This boundary is correct and security-smart, but it's nowhere stated in the model.

If you don't document this explicitly in the API contract, a developer will one day accidentally expose the full clinical record to a nurse at the request stage — before any commitment. Write this rule into the model comments and enforce it at the application layer, not just by convention.

3. Dispute window vs payout timing can overlap

A booking can be disputed after the weekly payout batch already ran and the nurse was paid. The current model has no clawback mechanism — nurse_payouts has no way to record that money needs to come back. Consider adding clawback_amount and clawback_status to nurse_payouts, or simply enforce a policy that payout only runs for bookings where the dispute window has closed (e.g., 72 hours post-completion). Either way, document the rule.

4. The ticket system has an urgent on-site gap

The ticket system is async. If a nurse arrives and the patient doesn't answer the door, or there's a medical emergency, there is no real-time channel in the model. The only outlet is the emergency contact phone number buried in booking_care_instructions. This is probably acceptable for v1 — but be intentional about it. The operational playbook for nurses should explicitly say "in an emergency, call the emergency contact number from the app, then open a ticket." Otherwise nurses will try to find the family's phone number by other means, which breaks the platform's communication control.

5. Three tables will eat your disk quietly

audit_logs, system_events, and notifications grow without any natural bound. Before you hit production, decide:

audit_logs — partition by month, archive after 2–3 years to cold storage system_events — same, or pipe directly to a data warehouse and don't keep them in SQL Server at all notifications — add a job that hard-deletes read notifications older than 90 days If you don't plan this before launch, you'll be doing emergency archiving under pressure later.

6. is_verified on nurse_profiles is a derived value — protect it

This flag is true when all required verification steps pass. But it lives as a column that could theoretically be set independently. If a bug or a rogue admin sets is_verified = 1 without the steps passing, an unvetted nurse becomes bookable. Enforce this transactionally: the only code path that sets is_verified = true should be the one that also checks all required verification_steps.status = 'passed', inside the same transaction. Never expose a direct update API for this field.