Product Identity & Scope
MASARUK (مسارك) – Core identity, vision, and functional scope
1. Purpose of This Document
This document defines the core identity, vision, and functional scope of the MASARUK platform.
It provides a consolidated, high-level view of the product as a whole, ensuring that all subsequent analysis modules (domain model, functional spec, APIs, UX, QA, operations) remain aligned with the platform's intended purpose.
This file is the root reference for understanding what MASARUK is, who it serves, and what parts compose it.
2. Product Identity
2.1 Official Branding
Name (Arabic)
مسارك
Name (English)
MASARUK
Slogan (Arabic)
مسارك – أسهل طريق لرحلتك
Slogan (English)
MASARUK – Your Easiest Path to Travel
Sector
Travel & Tourism (Saudi Arabia)
2.2 Brand Positioning
MASARUK is defined as a Saudi integrated travel ecosystem combining:
- A customer-facing (B2C) booking and discovery platform.
- A partner-facing (B2B) management portal for licensed tourism companies.
- A centralized admin control panel for full supervision.
- Unified backend API layer.
- Mobile apps and website as equal-priority delivery channels.
2.3 Platform Vision
To become the most reliable, user-friendly, and comprehensive travel booking platform in the Kingdom, providing:
- Verified trips from approved providers.
- Transparent logistics: hotels, buses, rest stops, schedules.
- Smooth booking and payment flow.
- Real-time communication and accurate financial handling.
- High-quality, trustworthy user experience.
2.4 Value Proposition
| Value | Description |
|---|---|
| One-stop travel booking | Browse trips → View details → Book → Pay → Track → Rate |
| Verified providers | Only licensed tourism companies |
| Transparent logistics | Real hotels, buses, drivers, itineraries, rest stops |
| Unified rating system | Ratings for trip, hotel, bus, driver, rest stops |
| Reliable payments | HyperPay + STC Pay + MADA + Apple Pay + SADAD |
| Arabic-first UX | Designed for Saudi users with full RTL support |
| Multi-company marketplace | Users choose from various verified providers |
3. Platform Scope
MASARUK consists of 4 major subsystems + cross-cutting backend infrastructure.
3.1 Subsystem A — B2C Platform
Users
Travelers in Saudi Arabia
Technology
Next.js 16 (Web) + Flutter (Mobile)
Purpose: Allow customers to explore, book, pay for, and track trips.
| Capability | Description | Related Entities |
|---|---|---|
| Browse trips | Filter by category (سياحية / عمرة), search, sort | Trip, Provider |
| View trip details | Overview, hotel, bus, itinerary, rest stops, pricing | Trip, Hotel, Bus, RestStop |
| Booking flow | Enter traveler data → payment → confirmation | Booking, BookingPassenger, PaymentTransaction |
| Payment processing | HyperPay, STC Pay, MADA, Apple Pay, SADAD | PaymentTransaction |
| Booking cancellation | Cancel upcoming bookings with refund calculation | Booking, FinancialRecord |
| My Bookings (حجوزاتي) | View قادمة / مكتملة / ملغاه bookings | Booking |
| Trip rating | Overall + detailed rating (hotel, bus, driver, rest stops) | Rating |
| User authentication | Signup, login, social login (Google/Facebook), forgot password | User |
| Notifications | Payment confirmations, trip reminders, rating requests | Notification |
3.2 Subsystem B — Tourism Providers Portal (B2B)
Users
Licensed Saudi Tourism Companies
Technology
Web dashboard (SPA)
Purpose: Allow providers to manage their own trips, resources, and bookings.
| Capability | Description | Related Entities |
|---|---|---|
| Dashboard (لوحة المعلومات) | KPIs, charts, provider-level stats | — |
| Trip management | Add, edit, duplicate, delete, publish/unpublish trips | Trip |
| Hotels management | Add, edit, delete hotels used in trips | Hotel |
| Buses management | Add, edit, delete buses and drivers | Bus, Driver |
| Rest stops management | Add, edit, delete rest stops | RestStop |
| Bookings management | View, filter, export bookings for their trips | Booking, BookingPassenger |
| Ad campaigns | Create, fund, track ad campaigns | AdCampaign, AdCampaignPayment |
| Financial reports | View settlement reports, VAT, commission | FinancialRecord |
| Ratings overview | See ratings received for their trips and resources | Rating |
| Company profile | Update company info, logo, license documents | Provider |
3.3 Subsystem C — Admin Panel (Internal)
Users
Super Admin, Finance Admin, Support Admin
Technology
Web dashboard (SPA)
Purpose: Full supervision and platform-level control.
| Capability | Description | Related Entities |
|---|---|---|
| Super Dashboard | Platform-wide KPIs: total bookings, trips, revenue | — |
| Trip management | View, edit, delete any trip from any provider | Trip |
| Booking management | View, filter, export all bookings | Booking |
| User management | View, suspend, delete B2C users | User |
| Provider management | Approve, suspend, delete providers | Provider |
| Ad campaigns (platform-level) | View all campaigns, approve/reject | AdCampaign |
| Financial reports | Global VAT, commissions, settlements | FinancialRecord |
| Ratings moderation | View, hide, flag abusive ratings | Rating |
| System settings | Tax rates, commission %, statuses config | — |
| Notifications management | Send global or targeted push/SMS/email | Notification |
3.4 Subsystem D — Unified Backend API
Technology
Node.js + TypeScript + PostgreSQL (Prisma)
Purpose: The single source of truth for all clients (Web, Mobile, Admin, Provider).
| Capability | Description |
|---|---|
| Authentication | JWT-based auth, refresh tokens, password reset |
| Authorization | Role-based access control (RBAC), permission matrix |
| CRUD for all entities | Trips, Hotels, Buses, Bookings, Payments, Ratings, ... |
| Booking workflow | Create, confirm, cancel, rate |
| Payment processing | Gateway callbacks, transaction recording |
| Notification dispatch | Push, SMS, Email triggers |
| Reporting | Aggregated stats for dashboards and exports |
| API versioning | /api/v1/... for backward compatibility |
4. Out of Scope (Phase 1)
- Flight booking or integration with airline APIs.
- Multi-country operations (focus is Saudi Arabia only).
- Car rental as standalone service.
- Complex loyalty / rewards programs.
- Real-time GPS tracking of buses (may be considered post-MVP).
- Multi-language beyond AR/EN.
5. Success Criteria
| Metric | Target | Measurement |
|---|---|---|
| User registration | 10,000+ users in first 6 months | Database count |
| Booking completion rate | > 75% | Booked / Started checkout |
| Payment success rate | > 95% | Successful / Attempted payments |
| Provider onboarding | 30+ licensed companies | Active providers count |
| Rating submission rate | > 40% | Trips rated / Completed trips |
| System uptime | > 99.5% | Monitoring tools |
| Mobile app rating | > 4.3 stars | App Store / Play Store |
6. References
01-overview/master-platform-definition.md→ Detailed breakdown of each subsystem03-domain-model/domain-entities-and-relationships.md→ Full entity catalog04-functional-spec/*.md→ Module-level functional specifications05-ux-and-flows/*.md→ UX flows and UI inventory06-api-and-integrations/*.md→ API documentation07-architecture/*.md→ Technical architecture details