masaruk Logo

Stakeholders & Personas

Definition of stakeholders and core personas of the MASARUK platform

1. Purpose of This Document

This document defines the stakeholders and core personas of the MASARUK platform.

It clarifies:

  • Who uses the system (directly and indirectly)
  • What each persona wants to achieve
  • Which subsystems, flows, and features are most important for each persona

All subsequent documents (requirements, UX flows, API design, RBAC, data model) must remain aligned with these personas.

2. Stakeholder Groups (High-Level)

1. B2C Travelers (End Users)

Individuals who browse trips, book, pay, rate, and manage their bookings.

2. Tourism Providers (B2B Partners)

Licensed Saudi tourism companies that publish and operate trips through the platform.

3. Platform Administration (Super Admin & Operations)

Owners, supervisors, finance, and support teams who manage the overall ecosystem.

4. Technical & Delivery Teams

Developers, QA, DevOps, product managers, and AI agents who build and operate the platform.

5. External Service Providers (Systems, not people)

Payment gateways, messaging providers, and map services (used indirectly through backend).

2.2 Stakeholder vs Subsystem Matrix (Overview)

Stakeholder GroupB2C WebMobile AppsProvider PortalAdmin PanelBackend API
B2C TravelersIndirect
Tourism ProvidersIndirect
Super Admin / Platform Ops✅ (View)Indirect
Finance / AccountingIndirect
Customer SupportIndirect
Development / QA / Product / AIDirect

3. B2C Personas (Travelers)

These personas represent the end users who interact with B2C Web (Next.js) and mobile apps (Flutter).

3.1 Persona T1 – Saudi Family Traveler Focused on Umrah

Profile:

  • Saudi resident
  • Books Umrah trips for themselves and family
  • Not necessarily very tech-savvy but comfortable with apps and WhatsApp

Goals:

  • Find reliable and organized Umrah programs
  • See hotel details, bus type, rest stops, and daily schedule clearly
  • Book for multiple travelers (family members) in one booking
  • Pay securely using local methods (MADA, STC Pay, SADAD, Apple Pay)
  • Receive clear confirmation and digital receipt
  • Manage upcoming and past trips via "My Bookings"
  • Rate the trip and its components after completion

Pain Points / Risks:

  • Confusion about total price (per person vs total)
  • Trust in provider and logistics
  • Clarity of cancellation policy and refund amounts

3.2 Persona T2 – Local Leisure Traveler (Experiences & Tourism)

Profile:

  • Resident in Saudi Arabia
  • Interested in local tours (e.g., AlUla, Santorini-style trips, beaches, mountains)
  • Often compares multiple trips and prices before booking

Goals:

  • Discover inspiring trips ("trips to unforgettable places")
  • Filter by type (tourism) and location
  • See offers (old price vs new)
  • Understand what's included and what's not
  • Book quickly, preferably with minimal form filling

Pain Points / Risks:

  • Misinterpretation of pricing currency (SAR vs $)
  • Unclear difference between offers and regular pricing
  • Text overload; prefers visual and icon-based summaries

3.3 Persona T3 – Frequent / Expert Traveler

Profile:

  • Books multiple trips annually (Umrah + tourism)
  • More sensitive to operational reliability and post-trip support

Goals:

  • Quick search and filtering
  • Clear history in "My Bookings"
  • Reliable refund processing in case of cancellation
  • Transparent ratings to evaluate providers

Pain Points / Risks:

  • Inconsistent status naming between web and app and communication
  • Confusing or delayed refunds
Info
Guest browsing behavior and accessibility requirements are documented as future considerations in 10-future-and-open-questions/future-expansion-and-roadmap.md

4. B2B Personas (Tourism Providers)

These personas use the Provider Portal (tourism companies / service providers dashboard) on the web.

4.1 Persona P1 – Tourism Company Owner/Manager

Role:

Business owner or general manager.

Goals:

  • List and promote their trips on MASARUK
  • Increase bookings and revenue
  • Monitor high-level KPIs
  • Manage profile and legal status as a licensed provider

Key Touchpoints:

  • Provider dashboard with KPIs
  • Trip management (add/edit trips)
  • Hotels / Buses / Rest Stops management
  • Bookings management
  • Financial reports (for their company)

4.2 Persona P2 – Operations & Bookings Coordinator (within Provider)

Role:

Employee handling daily operations.

Goals:

  • Keep trip catalogs up to date
  • Assign hotels, buses, drivers, and rest stops to trips
  • Track bookings and ensure capacity is not exceeded
  • Respond to customer inquiries

Pain Points:

  • Typos in critical fields (dates, prices, seat count)
  • Misconfigured cancellation rules vs expectations
  • Misunderstanding how ratings reflect on their assets

