Booking Lifecycle: States, Transitions, and Termination

Bookings are the primary revenue-generating business process in KaroKar. Every vendor-owned vehicle transaction flows through a formal booking lifecycle that governs who can act, what actions are permitted, and when availability is reserved or released. The lifecycle is enforced by an explicit state machine inside BookingService — ensuring that every transition is intentional, validated, and accompanied by a domain event that downstream domains can react to.

Booking state transitions must only occur through BookingService methods. Never update booking.status directly from controllers, scheduled jobs, event listeners, or any code outside the service layer. Direct status mutations bypass transition validation, skip domain event emission, and break availability synchronization.

Booking Entity

Field	Type	Description
`id`	`uuid`	Unique booking identifier (from `BaseEntity`)
`vehicleId`	`uuid`	The vehicle being booked
`vendorOrganizationId`	`uuid`	The vendor who owns the vehicle
`corporateOrganizationId`	`uuid`	The corporate organization making the booking
`requestedBy`	`uuid`	User ID of the corporate employee who created the request
`startDate`	`timestamptz`	Requested booking period start
`endDate`	`timestamptz`	Requested booking period end
`status`	`BookingStatus`	Current state in the booking lifecycle
`createdAt`	`timestamptz`	Record creation timestamp
`updatedAt`	`timestamptz`	Last modification timestamp

Booking States

KaroKar defines nine booking states covering the full lifecycle from initial drafting to final resolution.

State	Description
`DRAFT`	Booking created but not yet submitted to the vendor
`REQUESTED`	Booking submitted; awaiting vendor decision
`APPROVED`	Vendor accepted the booking; vehicle reserved
`REJECTED`	Vendor declined the booking; terminal state
`ASSIGNED`	An employee has been assigned to the approved booking
`ACTIVE`	Vehicle has been handed over to the employee
`COMPLETED`	Vehicle returned; booking reached its planned conclusion
`TERMINATED`	Booking ended prematurely after becoming operational
`CANCELLED`	Booking cancelled before vehicle handover

State Transition Table

Transitions are strictly enforced by the ALLOWED_TRANSITIONS map in BookingService. Attempting an invalid transition throws a DomainException with code INVALID_BOOKING_TRANSITION.

Current State	Allowed Next States
`DRAFT`	`REQUESTED`
`REQUESTED`	`APPROVED`, `REJECTED`, `CANCELLED`
`APPROVED`	`ASSIGNED`, `CANCELLED`
`ASSIGNED`	`ACTIVE`, `CANCELLED`
`ACTIVE`	`COMPLETED`, `TERMINATED`
`COMPLETED`	(terminal — no further transitions)
`TERMINATED`	(terminal — no further transitions)
`REJECTED`	(terminal — no further transitions)
`CANCELLED`	(terminal — no further transitions)

Vendor-Owned Vehicle Booking Workflow

The following walkthrough covers the complete journey for a vendor-owned vehicle from the corporate organization’s perspective.

Create a Draft

A corporate user selects a vehicle and desired dates. A POST /bookings call with CreateBookingDto creates the booking in DRAFT status. No availability record is created yet — the vehicle remains searchable by others.

// CreateBookingDto
{
  vehicleId: "uuid",
  vendorOrganizationId: "uuid",
  corporateOrganizationId: "uuid",
  requestedBy: "uuid",
  startDate: "2026-07-01T00:00:00Z",
  endDate: "2026-07-31T23:59:59Z"
}

Submit the Request

BookingService.submitRequest(id) transitions the booking from DRAFT → REQUESTED and emits BookingRequestedEvent. The vendor is notified. Still no availability block is created — the vendor may reject.

Vendor Approves

The vendor calls BookingService.approveBooking(id, dto), transitioning the booking to APPROVED. A BookingApprovedEvent is emitted.Availability impact: The Availability domain listens to booking.approved and creates a VehicleAvailability record:

sourceType: BOOKING
status:     RESERVED
startDate:  booking.startDate
endDate:    booking.endDate

The vehicle is now blocked from overlapping bookings.

Assign an Employee

The corporate admin calls BookingService.assignEmployee(id, employeeId), transitioning the booking to ASSIGNED and emitting BookingAssignedEvent.Availability impact: The RESERVED availability record transitions to ALLOCATED.Assignment domain impact: The Assignment domain listens to booking.assigned and creates an Assignment record linking the booking to the employee.

Activate the Booking

When the employee physically receives the vehicle, BookingService.activateBooking(id) transitions the booking to ACTIVE and emits BookingActivatedEvent. This marks the start of operational usage.

Complete or Terminate

Planned completion: BookingService.completeBooking(id) → COMPLETED. Availability released; vehicle returns to searchable pool.
Early termination: BookingService.terminateBooking(id, dto) → TERMINATED. A BookingTermination record is persisted. Availability released (unless a maintenance block is required, e.g., after ACCIDENT or VEHICLE_BREAKDOWN).

CANCELLED vs TERMINATED

These two terminal states are explicitly distinct and must not be confused.

CANCELLED

