hotelyn

Repository layout

hotelyn/
├── pubspec.yaml            ← workspace root (workspace: [...], melos: [...])
├── apps/
│   ├── hotelyn_app/        ← Flutter mobile app (Android, iOS)
│   └── hotelyn_dashboard/  ← Flutter dashboard app (Android, iOS, Web)
├── packages/
│   ├── hotelyn_api_client/ ← REST client (package:http) over the Dart Frog API
│   ├── hotelyn_domain/     ← domain entities (json_serializable) & interfaces
│   └── hotelyn_ui/         ← shared widget library & design system
├── backend/                ← Dart Frog REST server (talks to Supabase)
└── supabase/               ← local Supabase stack config + migrations

Setup

Prerequisites: Flutter stable channel, Dart ≥ 3.5.0, Melos ≥ 7.

Follow these steps in order on a fresh clone:

1. Install Flutter (stable channel) by following the official install guide for your OS.
2. Confirm your toolchain is healthy:

   flutter doctor
   

   Resolve any issues it reports (e.g. missing Android/iOS toolchains) before continuing.
3. Clone the repository and cd into it:

   git clone https://github.com/enzoftware/hotelyn.git
   cd hotelyn
   

4. Activate Melos globally (once per machine), then make sure the Pub cache bin directory is on your PATH so the melos command is available in new shells:

   dart pub global activate melos
   export PATH="$PATH:$HOME/.pub-cache/bin"
   

5. Bootstrap the workspace — this resolves and links every app/package/server in one shot:

   melos bootstrap
   

6. Verify the workspace is healthy:

   melos run analyze
   melos run test
   

7. Re-run flutter doctor — it should be clean with no unresolved issues:

   flutter doctor
   

No other manual setup is required. Steps 1–7 are the complete bootstrap sequence for a new machine.

Local Supabase stack

The app never talks to Supabase directly (see Architecture) — only the backend REST server does. To run that stack locally:

Prerequisites: Docker running, Supabase CLI ≥ 2.x.

1. Start the stack (Postgres, Auth, Storage, Realtime, PostgREST, Studio). On the first run this also applies every migration in supabase/migrations/ and loads supabase/seed.sql:

   supabase start
   

2. Confirm every service is healthy and note the printed URLs/keys:

   supabase status
   

3. Apply the schema and (re)load the seed data. Run this whenever migrations or supabase/seed.sql change, or whenever you want a clean, known dataset — it drops the local database, re-runs all migrations (the first enables postgis), then loads the seed:

   supabase db reset
   

   The seed is idempotent and deterministic (fixed IDs/coordinates), so a reset always produces the same six hotels, their rooms, and the two test accounts listed under Data model — safe to run as often as you like.
4. Verify the seed loaded (should print 6). Copy DB_URL from supabase status:

   psql "$DB_URL" -c 'select count(*) from hotels;'
   

   No local psql? Browse the tables in Studio (step 6), or run the query inside the database container:

   docker exec -it supabase_db_hotelyn \
     psql -U postgres -d postgres -c 'select count(*) from public.hotels;'
   

5. Copy the env templates and fill in the values supabase status printed:

   cp backend/.env.example backend/.env
   cp apps/hotelyn_app/.env.example apps/hotelyn_app/.env
   cp apps/hotelyn_dashboard/.env.example apps/hotelyn_dashboard/.env
   

