Entities & Relationships
Domain Entities & Relationships
1. Purpose
This document defines all core domain entities extracted strictly from the UI/UX analysis of:
B2C Mobile App
B2C Web
Admin Panel
Provider Portal
Booking Flow
Payment Flow
Ratings
Trip Details
Buses / Hotels / Rest Stops
Financial Reports
Ad Campaigns
Arabic Labels
Arabic labels from UI are preserved exactly as they appear.
2. Entity List Overview
Core Customer-facing Entities
UserالمستخدمBookingالحجزBookingPassengerبيانات المسافرTripالرحلةTripItineraryDayالبرنامج اليوميRatingالتقييم
Provider Resource Entities
Providerشركة السياحةBusالباصHotelالفندقRestStopالاستراحةAdCampaignالحملة الإعلانية
Financial Entities
PaymentTransactionمعاملة الدفعFinancialRecordالسجل المالي
System Entities
NotificationالإشعارSystemSettingإعدادات النظامAdminUserمستخدم الإدارةMediaAssetالوسائط
3. Entities & Their Descriptions
3.1 User
Represents a B2C customer who books trips.
| Field | Arabic UI Label | Notes |
|---|---|---|
| id | — | Primary key |
| full_name | الاسم بالكامل | As seen in signup/login |
| البريد الالكتروني | Required in auth | |
| mobile | رقم الجوال | Used in booking & rating |
| password_hash | — | bcrypt/argon2 hash |
| profile_image | — | Optional |
| created_at | — | — |
Relationships:has_many Bookings, has_many Ratings
Appears In:إنشاء حساب، تسجيل الدخول، حجوزاتي، تأكيد الحجز، تقييم الرحلة
3.2 Trip
The main product entity representing a travel program.
| Field | Arabic UI Label | Notes |
|---|---|---|
| id | — | Primary key |
| name | اسم البرنامج | From Admin/Provider trip creation |
| destination | — | e.g., مكة المكرمة |
| price_per_person | — | "ابتداءً من" |
| old_price | — | Strikethrough price |
| trip_type | نوع الرحلة | (سياحية / عمرة) |
| start_date | — | — |
| end_date | — | — |
| duration_days | — | Derived |
| duration_nights | — | Derived |
| description | — | Long text |
| services_included | ما يشمله السعر | Array of boolean flags |
| images | — | MediaAsset[] |
| status | الحالة | فعّالة / غير فعّالة |
Relationships:belongs_to Provider, has_one Hotel, has_one Bus, has_many RestStops, has_many TripItineraryDay, has_many Bookings
3.4 Booking
A confirmed or pending reservation for a Trip.
| Field | Arabic UI Label | Notes |
|---|---|---|
| id | رقم الحجز | Shown everywhere |
| user_id | — | FK |
| trip_id | اسم الرحلة | FK |
| total_amount | السعر | Sum after VAT |
| payment_status | حالة الدفع | مكتمل / ملغاه / قيد التنفيذ |
| booking_status | الحالة | مؤكدة / ملغاه / قيد التنفيذ / مكتملة / قادمة |
| booking_date | تاريخ الحجز | — |
| travel_date | تاريخ الرحلة | — |
| passengers_count | عدد المسافرين | — |
Note
UI shows
مؤكدة (feminine form). Internal enum is CONFIRMED. See statuses-and-lifecycles.md for canonical mappings.3.8 Bus
As managed in "قائمة الباصات".
| Field | Arabic UI Label | Notes |
|---|---|---|
| id | — | PK |
| provider_id | — | FK |
| plate_number | رقم اللوحة | — |
| model | موديل الباص | "سكانيا 2021" |
| seats | سعة المقاعد | — |
| status | الحالة | نشطة / غير نشطة / تحت الصيانة |
| services | الخدمات المتوفرة | واي فاي، حمام، تكييف… |
| driver_name | اسم السائق | Embedded |
| driver_mobile | رقم الجوال | Embedded |
| driver_photo | صورة السائق | — |
| bus_photo | صورة الباص | — |
3.7 Provider
Represents a tourism company using the B2B portal.
| Field | Arabic UI Label | Notes |
|---|---|---|
| id | — | PK |
| name | اسم الشركة | — |
| logo | — | Image |
| cr_number | — | Commercial registration |
| city | — | — |
| contact_name | اسم المسؤول | — |
| contact_mobile | رقم الجوال | — |
| contact_email | البريد الالكتروني | — |
Relationships:has_many Trips, Buses, Hotels, RestStops, AdCampaigns
3.12 PaymentTransaction
Records payments for bookings and campaigns.
| Field | Arabic UI Label | Notes |
|---|---|---|
| id | — | PK |
| booking_id | — | Nullable for AdCampaign |
| reference_number | رقم المعاملة | — |
| amount | المبلغ الإجمالي | — |
| vat_percent | ضريبة | 15% or 20% |
| payment_method | طريقة الدفع | Mada/STC Pay/Apple Pay |
| status | حالة الدفع | مكتمل / ملغاه / قيد التنفيذ |
| paid_at | تاريخ الدفع | — |
4. High-Level ER Relationships
User ───< Booking ───< BookingPassenger │ │ │ └─── PaymentTransaction ───< FinancialRecord │ └──< Rating >── Booking Provider ───< Trip ───< TripItineraryDay │ │ │ │ │ └──< RestStop (many-to-many per direction) │ └─── Bus │ Hotel │ └──< Bus / Hotel / RestStop / AdCampaign Trip ───< Booking >── User Trip ───< AdCampaign >── Provider
5. Cross-Module Dependencies
| Entity | Depends On | Depended By |
|---|---|---|
| Booking | User, Trip | Rating, PaymentTransaction |
| Trip | Provider | Booking, Rating, AdCampaign |
| RestStop | Provider | Trip (details) |
| Hotel | Provider | Trip (details) |
| Bus | Provider | Trip |
| PaymentTransaction | Booking / AdCampaign | FinancialRecord |
| Rating | Booking | — |
6. Data Types & Constraints Reference
6.1 Standard Field Types
| Field Pattern | PostgreSQL Type | Constraints |
|---|---|---|
| id | BIGSERIAL | PRIMARY KEY |
| *_id (foreign keys) | BIGINT | NOT NULL, REFERENCES |
| VARCHAR(255) | UNIQUE where applicable | |
| mobile | VARCHAR(20) | Format: 05xxxxxxxx |
| national_id | VARCHAR(10) | 10 digits |
| name, title | VARCHAR(255) | NOT NULL |
| description, notes | TEXT | NULLABLE |
| price, amount | DECIMAL(12,2) | NOT NULL, CHECK >= 0 |
| percentage | DECIMAL(5,2) | CHECK BETWEEN 0 AND 100 |
| status | VARCHAR(50) | NOT NULL, CHECK in enum |
| *_date, *_at | TIMESTAMPTZ | — |
| is_* (booleans) | BOOLEAN | DEFAULT false |
| services | JSONB | Array of service flags |
6.2 Standard Audit Fields
| Field | Type | Notes |
|---|---|---|
| created_at | TIMESTAMPTZ | DEFAULT NOW() |
| updated_at | TIMESTAMPTZ | Trigger on update |
| deleted_at | TIMESTAMPTZ | Soft delete (nullable) |
| created_by | BIGINT | User/Admin who created |
| updated_by | BIGINT | User/Admin who updated |