analysis/04-functional-spec/buses-module.md
Buses List
Buses Module – Functional Specification
1. Purpose
The Buses Module manages all bus-related operations for tourism providers. A Bus is a core logistical resource used in trips for transportation between cities or within itinerary days.
This module covers:
- Creating and maintaining bus records
- Assigning drivers
- Defining facilities (WiFi, Charger, etc.)
- Managing operational status (Active, Inactive, Maintenance)
- Integrating buses into trip creation and itineraries
2. Involved Entities
| Entity | Description |
|---|---|
| Bus | A transportation vehicle owned/managed by a provider. |
| Driver | Driver information stored inside the bus record. |
| Trip | Trips reference a bus via transportation metadata. |
| Provider | Owner of the bus. |
Note: No standalone "Driver" entity exists in the UI; driver data is embedded inside Bus.
4. Bus Entity Fields
| Field | Type | Notes |
|---|---|---|
| id | PK | — |
| provider_id | FK | Bus owner |
| plate_number | String | Plate Number |
| model | String | Bus Model (Manufacturer + Year) |
| seats_capacity | Integer | Seats Capacity |
| status | Enum | active / inactive / maintenance |
| driver_name | String | Driver Name |
| driver_phone | String | Driver Phone Number |
| driver_photo_url | String | Driver Photo |
| bus_photo_url | String | Bus Photo |
| created_at | timestamp | — |
| updated_at | timestamp | — |
5. Facilities & Amenities
Missing facility simply means "false" in the database.
6. Statuses
| UI Label | Enum | Meaning |
|---|---|---|
| Active (نشطة) | ACTIVE | Bus available for assignment |
| Inactive (غير نشطة) | INACTIVE | Hidden / not assignable |
| Under Maintenance (تحت الصيانة) | MAINTENANCE | Temporarily unavailable |
7. Business Rules
BR-1. Bus must belong to a provider
Every bus is tied to a single provider (no shared buses across providers).
BR-2. Only active buses can be assigned to trips
If status != ACTIVE, bus cannot appear in trip creation list.
BR-3. Driver fields are mandatory
Because UI requires: Driver Name, Phone Number, Driver Photo
BR-4. Facilities checkboxes represent true/false values
Each facility is stored as a boolean field.
BR-5. Cannot delete a bus linked to future trips
Trips referencing the bus prevent deletion.
Error: Cannot delete this bus as it is linked to active trips
BR-6. Bus status MAINTENANCE blocks booking
Trips using a bus under maintenance are marked with warnings.
BR-7. Image requirements
Bus image and driver image must support PNG, JPG, GIF up to 10MB.
8. State Transitions
INACTIVE → ACTIVE (Provider activates bus) ACTIVE → INACTIVE (Provider deactivates bus) ACTIVE → MAINTENANCE (Provider sets bus for maintenance) MAINTENANCE → ACTIVE (Maintenance completed)