Hotel Booking Lab

A hands-on learning project that rebuilds the core of a hotel booking platform (think Agoda / Booking.com) small enough to read in an afternoon, but with the real hard parts left in: atomic inventory under concurrency, a payment lock with timeouts, the transactional Outbox pattern into Kafka, role-based access with admin impersonation, a built-in load simulator that shows you where the bottlenecks are, and a Redis capacity test that fills Redis until it is full.

Everything runs locally with Docker Compose or Podman Compose. Nothing is production-ready on purpose: passwords are plain text and shown on the login page so anyone can try every role.

podman compose up --build
# or
docker compose up --build

Redis is capped at 400 MB (maxmemory, writes are refused when full instead of the VM running out of memory). Change it with REDIS_MAXMEMORY=1500mb podman compose up -d --force-recreate redis, after giving the Podman VM enough RAM.

Then open:

The login page lists every account with its password; click a row to log in. On a fresh database only the admin exists (admin@example.com / admin123). Log in as admin and press Generate Sample Data to create 20 hotels, two sellers and two customers, with example prices: Thailand's day-of-week defaults and high season (15 Dec – 15 Jan +40%), a fixed New Year's Eve price per room type, and an autumn discount on half of the hotels. Re-running it is safe.

The login page also shows the catalogue at a glance (hotels, rooms, room-nights bookable right now) and the accounts in three tables: admins, sellers and customers.

After changing code, rebuild and recreate the containers (podman-compose does not recreate on image change by itself):

podman compose up --build -d --force-recreate --no-deps api availability-worker web

As a customer

• Search hotels by country and city, pick check-in / check-out dates, open a hotel to see per-night availability, the price of every night (weekend, season and holiday prices marked) and the total for the stay.
• Results show a Sold out badge when no room is free for every night of the selected dates, are paged (10 / 20 / 50 / 100 per page, pager above and below the results) and can be viewed as cards or as a compact list with a small picture.
• Book a room: the nights are locked for you immediately and the booking is Awaiting payment. Pay within 60 seconds in My bookings or the status becomes Payment timed out and the room is released.
• My bookings shows a live countdown, a Pay button, a Cancel button for upcoming stays, a stay-phase badge (Upcoming / Staying now / Completed) and a warning when two of your stays overlap.

As a seller

• Dashboard: stat tiles and charts (booked vs free rooms per night, occupancy per hotel) for the next 7 / 14 / 30 days, with a table view.
• My hotels: only the hotels you own, with availability and the bookings on each. Search is scoped the same way, enforced by the API.
• Prices: per hotel, set the base price of each room type, your own day-of-week % (an empty day uses the country default), and seasons, holidays and discounts for one room type or all. Prices stack: season × day of week − discount; a holiday replaces season and day of week. A 60-night calendar shows every room type's price, and hovering a price shows its layers. Existing bookings keep the price they were made at.

As an admin

• Generate / delete sample data, create sample bookings for a chosen customer, rebuild the Redis availability cache from PostgreSQL.
• Redis records: every room × night of the window with the value Redis holds, window check (every room has every night), Redis RAM used vs its limit. Availability log: every run of the availability worker.
• Concurrency demo: every customer books the same room at the same instant; see exactly who wins.
• Load simulation with a report that ranks the slowest steps (p95) and a Cancel-all button:
  • Random rooms this week: N customers book random rooms at once, optionally only in one country or city; a share pays, a share lets the lock expire and rebooks, the rest abandon.
  • Same room, 7 nights: everyone wants one room; rejected customers cascade to another room type in the hotel, then to another hotel (anywhere, same country or same city).
• Country pricing: each country's default day-of-week % (e.g. Israel Mon −15%, Thu +30%, Fri +40%, Sat +10%; Thailand Wed −10%, Fri +20%, Sat +30%) and national seasons and holidays. Every hotel in the country inherits them unless it overrides.
• Redis capacity test: generate 1,000 to 1,000,000 sellers with 1, 10 or 100 hotels each (3 room types, spread over 20 cities in 6 countries), with 0, 10, 50 or 90% of the next 365 nights booked. Hotels alone cost no Redis memory; the occupancy is written to Redis as synthetic booked counts (Redis only) to measure how memory grows with bookings. It runs in batches of 250 until done, stopped, or Redis reaches maxmemory; the half-written batch is then rolled back. Tiles show Redis RAM, keys, bytes per key and progress. Remove capacity-test data deletes it all again.

1. POST /api/bookings runs one Lua script over every night of the stay. Redis stores how many rooms are booked per night (nothing stored = all free), and capacity comes from PostgreSQL. If any night is full it returns -1 and changes nothing; otherwise it adds 1 to every night atomically, so concurrent requests cannot oversell.
2. Inside the booking transaction PostgreSQL has the last word: it locks the room type and counts active bookings per night. If Redis was ever wrong (lost writes, a rebuild racing a booking) the booking is rejected as sold out instead of overbooking.
3. The booking row is inserted as PENDING with expires_at = now() + 60s, together with booking.created and room.availability.changed rows in the outbox_events table, in the same transaction.
4. POST /api/bookings/:id/pay is a single conditional UPDATE ... WHERE status='PENDING' AND expires_at > now(), so a late payment and the expiry worker can never both win.
5. A worker moves expired PENDING rows to PAYMENT_TIMEOUT (FOR UPDATE SKIP LOCKED), gives the nights back to Redis and writes booking.payment_timeout.
6. The outbox publisher sends unpublished events to Kafka and stamps published_at. Watch the topics in Kafka UI: booking.created, booking.confirmed, booking.payment_timeout, booking.cancelled, room.availability.changed.
7. Redis is treated as a cache: at startup (and from the admin panel) the booked counts are rebuilt from the bookings table, and until that has run once (key av:loaded) bookings are refused rather than treating an empty Redis as "all free". Month keys expire after their month; the availability worker also removes past nights daily.

More detail in ARCHITECTURE.md.

100 customers booking at once on a laptop, single API instance:

The publisher (1.5 s poll, one Kafka send per event) is the bottleneck by two orders of magnitude; Redis is negligible. Obvious next steps: batch the Kafka sends, replace polling with LISTEN/NOTIFY, shorten the worker interval.

Podman VM with 2 GB RAM, Redis capped at 400 MB. Memory per hotel (3 room types, next 365 nights):

Before, memory grew with the catalogue: Redis was full at ~3,750 hotels and 1,000,000 hotels would need ~120 GB. Now it grows with bookings: 400 MB holds ~50,000 hotels at 10% occupancy or ~36,000 at 90%, and 1,000,000 hotels need ~8 GB at 10%. Rebuilding Redis from the sample bookings takes ~30 ms. When Redis is full it refuses writes, so new bookings fail too.

apps/api/src/server.ts   Fastify API, workers, simulation, capacity test (single file on purpose)
apps/availability-worker/src/worker.ts   daily roll of the Redis availability window
apps/web/src/main.tsx    React SPA
apps/web/src/style.css
database/init.sql        schema for a fresh database (the API also migrates older ones)
docker-compose.yml
docs/                    screenshots

Plain-text passwords, no rate limiting, no tests, one API instance, in-process workers. The architecture notes end with the list of upgrades that would turn this into something real.