Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt
Use this file to discover all available pages before exploring further.
The Fleet domain is the operational foundation of KaroKar. It manages every vehicle in the platform — from initial registration through active use, scheduled maintenance, and suspension — while exposing a purpose-built availability engine that determines whether a vehicle can be booked or assigned during any requested period. A key architectural decision is that vehicle status and vehicle availability are deliberately separate concerns: a vehicle can be ACTIVE in its lifecycle while simultaneously being RESERVED or ALLOCATED on the availability timeline.
Vehicle Entity
Each vehicle is owned by exactly one organization and carries its current lifecycle status.
| Field | Type | Description |
|---|
id | uuid | Unique vehicle identifier (inherited from BaseEntity) |
organizationId | uuid | The owning organization (vendor or corporate) |
ownershipType | VehicleOwnershipType | VENDOR_OWNED or CORPORATE_OWNED |
make | string | Manufacturer name (e.g., Toyota) |
model | string | Model name (e.g., Corolla) |
year | number | Manufacturing year (1900–2100) |
licensePlate | string | Registered plate number |
status | VehicleStatus | Current lifecycle state of the vehicle |
createdAt | timestamptz | Record creation timestamp |
updatedAt | timestamptz | Last modification timestamp |
Ownership Types
KaroKar supports two ownership models, each with a distinct operational workflow.
VENDOR_OWNED
A vendor registers and owns the vehicle. Corporate organizations discover it via search and initiate a booking that requires explicit vendor approval before any employee can receive the vehicle.
Vendor Lists Vehicle
↓
Corporate Searches Vehicle
↓
Corporate Creates Booking Request
↓
Vendor Approves Booking
↓
Corporate Assigns Employee
↓
Employee Receives Vehicle
CORPORATE_OWNED
The corporate organization registers and owns the vehicle outright. There is no vendor, no booking approval step, and no marketplace negotiation — the vehicle moves directly into the assignment workflow.
Corporate Registers Vehicle
↓
Vehicle Added to Corporate Fleet
↓
Corporate Assigns Vehicle to Employee
↓
Employee Receives Vehicle
Corporate-owned vehicles bypass the Booking domain entirely. They enter the Assignment domain directly, skipping the REQUESTED → APPROVED approval cycle that vendor-owned vehicles must pass through.
Vehicle Statuses
The VehicleStatus enum represents the lifecycle state of a vehicle — not its scheduling availability.
| Status | Meaning |
|---|
PENDING | Vehicle registered but not yet reviewed or activated |
ACTIVE | Vehicle is operational and eligible for booking or assignment |
SUSPENDED | Vehicle has been suspended (see Suspension section) |
RETIRED | Vehicle has been permanently removed from the platform |
The Availability Engine
Core principle (ADR-003): Vehicle status ≠ Vehicle availability.
A vehicle with status ACTIVE may simultaneously be RESERVED for a future booking, ALLOCATED to a current employee, or blocked for MAINTENANCE next week. A single status field cannot represent these overlapping, time-based states — so KaroKar models availability as a first-class business domain using dedicated VehicleAvailability records.
The platform never asks “Is this vehicle available right now?” — it always asks “Is this vehicle available for the requested period?”
VehicleAvailability Entity
| Field | Type | Description |
|---|
id | uuid | Unique availability record identifier |
vehicleId | uuid | The vehicle this record applies to |
startDate | timestamptz | Start of the blocked period |
endDate | timestamptz | End of the blocked period |
sourceType | AvailabilitySourceType | What business event created this record |
sourceId | uuid | ID of the source entity (booking, assignment, etc.) |
status | AvailabilityStatus | The kind of unavailability |
createdAt | timestamptz | When the record was created |
Availability Statuses
| Status | Meaning |
|---|
RESERVED | Vehicle is reserved by an approved booking — not yet handed over |
ALLOCATED | Vehicle is actively allocated to an employee |
MAINTENANCE | Vehicle is scheduled for or undergoing maintenance |
SUSPENDED | Vehicle is suspended and hidden from search |
BLOCKED | Vehicle is manually blocked from use |
Availability Source Types
Each availability record is generated by a specific business event. The source type traces the record back to its origin:
| Source Type | Triggered By | Resulting Status |
|---|
BOOKING | Booking approved by vendor | RESERVED |
ASSIGNMENT | Employee assigned to a vehicle | ALLOCATED |
MAINTENANCE | Maintenance window scheduled | MAINTENANCE |
SUSPENSION | Vehicle suspension created | SUSPENDED |
MANUAL_BLOCK | Operational block applied by admin | BLOCKED |
Conflict Detection
AvailabilityService.detectConflict() performs date-range overlap validation before any new availability record is created. If an existing record overlaps the requested period, the request is rejected.
Example:
Reservation A: 01-Jul → 10-Jul ✅ Created
Reservation B: 05-Jul → 20-Jul ❌ Conflict — overlaps with Reservation A
AvailabilityService Methods
// Check whether a vehicle is free for a given period
checkAvailability(vehicleId: string, startDate: Date, endDate: Date): Promise<boolean>
// Create a new time-based availability block
createAvailabilityRecord(
vehicleId: string,
startDate: Date,
endDate: Date,
sourceType: AvailabilitySourceType,
sourceId: string,
): Promise<VehicleAvailability>
// Release a block when the source event completes or is cancelled
releaseAvailabilityRecord(sourceType: AvailabilitySourceType, sourceId: string): Promise<void>
// Explicitly check for overlapping records
detectConflict(vehicleId: string, startDate: Date, endDate: Date): Promise<boolean>
Vehicle Search
Search is availability-aware. VehicleService.searchAvailable() only returns vehicles that have no overlapping availability records for the requested period.
SearchVehiclesDto
class SearchVehiclesDto {
@IsUUID()
organizationId: string; // Filter to a specific organization's fleet
@IsDateString()
startDate: string; // ISO 8601 — start of requested period
@IsDateString()
endDate: string; // ISO 8601 — end of requested period
}
GET /vehicles/search?organizationId=org-uuid&startDate=2026-07-01&endDate=2026-07-31
RESERVED, ALLOCATED, MAINTENANCE, SUSPENDED, or BLOCKED records overlapping 01-Jul → 31-Jul will be returned.
Registering a Vehicle
CreateVehicleDto
class CreateVehicleDto {
@IsUUID()
organizationId: string; // Owning organization
@IsEnum(VehicleOwnershipType)
ownershipType: VehicleOwnershipType; // VENDOR_OWNED | CORPORATE_OWNED
@IsString()
make: string; // e.g., "Toyota"
@IsString()
model: string; // e.g., "Corolla"
@IsInt() @Min(1900) @Max(2100)
year: number; // e.g., 2023
@IsString()
licensePlate: string; // e.g., "KHI-123"
}
PENDING status. They must be explicitly activated via VehicleService.activateVehicle(id) before they appear in search results.
Maintenance Scheduling
Maintenance is modeled as a first-class record that automatically removes the vehicle from availability during the service window.
MaintenanceRecord Entity
| Field | Type | Description |
|---|
id | uuid | Unique record identifier |
vehicleId | uuid | The vehicle under maintenance |
startDate | timestamptz | Maintenance window start |
endDate | timestamptz | Maintenance window end |
reason | string | Human-readable description of the work |
status | MaintenanceStatus | Current state of this maintenance job |
Maintenance Statuses
| Status | Meaning |
|---|
SCHEDULED | Maintenance has been booked; vehicle is removed from search |
IN_PROGRESS | Maintenance is actively being performed |
COMPLETED | Maintenance finished; vehicle availability record released |
ScheduleMaintenanceDto
class ScheduleMaintenanceDto {
@IsDateString()
startDate: string; // ISO 8601
@IsDateString()
endDate: string; // ISO 8601
@IsString()
reason: string; // e.g., "Annual engine service"
}
sourceType: MAINTENANCE and status: MAINTENANCE is created, immediately blocking the vehicle for that window. Completing the maintenance record via MaintenanceService.completeMaintenance(id) releases the availability block.
Vehicle Suspension
Suspension represents a compliance or administrative hold that hides the vehicle from search and prevents new bookings.
VehicleSuspension Entity
| Field | Type | Description |
|---|
id | uuid | Unique suspension identifier |
vehicleId | uuid | The suspended vehicle |
reason | SuspensionReason | Enumerated reason for suspension |
startDate | timestamptz | When the suspension begins |
endDate | timestamptz | null | When it ends (null = indefinite) |
createdBy | uuid | User who created the suspension |
createdAt | timestamptz | Record creation timestamp |
Suspension Reasons
| Reason | Description |
|---|
INSURANCE_EXPIRED | Vehicle insurance has lapsed |
REGISTRATION_EXPIRED | Vehicle registration has expired |
FITNESS_CERTIFICATE_EXPIRED | Roadworthiness certificate has expired |
ADMIN_ACTION | Platform administrator has suspended the vehicle |
VENDOR_REQUEST | Vendor has requested the vehicle be suspended |
A suspended vehicle has its vehicle status set to SUSPENDED and a VehicleAvailability record created with sourceType: SUSPENSION and status: SUSPENDED. Both must be resolved to restore the vehicle to an operational state.
Suspension Availability Impact
Vehicle Suspended
↓
Availability Record Created (sourceType: SUSPENSION, status: SUSPENDED)
↓
Vehicle Hidden from Search
↓
New Bookings Blocked