6. Open Studio at the printed STUDIO_URL (defaults to http://127.0.0.1:54323) to browse the seeded schema and data.
7. When you're done, stop the stack:

   supabase stop
   

Data model

The schema (see supabase/migrations/) is four normalized tables plus enum types and Row Level Security:

Table	Notes
profiles	1:1 with auth.users; holds role (guest/hotel_staff/admin) + hotel_id.
hotels	Includes a PostGIS location geometry(Point, 4326) with a GiST index.
rooms	FK → hotels; is_available flags bookable rooms.
reservations	FK → hotels/rooms/profiles; status enum; hold_expires_at + unique confirmation_code. Partial unique index on room_id WHERE status IN ('held','confirmed') makes double-booking impossible.

RLS is enabled on every table: guests browse available rooms and manage only their own reservations; hotel staff read/write only their own hotel's rooms and reservations. The seed (supabase/seed.sql, loaded by supabase db reset) is deterministic: six hotels across LatAm + North America launch cities, a mix of available/unavailable rooms, and two test accounts (local password password123):

Account	Role
guest@hotelyn.test	guest
staff@hotelyn.test	hotel_staff (owns the Lima hotel)

Metre-accurate proximity search casts location to geography (a distance in metres), which is served by the dedicated functional GiST index rather than the degree-based one:

-- hotels within 5 km of a point (lon, lat)
select name from hotels
where st_dwithin(location::geography,
                 st_setsrid(st_makepoint(-77.03, -12.11), 4326)::geography, 5000);

The RLS policies (and the geolocation functions below) are covered by automated pgTAP tests — the Hotel A / Hotel B isolation proof plus the search-function behaviour:

supabase test db

Geolocation search & recommendations

Three SECURITY DEFINER SQL functions (migration ..._geo_search.sql) power search. They read every reservation to compute availability but only ever return public catalogue rows:

Function	Purpose
nearby_hotels(lat, lng, radius_km)	Hotels within the radius (ST_DWithin), nearest-first with a distance_km (ST_Distance). Empty set when nothing is in range.
rooms_with_availability(hotel_id?)	Each room with available_now = flagged available and no unexpired held/confirmed hold (hold_expires_at > now()). Expired holds don't block.
recommended_hotels(lat, lng, radius_km)	In-radius hotels ranked by confirmed reservations in the trailing recommendation_window_days() (30), ties broken by proximity. Cold-start (all zero) falls back to nearby filtered to available-now.

Nearby search is index-accelerated: p95 ≈ 0.3 ms with 100 hotels (200 runs, local stack) — well under the 300 ms budget.

Reservation holds (EPIC-04)

A hold is a short-lived, exclusive claim on a room (default 15 min, see hold_duration()) so a guest can finish checkout without being double-booked. Correctness is the database's job — the migration ..._reservation_holds.sql enforces it structurally:

Piece	What it does
Partial unique index reservations_active_room_uidx	At most one held/confirmed reservation per room. A concurrent second hold loses to the constraint — no application lock needed (BE-401).
create_reservation_hold(room_id, guest_id, check_in, check_out)	INSERT … ON CONFLICT DO NOTHING: returns the created reservation, or zero rows when the room is already held (the client maps this to a typed 409 RoomAlreadyHeldException). Generates the confirmation_code in the same transaction and reclaims any lapsed hold first (BE-402).
Query-time expiry	No paid scheduler: status may read held after real expiry, but every read path treats held AND hold_expires_at < now() as free, so no user ever sees a stale-blocked room (BE-403).

The single-winner guarantee and expiry behaviour are covered by pgTAP (supabase/tests/reservation_holds_test.sql).

Hotel-side inventory (EPIC-05)

Staff-facing operations over their own hotel (migration ..._hotel_inventory.sql). Because the backend holds the service-role key and so bypasses RLS, each staff RPC takes the acting profile (p_actor) and re-checks ownership itself (actor_manages_hotel) — exactly as the hold RPC guards on auth.uid(). RLS (BE-203) remains the boundary for any direct client.

Piece	What it does
staff_room_list(actor, hotel_id?)	The actor's own hotel rooms with a derived status — available / unavailable / held / occupied — using the query-time expiry rule. Scope comes from the actor's profile, never a client-supplied hotel id (BE-501).
set_room_availability(actor, room_id, is_available)	Toggle availability, ownership-checked. Refuses to set available while an active hold/confirmed reservation would double-allocate the room (room_has_active_reservation) (BE-502).
confirm_reservation(actor, id) / reject_reservation(actor, id)	Owning staff confirm or reject a reservation. Confirming an expired hold fails (hold_expired) rather than resurrecting it; rejecting frees the room immediately (BE-503).
supabase_realtime publication	reservations is published for Realtime; a staff session's subscription is scoped to its own hotel by the existing RLS select policy. The dashboard subscription is wired in the app layer (BE-504).

Covered by pgTAP (supabase/tests/hotel_inventory_test.sql).

Booking confirmation & manual payment (EPIC-07)

The MVP has no online payment integration: a guest pays in person and staff mark the reservation paid (migration ..._manual_payment.sql). Like the other staff RPCs it takes the acting profile and re-checks ownership via actor_manages_hotel.

Piece	What it does
confirmation_code (BE-701)	6+ char Crockford-base32 handle (HZ-…, no I/L/O/U) generated inside create_reservation_hold and unique among reservations; the RPC retries on the astronomically rare collision. Already landed with the hold engine (EPIC-04).
mark_reservation_paid(actor, id)	Owning staff mark a live hold paid: it transitions to confirmed, its expiry is cleared, and paid_by/paid_at are stamped for dispute resolution. Refuses (reservation_not_payable) anything that is not a live hold — already-confirmed, terminal, or an expired hold (BE-702).

Covered by pgTAP (supabase/tests/manual_payment_test.sql).

Deferred (BE-703). ID/age verification data capture is a documented phase-2 item (decision #3) and is not built in the MVP. Shipping to real users in "hoteles de paso" jurisdictions without it is a compliance gap to close before launch, not a missing feature here.

Realtime & the REST-only rule. The apps have no direct Supabase dependency (see the architecture note at the top), so #174's dashboard subscription is a follow-up in the app layer; this change lands only the DB-side enabler.

Auth note. The staff RPCs are granted to service_role only, so they are reachable only through the backend (a logged-in user cannot call them directly via PostgREST and pass someone else's p_actor). The backend derives the ac