Booking Lifecycle Engine

Relevant source files

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

• backend/src/domain/entities/Booking.ts
• backend/src/application/use-cases/booking/CreateBookingUseCase.ts
• backend/src/interfaces/controllers/BookingController.ts
• backend/src/application/use-cases/booking/UpdateBookingUseCase.ts
• backend/src/application/use-cases/booking/CancelBookingUseCase.ts
• backend/src/infrastructure/database/repositories/BookingRepository.ts
• backend/src/infrastructure/database/prisma/schema.prisma
• backend/src/application/dtos/BookingDto.ts

The Booking Lifecycle Engine manages the complete state transitions and operational logic for cleaning service appointments. It handles the creation, scheduling, cleaner assignment, modification, and cancellation of bookings while integrating AI-driven insights for pricing and resource allocation.

This engine coordinates between the persistence layer, AI services for optimization, and external payment processors to ensure a consistent state throughout the service delivery process.

Architecture and Data Flow

The engine follows a layered architecture. The BookingController receives HTTP requests and validates them using Zod schemas. The logic resides in specific Use Case classes which interact with the Booking domain entity and the BookingRepository.

Booking Creation Flow

When a user initiates a booking, the system validates the input, calculates dynamic pricing, and attempts to find a recommended cleaner via the smart scheduling logic.

Domain Model

The Booking entity represents the core data structure. It includes properties for scheduling, location, pricing, and AI-generated metadata.

Booking States

The engine enforces specific statuses to track the lifecycle of a service:

• PENDING: Initial state before cleaner assignment.
• ASSIGNED: A cleaner is matched to the booking.
• CONFIRMED: Booking is finalized.
• IN_PROGRESS: Service is currently being performed.
• COMPLETED: Service is finished.
• CANCELLED: Service is terminated before completion.

Sources: backend/src/domain/entities/Booking.ts:7-22, backend/src/infrastructure/database/prisma/schema.prisma:34-41

Data Structure Table

Field	Type	Description
id	UUID	Unique identifier for the booking
userId	UUID	Reference to the customer who booked
cleanerId	UUID (Optional)	Reference to the assigned cleaner
timeSlot	Object	Contains start and end Date objects
amount	Decimal	Total cost of the service
status	Enum	Current lifecycle state
aiMetadata	JSON	Pricing and scheduling optimization data

Sources: backend/src/domain/entities/Booking.ts:7-22, backend/src/infrastructure/database/prisma/schema.prisma:84-106

Operational Logic

Scheduling and Rescheduling

The UpdateBookingUseCase allows modification of an existing booking. If the schedule is updated, both start and end times must be provided simultaneously to ensure validity. The domain entity calculates durationMinutes automatically upon schedule updates.

// From backend/src/domain/entities/Booking.ts
updateSchedule(start: Date, end: Date): void {
  this.timeSlot = new TimeSlot(start, end);
  this.durationMinutes = this.timeSlot.durationInMinutes();
  this.touch();
}

Sources: backend/src/domain/entities/Booking.ts:71-75, backend/src/application/use-cases/booking/UpdateBookingUseCase.ts:14-20

Cancellation Policy

Cancellations are managed by the CancelBookingUseCase. The system prevents cancellation if a booking is already in the COMPLETED state. A reason for cancellation is required and stored within the aiMetadata field.

API Endpoints

The BookingController exposes endpoints for managing the lifecycle, protected by authentication middleware.

Method	Endpoint	Use Case	Description
GET	/api/v1/bookings	GetBookingsUseCase	Lists bookings for user or all for admins
POST	/api/v1/bookings	CreateBookingUseCase	Creates a new booking with AI pricing
PATCH	/api/v1/bookings/:id	UpdateBookingUseCase	Updates schedule or notes
POST	/api/v1/bookings/:id/cancel	CancelBookingUseCase	Terminates a booking with a reason

Sources: backend/src/interfaces/http/routes/booking.routes.ts:5-13, backend/src/interfaces/controllers/BookingController.ts:31-64

Summary

The Booking Lifecycle Engine provides a robust framework for managing cleaning services. By centralizing logic in use cases and enforcing state transitions within the Booking domain entity, it ensures data integrity. The integration with the BookingRepository via Prisma facilitates efficient persistence and conflict detection for cleaner schedules.

Sources: backend/src/infrastructure/database/repositories/BookingRepository.ts:33-52, backend/src/application/use-cases/booking/GetBookingsUseCase.ts:6-12