4.3 Persona P3 – Marketing Specialist (within Provider)

Role:

Marketer responsible for promotion.

Goals:

  • Run ad campaigns for specific trips
  • Control budgets for "Ad Management"
  • Monitor campaign performance (spent vs budget)

Pain Points:

  • Campaign status mismatch vs spending
  • Incorrect tax setup for ad payments (20% vs 15% discrepancy)

5. Platform Administration Personas

These personas use the Super Admin Panel + may view or access some provider data.

5.1 Persona A1 – Super Admin / Platform Owner

Role:

Business owner or highest-level manager of MASARUK.

Goals:

  • Full visibility across the platform (all providers, trips, bookings, finance)
  • Control active providers
  • Ensure compliance with Saudi tourism regulations
  • Set fees and commission structures and policies

Key Touchpoints:

  • Super admin dashboard (KPIs, charts)
  • Global trip, booking, user management
  • Global financial reports (platform-level)
  • Tax and commission settings and status assignment

5.2 Persona A2 – Finance & Settlement Employee

Role:

Finance/accounting employee for MASARUK.

Goals:

  • Track all transactions from bookings and ad campaigns
  • Calculate commissions (platform commission)
  • Manage settlements with providers
  • Ensure tax accuracy (VAT 15%)

Pain Points:

  • Inconsistent tax rate between modules
  • Duplicate transaction IDs in test data
  • Currency discrepancy between dashboards and apps

5.3 Persona A3 – Customer Support & Operations Agent

Role:

Support team member handling customer issues.

Goals:

  • Quick booking search by booking number or customer name or phone
  • View complete booking details
  • Send messages to customers from within the system
  • Support cancellations and clarify cancellation policy

Pain Points:

  • Lack of direct "Cancel Booking" action in UI
  • Mismatch between what app displays vs internal statuses

6. Technical & Delivery Personas

These personas are internal but must be considered in analysis, especially for API, data model, and DevOps.

6.1 Backend Engineer (Node.js / API)

Needs: Clear entities, enumerated statuses with mappings, explicit business rules, error handling specs.

6.2 Frontend Web Engineer (Next.js + Tailwind)

Needs: Field definitions for each screen, clear patterns for forms and tables, UX states.

6.3 Mobile Engineer (Flutter)

Needs: Same domain contracts as web and admin, explicit mapping from APIs to UI screens.

6.4 QA Engineer / Tester

Needs: Detailed use cases, status and error case enumeration, mapping between labels and codes.

6.5 Product Owner / Analyst / AI Agents

Needs: Clear scope boundaries, cross-referencing, documented open questions.

7. External Systems (Non-Human Stakeholders)

These are not "personas" but must be treated as stakeholders in architecture and API design.

7.1 Payment Gateways

GatewayUse CaseIntegration Type
HyperPayMada, Visa, Mastercard, Apple PayServer-to-server + redirect
STC PaySTC Pay mobile paymentServer-to-server
SADADBill paymentsServer-to-server

7.2 Messaging Services (TBD)

Service TypeUse Case
SMSBooking confirmations, OTP, trip reminders
EmailReceipts, marketing, password reset
PushReal-time notifications (mobile + web)
Info
Specific provider choice (Taqnyat, Unifonic, SendGrid, FCM, etc.) requires confirmation.

7.3 Location & Maps (TBD)

ServiceUse Case
Maps APIDisplay hotel/rest stop location, distance calculation
Places APIAddress auto-completion (optional)

8. Persona to RBAC Role Mapping

PersonaRBAC Role(s)Permissions Summary
T1, T2, T3 (B2C Travelers)CUSTOMER / END_USERBook, pay, rate, manage bookings
P1 (Tourism Company Owner)PROVIDER_ADMINFull access to provider portal
P2 (Operations Coordinator)PROVIDER_STAFFTrip/resource management, no finance
P3 (Marketing Specialist)PROVIDER_MARKETINGAd campaigns, budget management
A1 (Super Admin)SUPER_ADMINFull platform authority
A2 (Finance Employee)FINANCE_ADMINFinancial reports, settlements, refunds
A3 (Support Agent)SUPPORT_ADMINBookings, messaging, view-only finance
Info
Guest browsing and accessibility personas are documented as future considerations.

9. Open Questions

  • Guest browsing flow: Does the platform allow browsing trips without authentication?
  • Accessibility: What level of WCAG compliance is required for MVP?
  • Provider staff permissions: Are sub-roles (marketing, operations) required for MVP?

See 09-quality-and-operations/open-questions-and-assumptions.md for the full list.