Architecture Overview

MaxTracks Scanner is a Flutter mobile app (Android) used by warehouse staff for scanning packages, checking them in, capturing measurements, managing consolidations, and handling client pickups. It shares the same Firestore database as MaxTracks Web.

Technology Stack

Layer	Technology	Version
Framework	Flutter (Dart)	SDK >=3.4.3
State Management	GetX	4.6.6
Database	Cloud Firestore	5.0.1
Auth	Firebase Auth	5.1.0
Storage	Firebase Storage	12.1.0
Remote Config	Firebase Remote Config	5.1.3
Scanner	mobile_scanner	4.0.1
Audio	audioplayers	5.2.1
Font	Manrope	Custom

Project Structure

maxtracksapp/
├── lib/
│   ├── features/                  # Feature modules
│   │   ├── intro_page/           # Splash/landing screen
│   │   ├── registration/         # Login/authentication
│   │   ├── home/                 # Main dashboard + client pickup
│   │   ├── check_in/            # Check-in workflow (consolidation, items, charges)
│   │   └── package_details/     # Standard package receiving/unloading
│   ├── core/
│   │   ├── auth/                # Enhanced auth service, device tracking
│   │   ├── services/            # PackageCheck, Client, Logistic, Sound services
│   │   ├── global/              # Shared widgets, models, enums
│   │   ├── constant/            # App strings, colors, themes
│   │   └── themes/              # Material theme config
│   ├── routes/                   # GetX route definitions
│   ├── dependency_injection.dart  # Service registration
│   ├── main_production.dart       # Production entry point
│   └── main_development.dart      # Development entry point
├── android/                       # Android platform (min SDK 21)
├── assets/                        # JSON configs
├── images/                        # Logo, icons
├── lottie/                        # Animations
├── fonts/                         # Manrope font family
└── pubspec.yaml                   # Dependencies (version 1.4.7+1)

Firebase Integration

The scanner app connects to the same Firebase project as MaxTracks Web (max-inventory-scanner-b0b53).

Collections Read/Written

Collection	Read	Write	Purpose
Packages	Yes	Yes	Core package data, scan history, status updates
Clients	Yes	No	Client lookup and name matching
User	Yes	Yes	Authentication, device tracking, login state
UserLogs	No	Yes	Session login/logout tracking
UserAppVersion	No	Yes	Records app version per user
AppPermissions	Yes	No	Role-based permission checks
Items	Yes	No	Item catalog for check-in categorization
Categories	Yes	No	Item categories for check-in
Charges	Yes	No	Additional fee definitions

Firebase Storage

Path	Purpose
`json/packages.json`	Package metadata synced to local cache
Problem photos	Uploaded when damage/issues are reported

State Management (GetX)

The app uses GetX for state management, navigation, and dependency injection.

Controllers:

IntroPageController – splash screen, version check
RegistrationController – login, device validation
HomeController – dashboard, role switching, tab state
CheckInController – check-in form, consolidation logic
PackageDetailsController – package receiving form
ClientNameController – client search (shared across screens)
ProblemSectionController – damage reporting
SuggestionController – package search suggestions
ManualTrackingNumberController – manual barcode entry

Reactive state: RxString, RxBool, RxList<T>, Rx<T> observables with GetBuilder<T> widgets.

User Roles

Code	Role	Access
role[0]	Administrator	Full access
role[1]	Check In	Package check-in, consolidation, item assignment
role[2]	Container Unload	Package unloading, search by tracking/client
role[3]	Client Pickup	Tab-based pickup management, container filtering

Authentication Flow

User enters username + password on Registration page
App queries User collection for matching credentials
Validates single-device enforcement (one active device per user)
Writes session to UserLogs, records version to UserAppVersion
Stores session in SharedPreferences (userName, userID, userRole)
Navigates to Home based on role