نُزُل · Nuzul — Arabic-first PMS for hotels & serviced apartments (Oman / GCC)

MVP implementation of the PRD (v1.0, 14 Oct 2026): reservations, availability, guests, check-in/out, folios, invoices with Omani taxes & fees, cash shifts, housekeeping, maintenance, owner dashboard, reports, ROP / Ministry compliance exports, roles and an append-only audit log.

Stack: Next.js 16 (App Router, server actions) · TypeScript · Tailwind 4 · Supabase (Postgres 17, Auth, Storage, pg_cron).

Binding technical decisions (PRD §9) and where they live

Decision	Implementation
Multi-tenancy from the first table	tenant_id on every table + RLS via private.user_tenant_ids() / private.has_role() (supabase/migrations/0001…0005)
No double bookings	EXCLUDE USING gist (unit_id WITH =, stay WITH &&) on active reservations (reservations_no_overlap)
Money in baisa	every amount is bigint (1 OMR = 1000 baisa); UI converts with src/lib/format.ts
Immutable audit log	audit_log filled by SECURITY DEFINER triggers; updates/deletes raise IMMUTABLE
Immutable invoices	sequential gap-free numbering per tenant (document_sequences), frozen JSON snapshot, corrections by credit note only
Async integrations	outbox_events (reservation.created, guest.checked_in, invoice.issued) for future ROP/Fawtara/channel workers

PRD coverage (P0)

ID	Status	Notes
FR-01	✅	company → property → floor → unit; bulk unit creation (101-120, 201-220)
FR-02	✅	nightly/monthly rates + seasonal rate_plans (Ramadan, Eid, Khareef) auto-applied
FR-03	✅	six statuses; transitions driven by check-in/out, housekeeping and maintenance
FR-04	✅	available_units() (GiST-indexed)
FR-05	✅	DB exclusion constraint → friendly CONFLICT error
FR-06	✅	14-day tape chart with drag & drop + Hijri dates, conflict-checked on save
FR-10–14	✅	create / change / extend / move / cancel / no-show; sources; discount limit needs manager; monthly contracts with billing schedules (posted daily by pg_cron); refundable deposits kept as liability
FR-20	✅	in-browser OCR (tesseract.js) of the MRZ on Omani/GCC IDs & passports; staff review before save
FR-21	✅	consent_at NOT NULL — no consent, no profile; separate consent for transfer abroad
FR-22–24	✅	guest search/history; check-in validates documents, unit readiness; check-out warns on balance and creates a cleaning task
FR-30–35	✅	bilingual invoice + credit notes, configurable tax engine, multi-method/partial payments, expenses, cash shift with variance per employee, aging 0-30/31-60/61-90/90+ with WhatsApp reminders
FR-40	✅	mobile cleaning list, arrivals first; "Ready" makes the unit available
FR-43	✅ (early P1)	blocking maintenance tickets remove a unit from availability
FR-53+	✅	owner grants/revokes sections per employee (Settings → Manage permissions); enforced by private.has_role in the database, not only hidden in the UI
FR-50–55	✅	owner dashboard, occupancy/ADR/RevPAR, CSV exports, six roles, audit log, wa.me sharing
CR-01/02	✅ structured export	ROP guest register CSV + ministry statistics; every export logged in compliance_submissions
CR-03–06	✅	tourism 4%, municipality 5%, VAT 5%, service charge (0–8%, off by default) — all editable per tenant

Run locally

cp .env.example .env.local   # Supabase URL + publishable key
npm install
npm run dev

Database tests

supabase/tests/ runs the full schema on plain Postgres (with a tiny stub of Supabase's auth/storage):

createdb hotel
psql -d hotel -f supabase/tests/00_supabase_stub.sql
for f in supabase/migrations/*.sql; do psql -v ON_ERROR_STOP=1 -d hotel -f "$f"; done
psql -d hotel -f supabase/tests/01_core_flows.sql   # → ALL TESTS PASSED
psql -d hotel -f supabase/tests/02_invitations.sql
psql -d hotel -f supabase/tests/03_unit_guard.sql     # → UNIT GUARD OK
psql -d hotel -f supabase/tests/04_permissions.sql    # → PERMISSIONS OK
psql -d hotel -f supabase/tests/05_job_titles.sql     # → JOB TITLES OK
psql -d hotel -f supabase/tests/06_analytics.sql      # → ANALYTICS OK
psql -d hotel -f supabase/tests/07_alerts_search.sql  # → ALERTS SEARCH OK

01_core_flows.sql proves tenant isolation (NFR-01), the conflict constraint, discount approval, check-in/out rules, taxes, invoices/credit notes immutability, contracts, cash-shift variance, role restrictions and audit-log immutability.

Staff accounts

Owner/manager invites an email + role in Settings. The employee signs up with that email; on first sign-in the invitation is attached automatically (accept_invitations()).

Deployment

• Supabase: project hotel (isijnklsskwbdbmmertk) — all migrations in supabase/migrations are applied.
• Vercel: project nuzul-hotel (https://nuzul-hotel.vercel.app) is connected to this GitHub repo; every push to claude/blissful-einstein-kbkcp6 (the repo's default branch) deploys to production automatically.
• Supabase Auth settings: set Site URL to the Vercel production URL and add https://<your-domain>/auth/callback to Redirect URLs, so sign-up confirmation emails land back in the app. TOTP MFA must stay enabled (default).

Not yet built (next steps)

Daily owner report delivery (FR-52 auto-send), direct ROP/MHT API, Fawtara provider, Thawani links, WhatsApp Business API, channel manager, offline mode.