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 Group | B2C Web | Mobile Apps | Provider Portal | Admin Panel | Backend API |
|---|---|---|---|---|---|
| B2C Travelers | ✅ | ✅ | ❌ | ❌ | Indirect |
| Tourism Providers | ❌ | ❌ | ✅ | ❌ | Indirect |
| Super Admin / Platform Ops | ❌ | ❌ | ✅ (View) | ✅ | Indirect |
| Finance / Accounting | ❌ | ❌ | ✅ | ✅ | Indirect |
| Customer Support | ❌ | ❌ | ✅ | ✅ | Indirect |
| Development / QA / Product / AI | ✅ | ✅ | ✅ | ✅ | Direct |
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
10-future-and-open-questions/future-expansion-and-roadmap.md4. 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
| Gateway | Use Case | Integration Type |
|---|---|---|
| HyperPay | Mada, Visa, Mastercard, Apple Pay | Server-to-server + redirect |
| STC Pay | STC Pay mobile payment | Server-to-server |
| SADAD | Bill payments | Server-to-server |
7.2 Messaging Services (TBD)
| Service Type | Use Case |
|---|---|
| SMS | Booking confirmations, OTP, trip reminders |
| Receipts, marketing, password reset | |
| Push | Real-time notifications (mobile + web) |
7.3 Location & Maps (TBD)
| Service | Use Case |
|---|---|
| Maps API | Display hotel/rest stop location, distance calculation |
| Places API | Address auto-completion (optional) |
8. Persona to RBAC Role Mapping
| Persona | RBAC Role(s) | Permissions Summary |
|---|---|---|
| T1, T2, T3 (B2C Travelers) | CUSTOMER / END_USER | Book, pay, rate, manage bookings |
| P1 (Tourism Company Owner) | PROVIDER_ADMIN | Full access to provider portal |
| P2 (Operations Coordinator) | PROVIDER_STAFF | Trip/resource management, no finance |
| P3 (Marketing Specialist) | PROVIDER_MARKETING | Ad campaigns, budget management |
| A1 (Super Admin) | SUPER_ADMIN | Full platform authority |
| A2 (Finance Employee) | FINANCE_ADMIN | Financial reports, settlements, refunds |
| A3 (Support Agent) | SUPPORT_ADMIN | Bookings, messaging, view-only finance |
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.