MASARUK – Master Platform Definition

01-overview/master-platform-definition.md

High-level central definition of MASARUK platform: vision, identity, functional domains, core subsystems, and main lifecycles.

1. Vision and Product Identity

1.1 Vision Statement

MASARUK – Your Easiest Path to Travel

A unified Saudi travel platform designed to simplify, modernize, and enhance the experience of booking tours, Umrah programs, and domestic trips — across web, mobile apps, and provider and admin dashboards.

MASARUK aims to deliver:

Seamless booking experience
Trusted and verified providers
Transparent pricing
Smooth digital payments (MADA / Apple Pay / STC Pay)
High-quality, organized trip information
Unified experience across all platforms (web + mobile)

The platform integrates B2C, B2B, and admin systems into a cohesive digital tourism infrastructure.

2. Core Problem MASARUK Solves

Traditional Problems:

✗Fragmented booking channels
✗Manual communication with providers
✗Lack of standardized trip information
✗Inconsistent pricing and unclear refund rules
✗No digital booking records
✗Customer service delays and errors
✗Difficulty verifying provider credibility

MASARUK Solutions:

✓Centralized verified marketplace
✓Automated booking + digital records
✓Standardized trip definitions (program, schedule, stops, hotel, bus...)
✓Clear payment rules (taxes, refunds, partial refunds)
✓Automated trip lifecycle
✓Provider-level resource management
✓Admin-level financial auditing

3. Platform Structure (End-to-End)

MASARUK consists of four main subsystems, supported by a unified backend and shared infrastructure.

13.1 B2C Web Platform (Next.js)

Target users: End customers (travelers)

Homepage and DiscoveryTrip ListTrip DetailsBooking FlowPayment FlowMy BookingsRating FlowsUser ProfileAuthentication

23.2 Mobile Apps (Flutter – Android & iOS)

Equivalent to B2C web, with mobile-oriented interaction

Mobile-specific capabilities:

Push notifications (Firebase)
Native mobile payments (e.g., Apple Pay on iOS, via gateway integration)

33.3 Provider Portal (B2B)

Used by licensed tourism companies (service providers)

Trip ManagementHotel ManagementBus ManagementRest Stop ManagementAd Campaign ManagementRelated Bookings ManagementFinancial Reports View

43.4 Super Admin Panel

Used internally by MASARUK team

Provider Approval/VerificationTrip SupervisionBooking SupervisionFinancial DashboardsRefund ApprovalSystem ConfigurationUser and Role Management

4. Unified Domain Model (High-Level Summary)

The platform operates on a unified set of core entities (official names):

Entity	Description	Main Lifecycle
User	End customer (B2C traveler)	Account (Active/Suspended/Deleted)
Provider	Licensed tourism company	Approval (PENDING_APPROVAL → APPROVED → SUSPENDED)
Trip	Travel package/program	Trip (ACTIVE → COMPLETED/CANCELLED)
Booking	Customer booking	Booking (PENDING → CONFIRMED → COMPLETED/CANCELLED)
BookingPassenger	Individual traveler in booking	N/A (follows Booking)
Hotel	Accommodation resource	Resource (ACTIVE/INACTIVE)
Bus	Transportation resource	Resource (ACTIVE/INACTIVE/UNDER_MAINTENANCE)
RestStop	Rest stop resource	Resource (ACTIVE/INACTIVE)
AdCampaign	Marketing campaign	Campaign (SCHEDULED → ACTIVE → ENDED/PAUSED)
Rating	Customer review	N/A (immutable after creation)
PaymentTransaction	Gateway payment record	Payment (PENDING → COMPLETED/FAILED → REFUNDED)
FinancialRecord	Provider settlement record	Settlement (IN_CURRENT_BALANCE → TRANSFERRED/REFUNDED)
Notification	System/user notification	Notification (UNREAD → READ)
SystemSetting	Platform configuration	N/A (key-value store)
AdminUser	Internal admin/operator	Account (Active/Suspended)
MediaAsset	Images/files for trips/resources	N/A (referenced from other entities)

Info

Official detailed definitions and relationships are specified in:

03-domain-model/domain-entities-and-relationships.md
03-domain-model/statuses-and-lifecycles.md
03-domain-model/business-rules-and-policies.md

5. Trip Lifecycle – Master Definition

The trip lifecycle is the backbone of all MASARUK logic

Conceptually, trips pass through these states in the system:

ActiveInactiveCancelledCompletedScheduled

Key events affecting trip lifecycle:

•Provider toggles trip visibility (e.g., activates/deactivates a trip)
•Admin overrides status (e.g., cancels a trip)
•Trip end date expires → System infers trip is **completed/ended**
•Provider or admin cancels trip → Bookings may trigger refund flows

6. Booking Lifecycle – Master Definition

The booking lifecycle is standard across all channels

PendingConfirmedCancelledCompletedUpcoming

Key events:

•Successful payment callback from gateway → Internal booking status moves from `PENDING` to `CONFIRMED`
•Trip end date expires → Booking is treated as `COMPLETED` (may show as completed in UI)
•Trip start/future dates → Booking may display in UI as upcoming
•Manual cancellation (user or admin, according to refund policy) → Booking becomes `CANCELLED`

7. Payment and Financial Lifecycles – Master Definition

Payments and financial records in MASARUK operate on two interrelated but distinct lifecycles

7.1 PaymentTransaction Lifecycle (Gateway)

Each online payment is processed through configured gateways:

• HyperPay (Mada / Visa / Mastercard)
• Apple Pay (iOS, via gateway)
• STC Pay
• SADAD (where applicable)

Conceptual payment states (gateway/transaction level):

InitiatedPending / AuthorizedCaptured / CompletedFailedRefunded

7.2 FinancialRecord Lifecycle (Settlement)

Financial settlement between MASARUK and providers uses a separate lifecycle:

In Current BalanceAmount due to provider but not yet transferred

TransferredAmount has been disbursed to provider

RefundedAmount has been refunded to customer (per policy)

10. Cross-Platform Experience Consistency

MASARUK enforces strict UX consistency rules across web, mobile, provider, and admin.

10.1 Naming Consistency (Arabic UI)

UI terms (Arabic) are preserved exactly as they appear:

ملغاهمكتملةقيد التنفيذفعالة / غير فعالةنشطة / غير نشطة

10.2 Currency

Always: Saudi Riyal – SAR in external UI

10.3 Trip Details Tab Order

1. Trip Overview2. Details3. Daily Program

10.4 Booking Flow Order

1. Trip Details→2. Traveler Info→3. Payment→4. Confirmation

10.5 Navigation Patterns

• Provider portal uses sidebar navigation
• Admin panel uses expanded sidebar + role-based view
• Mobile apps use bottom navigation and in-flow navigation patterns

14. Platform Principles

Scalability

Multi-provider marketplace and growing catalog

Security

JWT, RBAC, rate limiting, secure payment integrations

Monitoring

Structured logs, monitoring, and error tracking

Saudi-First Compliance

MADA support, Arabic UI, and Saudi VAT rules

UX Consistency

Unified flows and naming across web and mobile

Modular Expansion

Ability to add new trip types or related domains in future phases

Warning

Assumptions and Open Questions:

VAT Discrepancy: 15% appears in booking flows, 20% in ad campaigns
Currency Format Discrepancy: Some mockups show $ instead of SAR
Rest Stop vs Hotel Activation Labels: Buses use Active/Inactive/Under Maintenance, Hotels and Rest Stops use Active/Inactive (فعالة/غير فعالة)
Trip Duration Calculation: Assumed duration is entered manually, not auto-calculated
Social Login Behavior: Requires clarification on which social providers are in scope