Booking Management

Relevant source files

The following files were used as context for generating this wiki page:

• packages/db/src/schema/bookings.ts
• packages/db/src/seed.ts
• packages/db/drizzle/meta/0000_snapshot.json
• packages/db/drizzle/0000_normal_the_order.sql
• packages/shared/src/utils/index.ts
• apps/api/src/utils/helpers.ts

Booking Management is a core system within the Subito platform responsible for the lifecycle of service requests, ranging from initial creation to completion or cancellation. The system supports multiple booking types, including instant, scheduled, and recurring services, while managing complex relationships between users (customers), partners (service providers), hubs, and financial transactions.

The system ensures data integrity through idempotency tracking and maintains a detailed status history for every booking. It integrates with localized geography via Hubs and Micro-Hubs to manage capacity and scheduling slots efficiently.
Sources: packages/db/src/schema/bookings.ts:18-103, packages/db/src/seed.ts:634-754

Core Data Models

The booking system relies on a relational schema that connects customer requests to service catalogs and fulfillment partners.

Booking Structure

The bookings table serves as the primary entity, storing timing, pricing, and status information. Every booking is assigned a unique booking_number generated using a timestamp and random suffix.

Field	Type	Description
id	UUID	Unique identifier (Primary Key).
booking_number	VARCHAR(50)	Human-readable identifier (e.g., BK240611ABC123).
status	ENUM	Current state (e.g., PENDING_PAYMENT, MATCHED).
booking_type	ENUM	INSTANT, SCHEDULED, or RECURRING.
subtotal	DECIMAL	Base price before discounts and taxes.
final_amount	DECIMAL	Total amount payable by the user.

Sources: packages/db/src/schema/bookings.ts:36-103, apps/api/src/utils/helpers.ts:3-11

Relationships

The following ER diagram illustrates the primary entities involved in the booking lifecycle.

Diagram shows the relationship between the core bookings table and its associated metadata and actor tables.
Sources: packages/db/src/schema/bookings.ts:208-235, packages/db/drizzle/meta/0000_snapshot.json:1159-1311

Booking Lifecycle and Status Flow

The system tracks the progression of a booking through a series of defined states. Transitions are recorded in the booking_status_history table for auditing and reporting.

Status Transitions

A typical booking flow proceeds from payment to completion:

Flow diagram of the standard booking state machine.
Sources: packages/db/src/schema/bookings.ts:18-27, packages/db/src/seed.ts:771-815

Cancellation Logic

Cancellations can be triggered by users, partners, or system failures (e.g., NO_PARTNERS_FOUND). If a partner has already been matched, the system may require a partner acknowledgment via cancellation_awaiting_partner_ack before releasing the booking.
Sources: packages/db/src/schema/bookings.ts:29-37, packages/db/src/schema/bookings.ts:92-95

Scheduling and Capacity

Scheduling is managed through a combination of Hub configurations and discrete time slots.

Booking Slots

The booking_slots table defines the availability for specific Micro-Hubs on given dates.

• Capacity: Each slot has a max_capacity and current_bookings counter.
• Surge Pricing: Slots can define a surge_multiplier based on demand, which is applied to the booking's surge_amount.
  Sources: packages/db/src/schema/bookings.ts:188-201, packages/shared/src/utils/index.ts:3-10

Recurring Bookings

Recurring services are configured via recurring_bookings, which act as a template for generating booking_instances.

• Types: Supported frequencies include WEEKLY, BIWEEKLY, and MONTHLY.
• Instances: Each instance tracks its own status (e.g., SCHEDULED, SKIPPED) while referencing the parent_booking_id.
  Sources: packages/db/src/schema/bookings.ts:153-186, packages/db/drizzle/0000_normal_the_order.sql:328-348

Partner Matching

The system calculates a "Match Score" to determine the best partner for a booking. This logic incorporates partner ratings, historical performance, and proximity.

// Scoring formula derived from shared utilities
export function calculatePartnerMatchScore(input: {
  averageRating: string | null
  completedBookings: number | null
  distanceKm: number
}): number {
  const rating = input.averageRating ? parseFloat(input.averageRating) : 3
  const completed = input.completedBookings || 0
  const distanceScore = Math.max(0, 10 - input.distanceKm)
  return rating * 2 + Math.min(completed / 10, 3) + distanceScore * 0.5
}

Sources: packages/shared/src/utils/index.ts:40-50

Safety and Reliability

Idempotency

To prevent duplicate bookings or payments, the system employs an idempotency_keys table. It tracks the request_hash and stores the response_body for a given key and userId. This ensures that retried network requests do not result in multiple resource creations.
Sources: packages/db/src/schema/bookings.ts:110-129

Financial Calculations

Pricing involves calculating subtotals, GST (default 18%), and applying discounts.

• GST Calculation: roundToTwoDecimals(amount * rate)
• Decimals: All currency values are stored as numeric(12, 2) or decimal to ensure precision.
  Sources: packages/shared/src/utils/index.ts:5-10, apps/api/src/utils/helpers.ts:97-103

Summary

The Booking Management system provides a robust framework for handling service commerce. By decoupling the booking template (bookings) from specific instances (booking_instances) and utilizing a centralized capacity management system (booking_slots), the platform can scale from simple one-time tasks to complex recurring service schedules. Reliability is reinforced through idempotency tracking and a rigorous status history audit trail.
Sources: packages/db/src/schema/bookings.ts:1-250