System Requirements

Functional Requirements:

• Allow users to browse and search available rooms by time slot, capacity, location, and equipment.
• Enable users to create, update, and cancel room bookings.
• Temporarily hold a room for a user (e.g., 10 minutes) while they complete the booking details.
• Prevent double-booking of rooms by ensuring concurrent booking attempts are serialized.
• Send asynchronous notifications (email/push) for booking confirmations, updates, cancellations, and pre-meeting reminders.
• Support role-based access control (RBAC): users book rooms; admins manage inventory.

Non-Functional Requirements:

• Strong Consistency (ACID): This is the paramount requirement. The system must guarantee that a double booking is mathematically impossible.
• High Availability: The read path (searching for rooms) must remain highly available and performant, especially during morning spikes when employees plan their day.
• Low Latency: Room search queries should execute in < 200ms.
• Fault Tolerance: If the notification system goes down, it should not prevent users from successfully booking rooms.

API Design

We use a two-step booking process to support the "10-minute hold" UX requirement, keeping the APIs strictly RESTful.

1. Search Available Rooms GET /v1/rooms?start_time=2026-03-02T14:00:00Z&end_time=2026-03-02T15:00:00Z&capacity=10&equipment=projector Returns a list of rooms that do not have any overlapping CONFIRMED or PENDING bookings for the requested time.

2. Reserve a Room (Initiate 10-Minute Hold) POST /v1/bookings/reserve

JSON

Returns: 201 Created with a bookingId and a status of PENDING.

3. Confirm the Booking POST /v1/bookings/{booking_id}/confirm

JSON

Returns: 200 OK with the status updated to CONFIRMED.

4. Cancel a Booking DELETE /v1/bookings/{booking_id}

High-Level Design

• Client: Web or mobile application.
• API Gateway: Handles rate limiting, authentication, and routes requests.
• Booking Service: The core backend application (e.g., a Spring Boot service) that handles the business logic, state transitions, and database interactions.
• Primary Database (PostgreSQL): The single source of truth. Handles concurrency control natively via constraints.
• Message Broker (Kafka / RabbitMQ): Decouples the core booking flow from external dependencies like email servers.
• Notification Service: Consumes events from the broker and interfaces with third-party providers (SendGrid, APNs) to send messages.
• Scheduler / Background Worker: A lightweight cron job or background thread that runs periodically to clean up expired reservations and trigger meeting reminders.

Detailed Component Design

1. Concurrency Control (Preventing Double Bookings) Instead of relying on application-level locks or distributed Redis TTLs, we push the concurrency logic down to the database using PostgreSQL Exclusion Constraints.

When the Booking Service attempts to insert a new reservation, PostgreSQL evaluates the proposed time range against existing records for that specific roomId. If another transaction is currently committing an overlapping time block, PostgreSQL serializes the requests. The winner gets the row inserted; the loser receives a constraint violation error, which the API translates to an HTTP 409 Conflict ("Room is no longer available").

2. The Reservation State Machine (The 10-Minute Hold) The system manages inventory availability through states rather than physical locks:

• State 1: PENDING. When the /reserve API is called, a row is inserted with status = 'PENDING' and an expiresAt timestamp set to NOW() + 10 minutes. Because the row exists in the DB, the Exclusion Constraint prevents anyone else from booking this slot.
• State 2: CONFIRMED. When the /confirm API is called, the system verifies expiresAt > NOW(). If valid, it updates the status to CONFIRMED and clears the expiresAt field.
• State 3: EXPIRED (Cleanup). A background worker runs every minute executing: DELETE FROM Bookings WHERE status = 'PENDING' AND expiresAt < NOW(). This instantly frees up abandoned holds.

3. Asynchronous Notifications To ensure the Booking Service remains fast, it does not send emails directly. Upon a successful transaction commit for a CONFIRMED booking, the service publishes a BookingConfirmedEvent to a message broker. The Notification Service consumes this event, constructs the email template, and sends it. If the email provider is down, the broker retains the message, ensuring eventual delivery without failing the user's booking request.