masaruk Logo

Mobile Architecture – Flutter

Flutter mobile application architecture for Android & iOS (Single Codebase)

1. Purpose of This Document

This document defines the architectural structure, design decisions, and mobile-specific development conventions for the MASARUK mobile application. The Flutter codebase must remain fully aligned with:

  • Backend REST API
  • Web (Next.js)
  • Provider Portal
  • Admin Panel
  • Shared domain model
  • UI/UX guidelines

The mobile app is the primary interface for travellers (B2C), and must reflect the booking flows, trip details, rating flows, and user dashboards analyzed from the raw UI screens.

2. Core Architectural Principles

2.1 Single Codebase for Android & iOS

  • 100% shared Dart code
  • Platform channels used only when required (payments, notifications)

2.2 Clean Architecture Approach

  • lib/presentation/ → UI (Widgets, Screens, State)
  • lib/domain/ → Entities, Models, Use-cases
  • lib/data/ → API clients, DTOs, Repositories

This ensures:

  • Separation of concerns
  • Testability
  • Predictability
  • Consistency with other MASARUK subsystems

2.3 Reactive State Management

Preferred state manager: Riverpod (recommended). Alternative allowed: Bloc.

  • UI screens must remain 'dumb'
  • Business logic lives in providers / blocs
  • Events & state transitions must match backend lifecycles

4. Navigation Architecture

4.1 Navigation Type

Use GoRouter for structured, deep-linkable routes.

4.2 Core Routes

ScreenPath
Splash/
Welcome/welcome
Login/auth/login
Signup/auth/signup
Home/home
Trip List/trips
Trip Details/trips/:id
Booking Flow/booking/:tripId
My Bookings/bookings
Booking Details/bookings/:id
Rating/ratings/new
Profile/profile

6. Authentication

  1. User logs in via /auth/login
  2. Token stored in FlutterSecureStorage
  3. Token passed in all authenticated API calls
  4. On logout, clear token + navigate to /welcome

7. Localization (AR/EN)

  • Flutter intl or easy_localization package
  • RTL handled via Directionality widget
  • AR/EN JSON files in assets/locales/
  • User preference stored locally

8. Push Notifications

  • Firebase Cloud Messaging (FCM)
  • Foreground + Background handling
  • Deep links to specific screens (booking, trip details)
  • Notification permission requested on first launch

9. Payment Integration

  • HyperPay SDK or WebView-based payment flow
  • Apple Pay (iOS only)
  • STC Pay via deep link
  • Payment confirmation via callback + polling

12. Summary

The MASARUK Mobile App is:

Flutter single-codebase (Android + iOS)Clean ArchitectureState managed via Riverpod/BlocFully localized (AR/EN + RTL)API-driven via isolated clientsPayment-readyDeep-link enabledReady for scale