The booking was cancelled before the vehicle was ever handed over to an employee. The vehicle was never actively used under this booking.Valid from: REQUESTED, APPROVED, ASSIGNEDAvailability is released if a RESERVED record existed (i.e., if cancelled from APPROVED or ASSIGNED).

TERMINATED

The booking became operational (reached ACTIVE) but ended before its planned endDate. The vehicle was handed over and in active use.Valid from: ACTIVE onlyA BookingTermination record is always created. Certain termination reasons (e.g., ACCIDENT, VEHICLE_BREAKDOWN) may additionally trigger a maintenance block.

BookingTermination Record

When a booking is terminated, a separate BookingTermination entity is persisted to record the operational details of the early closure.

Field	Type	Description
`id`	`uuid`	Unique termination record identifier
`bookingId`	`uuid`	The booking that was terminated
`reason`	`TerminationReason`	Enumerated reason for termination
`terminatedBy`	`uuid`	User ID who performed the termination
`terminatedAt`	`timestamptz`	Exact timestamp of termination
`notes`	`string \| null`	Optional free-text notes

`TerminateBookingDto`

class TerminateBookingDto {
  @IsEnum(TerminationReason)
  reason: TerminationReason;   // Required — must be a valid enum value

  @IsUUID()
  terminatedBy: string;        // Required — ID of the user terminating the booking

  @IsOptional()
  @IsString()
  notes?: string;              // Optional — additional context
}

Termination Reasons

Reason	Description
`VEHICLE_BREAKDOWN`	Vehicle became inoperable during the booking period
`ACCIDENT`	Vehicle was involved in an accident
`VENDOR_RECALL`	Vendor recalled the vehicle
`CORPORATE_RECALL`	Corporate organization recalled the vehicle
`EMPLOYEE_EXIT`	Assigned employee left the organization
`COMPLIANCE_VIOLATION`	A compliance rule was breached
`INSURANCE_EXPIRED`	Vehicle insurance lapsed during the booking
`ADMIN_ACTION`	Platform administrator forced termination
`OTHER`	Any other reason not covered above

New termination reasons can be added to the TerminationReason enum in future phases without changing the state machine or booking lifecycle logic.

Domain Events

Every state transition emits a domain event via EventEmitter2. Downstream domains subscribe to these events without being coupled to the Booking domain.

Event	Emitted On	Key Consumers
`BookingRequestedEvent`	`DRAFT → REQUESTED`	Notifications, Audit, Admin Dashboard
`BookingApprovedEvent`	`REQUESTED → APPROVED`	Availability Domain, Notifications, Audit
`BookingRejectedEvent`	`REQUESTED → REJECTED`	Notifications, Audit
`BookingAssignedEvent`	`APPROVED → ASSIGNED`	Assignment Domain, Notifications, Audit
`BookingActivatedEvent`	`ASSIGNED → ACTIVE`	Fleet Operations, Analytics, Audit
`BookingCompletedEvent`	`ACTIVE → COMPLETED`	Availability Domain, Analytics, Audit
`BookingTerminatedEvent`	`ACTIVE → TERMINATED`	Availability Domain, Assignment Domain, Notifications, Audit
`BookingCancelledEvent`	`* → CANCELLED`	Availability Domain, Notifications, Audit

Availability Integration

The Booking domain never directly modifies availability records — it emits events and the Availability domain reacts.

Booking Transition	Availability Effect
`REQUESTED`	No change — vehicle stays available
`APPROVED`	`RESERVED` availability record created for the booking period
`ASSIGNED`	Availability status transitions `RESERVED → ALLOCATED`
`COMPLETED`	Availability record released; vehicle re-enters searchable pool
`CANCELLED` (from `APPROVED`/`ASSIGNED`)	`RESERVED` / `ALLOCATED` record released
`TERMINATED`	Availability record released (maintenance block may be added separately)

Assignment Integration

A booking and its assigned employee are not directly linked. The correct model is:

Booking → Assignment → Employee

This separation — enforced by emitting BookingAssignedEvent which the Assignment domain consumes — enables future reassignments, temporary allocations, and pool vehicle scenarios without modifying booking logic. See the Assignments guide for full details.

Get Started

Core Concepts

Domain Guides

Configuration

Booking Lifecycle: States, Transitions, and Termination

Booking Entity

Booking States

State Transition Table

Vendor-Owned Vehicle Booking Workflow

CANCELLED vs TERMINATED

CANCELLED

TERMINATED

BookingTermination Record

`TerminateBookingDto`

Termination Reasons

Domain Events

Availability Integration

Assignment Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Domain Guides

Configuration

Documentation Index

​Booking Entity

​Booking States

​State Transition Table

​Vendor-Owned Vehicle Booking Workflow

​CANCELLED vs TERMINATED

CANCELLED

TERMINATED

​BookingTermination Record

​TerminateBookingDto

​Termination Reasons

​Domain Events

​Availability Integration

​Assignment Integration

Build docs developers (and LLMs) love

Booking Entity

Booking States

State Transition Table

Vendor-Owned Vehicle Booking Workflow

CANCELLED vs TERMINATED

BookingTermination Record

`TerminateBookingDto`

Termination Reasons

Domain Events

Availability Integration

Assignment Integration