stable01-overview/high-level-system-map.md

High-Level System Map

Architectural overview of the MASARUK platform

1. Introduction

This document presents a high-level architectural overview of the entire MASARUK platform.

It describes all major subsystems, their responsibilities, and the flow of data between:

B2C Web Platform (Next.js 16)
Mobile Apps (Flutter)
Admin Panel (SPA)
Provider Portal (B2B resource management dashboard)
Unified REST API Layer (Node.js)
PostgreSQL Database
External Integrations (Payments, Maps, Notifications, SMS/Email)

2. System Components Overview

MASARUK consists of six primary layers, each with clear responsibilities:

2.1 B2C Web Platform (Next.js 16)

Target users: Travelers (end customers)

Browse trips and categories
Trip details & daily itinerary
Booking flow (select travelers → payment → confirmation)
My bookings
Trip rating flow
Authentication (signup / login / forgot password)
Multilingual (AR/EN)
SEO + SSR rendering

Communicates exclusively with REST API (HTTPS)

2.2 Mobile Apps (Flutter – Android & iOS)

Mirrors all B2C features + mobile-specific features:

Push notifications (Firebase)
Native mobile payments (Apple Pay on iOS)

2.3 Admin Panel (Super Admin / Internal Ops)

Internal management interface for MASARUK team.

Key modules:

Trip & program management
Booking management
Financial reporting
Providers management
Ads & Marketing Campaigns
System configuration

Access restricted by IP whitelist or VPN (recommended for production).

2.4 Provider Portal (B2B Tourism Companies)

Each licensed company manages:

Trips
Buses
Hotels
Rest Stops
Ad Campaigns
Bookings related to their trips

2.5 Unified REST API Layer (Node.js)

Core service powering every interface. Responsibilities:

Authentication (email / mobile / password)
Role & permission enforcement
CRUD operations for all domain entities
Booking workflows
Payment initiation & callback handling
Ratings & reviews
Data validation, Pagination, filtering, sorting

API is versioned: /api/v1/...

2.6 PostgreSQL Database

Fully normalized relational schema
Soft delete enabled in applicable entities
Audit tables for critical actions
Optimized indexes for Trips, Bookings, Payments, Provider data, Financial records
Uses snake_case for all field names

3. External Integrations

3.1 Payments

HyperPay
STC Pay
MADA
SADAD
Credit Cards (Visa/Mastercard)
Apple Pay (iOS only)

VAT: 15% standard, 20% for Ads (open question)

3.2 Maps

Google Maps Deep Links
Hotels locations
Rest stop locations
Trip map previews
Location input fields

3.3 Notifications

Firebase Cloud Messaging (FCM)
Booking confirmation
Payment status
Trip reminders
Rating requests
Email provider
SMS provider for OTP

4. High-Level Data Flow

4.1 B2C Web & Mobile → REST API

User → Web/Mobile UI → REST API → Database

Examples: Fetch trip list, Load trip details, Submit booking data, Execute payment, Submit ratings

4.2 Admin / Provider Panels → REST API

Admin/Provider UI → REST API → Database

Used for: Managing trips, Updating resources, Launching AdCampaigns, Viewing bookings, Financial reports

4.3 Payment Flow

Client (Web/Mobile)
   → API (init transaction)
      → Payment Gateway
         → Callback to API
            → Update Booking + PaymentTransaction

After callback: Booking is marked "مؤكدة" or "ملغاه", PaymentTransaction stored, Financial reports updated, Notifications sent

5. High-Level System Diagram

                ┌─────────────────┐ ┌──────────────┐ ┌───────────────┐
                │    B2C Web      │ │ Mobile Apps  │ │ Admin/Provider│
                │  (Next.js 16)   │ │  (Flutter)   │ │     (TBD)     │
                └─────────┬───────┘ └──────┬───────┘ └───────┬───────┘
                          │                │                 │
                          └────────────────┼─────────────────┘
                                           │ HTTPS REST
                                           ▼
                              ┌────────────────────────┐
                              │    REST API Layer      │
                              │      (Node.js)         │
                              └───────────┬────────────┘
                                          │
                              ┌───────────▼────────────┐
                              │    PostgreSQL DB       │
                              └────────────────────────┘

   External Services:
   ┌──────────────────────────────────────────────────────────┐
   │ Payments: HyperPay → MADA, STC Pay, Visa/MC, Apple Pay   │
   │ SMS: Provider TBD                                        │
   │ Email: Provider TBD                                      │
   │ Push: Firebase Cloud Messaging (assumed)                 │
   │ Maps: Google Maps or alternative TBD                     │
   └──────────────────────────────────────────────────────────┘

6. Cross-System Dependencies

Component	Depends On	Notes
B2C Web	REST API	Cannot function without API availability
Mobile Apps	REST API + Firebase	Requires API + Notifications
Provider Portal	REST API	CRUD operations & reporting
Admin Panel	REST API	Full management layer
Payment Flow	Payment Gateway APIs	Requires callback success
Ratings	Bookings module	User must have completed trip
Financial Reports	Bookings + Payments	Raw data from other modules