masaruk Logo

System Architecture Overview

High-level unified architectural overview of the entire MASARUK platform

Stack: Next.js (Web), Flutter (Mobile), Node.js (Backend), PostgreSQL (DB)

1. Purpose of This Document

This document provides a unified, high-level architectural overview of the entire MASARUK platform. It describes the system's logical layers, major components, data flows, and cross-platform behavior across:

  • B2C Web Platform (Next.js)
  • Mobile Apps (Flutter – Android & iOS)
  • Admin Panel (Web)
  • Provider Portal (Web B2B)
  • Unified REST API Layer (Node.js)
  • PostgreSQL Database
  • Third-party integrations (Payments, Maps, Notifications, SMS, Email)

This file serves as the top-level entry point for understanding the entire system architecture before diving into detailed component-level docs.

2. High-Level Architecture Layers

The MASARUK platform follows a modular, layered architecture consisting of:

Layer 1 — Presentation Layer (Client Apps)

  • Next.js Web (SSR/SSG/CSR hybrid)
  • Flutter Mobile App (Android & iOS)
  • Admin Panel (Web)
  • Provider Portal (Web)

Common responsibilities:

  • UI rendering
  • Form handling
  • Calling backend APIs
  • Localization (AR/EN)
  • Session & token management
  • Client-side caching (React Query / Flutter caching)

Layer 2 — API Gateway / RESTful Service Layer

Built with Node.js (TypeScript), providing:

  • Public endpoints (Trips, Bookings, Ratings…)
  • Authenticated endpoints (User, Bookings, Payments…)
  • Provider endpoints (Trips, buses, hotels, rest stops…)
  • Admin endpoints (Approvals, financials…)

Technical characteristics:

  • JWT authentication
  • Middleware for rate limiting & RBAC
  • API versioning: /api/v1/...
  • Validation using Zod schemas
  • Modular controllers following service → repository pattern

Layer 3 — Domain Logic Layer (Services & Policies)

This layer contains the actual business logic:

  • Booking validation rules
  • Payment processing rules
  • Refund & cancellation rules
  • Trip lifecycle management
  • Ad campaign lifecycle handling
  • Provider activation/approval logic
  • Financial settlement and payouts
  • Notifications triggering (email/SMS/push)
  • Rating flow rules

Every service follows:

  • Deterministic behavior
  • No UI assumptions
  • API-driven workflow

Layer 4 — Data Access Layer (Repositories)

All database operations flow through:

TripRepositoryBookingRepositoryPaymentTransactionRepositoryProviderRepositoryBusRepositoryHotelRepositoryRestStopRepositoryRatingRepositorySystemSettingsRepository

Repositories abstract raw SQL queries and enforce:

  • Consistent data schemas
  • Soft deletes
  • Optimized indexed queries
  • Transaction-safe operations

Layer 5 — Database Layer (PostgreSQL)

Uses:

  • Normalized relational schema
  • Strong foreign-key constraints
  • Auditing fields (created_by, updated_by)
  • Timestamps + soft delete
  • JSONB fields where appropriate (e.g., itinerary)

Core tables (representative, not full list):

usersproviderstripsbookingsbooking_passengerspayment_transactionshotelsbusesrest_stopsad_campaignsratings

3. External Integrations

Payments

Officially confirmed integrations only:

HyperPaySTC PayMADAApple Pay (iOS only)SADAD

Used for: Trip booking payments, Ad campaign payment flow, Refund handling (as supported)

Maps & Location

Google Maps for: Trip location display, Provider resources (hotels/buses/rest stops), Distance-based info

Notifications

  • Firebase Cloud Messaging (Push for mobile)
  • Email provider (transactional emails)
  • SMS provider (OTP / booking confirmations)

4. Deployment Architecture (High-Level)

Frontend Deployment

  • Next.js deployed on Vercel / Node hosting
  • Static assets globally cached
  • Web caching at CDN edge
  • Flutter app distributed via App Store / Play Store

Backend Deployment

  • Node.js deployed on Linux server (PM2 cluster)
  • BullMQ workers for queues
  • Redis for: Queues, Rate limiting, Caching

Database Deployment

  • PostgreSQL hosted on managed DB or self-hosted instance
  • Daily backups
  • PITR optional

5. Core Data Flows

Flow 1 — Trip Browsing (Web/Mobile)

  1. Client calls GET /api/v1/trips
  2. Backend fetches trips (available, active, not sold out)
  3. Returned with filters & metadata
  4. Client renders trip cards

Flow 2 — Booking Creation

  1. User submits passenger data
  2. Backend validates seat availability
  3. Payment initiated → Payment gateway
  4. On success: Booking created, Payment transaction recorded, Trip seats reduced, Confirmation notifications triggered

Flow 3 — Rating Flow

  1. Booking must be completed
  2. User receives push/email invitation
  3. User rates: Trip overall, Hotel, Bus, Driver, Rest stops
  4. Ratings stored and aggregated

Flow 4 — Provider Management

  1. Provider logs into B2B portal
  2. Manages: Trips, Hotels, Buses, Rest stops, Ad campaigns
  3. All changes propagate to B2C platform in real-time

6. Cross-Platform Consistency Requirements

  • Same trip fields across Web, Mobile, Admin, Provider
  • Same booking flow ordering
  • Same status mapping (Arabic ↔ Internal enum)
  • Same currency: SAR
  • Same terminology across all documentation
  • Same lifecycle transitions (booking, trip, payment...)

7. Security Architecture (High-Level)

  • Token-based authentication (JWT)
  • Role-based access control (RBAC)
  • Rate limiting for all public endpoints
  • Input validation at API boundary
  • Encrypted card data handled only by payment provider
  • HTTPS enforced everywhere
  • No sensitive data logged

8. Versioning Policy

  • We track the latest stable major version for security patches.
  • Exact patch version is verified during CI using: npm view next version.

Current documented version: Next.js 16.0.10 (Stable)

10. Summary

The MASARUK architecture is:

ModularLayeredAPI-drivenConsistent across all platformsSecureReady for scale

This document forms the foundation for understanding the platform before diving into backend, web, mobile, or data-specific architecture.