FuelVantage | Fuel Station Rewards React Native App

FuelVantage — Fuel Station Rewards, Forecourt Mobile POS & Multi-Branch Management Ecosystem

FuelVantage is a complete, enterprise-grade turnkey digital fuel loyalty, forecourt attendant mobile POS, and multi-branch franchise management ecosystem. Engineered specifically for gas station networks, oil company franchises, convenience retail chains, and EV charging hubs, FuelVantage unifies a high-converting Customer Loyalty Mobile App, a rugged in-lane Forecourt Staff Attendant Mobile POS, an executive Super Admin Command Center Mobile App, and a real-time Node.js / Express / TypeScript Backend Engine with MongoDB ACID transactions, Socket.io WebSockets, and Firebase Cloud Messaging.

Built with React Native, the latest Expo SDK, and TailwindCSS / NativeWind. Every operational parameter, dynamic fuel grade price (Regular 87, Diesel Ultra, Premium 93, EV kWh), multi-tier VIP multiplier (Bronze 1.0x, Silver 1.25x, Gold 1.5x, Platinum 2.0x), currency symbol placement, loyalty calculation mode (Points, Stamps, or Hybrid), and station dispenser pump bay is 100% dynamically manageable in real-time via the Super Admin portal and WebSocket push with zero app recompilation.

⭐ Key Highlights & Commercial USPs

• 60-Second Dynamic Anti-Fraud QR Member Pass: Rolling AES-256 HMAC cryptographic nonces cycle automatically every 60 seconds with an animated countdown ring, completely eliminating screenshot sharing and loyalty pass fraud.
• ⛽ Rugged In-Lane Forecourt Staff POS App (@staffapp): Handheld mobile POS for forecourt attendants featuring hardware camera QR decoding in under 100ms, dispenser volume calculations, voucher redemption terminal, tender settlement (Cash, Card, Fleet, Points), and end-of-shift Z-Reports.
• ️ $0-Cost Leaflet Forecourt Map (Zero Google Maps Billing): High-performance interactive OpenStreetMap & CartoDB Voyager vector map layer integrated via React Native WebView with branded station pins, GPS distance calculations, and 1-tap Apple/Google Maps deep linking — saving operators $200+/month in Google Maps API bills.
• Super Admin Command Center App (@adminapp): Franchise executives manage multi-branch station locations, configure dispenser pump bays (Pumps #1 to #16+), update live fuel prices across branches with WebSocket push, view interactive trend charts powered by react-native-gifted-charts, manage attendant shifts, and execute customer loyalty adjustments with mandatory audit remarks.
• High-Converting Customer Loyalty App (@customerapp): Frictionless passwordless 6-digit OTP onboarding, categorized rewards catalog, digital thermal voucher wallet with vector barcodes, viral Refer & Earn growth loop, and itemized PDF fueling receipt export via expo-print and expo-sharing.

• ⚡ Real-Time WebSocket Synchronization (Socket.io): Instant fuel price board broadcasts across all mobile screens, live forecourt transaction feeds for administrators, and sub-second push notifications when points are earned at the dispenser pump.
• ️ MongoDB Multi-Document ACID Transactions: All wallet balance updates, points accruals, and voucher redemptions utilize atomic session.withTransaction() write locks to prevent race conditions and double-spending.
• ✉️ Dynamic Database-Driven Nodemailer SMTP: Live SMTP credentials and dynamic HTML email templates stored directly in MongoDB with automated token interpolation ({{userName}}, {{otpCode}}, {{points}}, {{liters}}, {{fuelType}}) and support for Gmail 16-Digit App Passwords, Brevo, SendGrid, and cPanel webmail.

Live Demo & Pre-Seeded Test Credentials

Deploy and test all 4 nodes of the FuelVantage ecosystem immediately with the pre-seeded credentials:

• Super Admin Mobile App (Android APK Demo): Download Admin Demo APK (Google Drive)
• ⛽ Staff Attendant Mobile POS App (Android APK Demo): Download Staff POS Demo APK (Google Drive)
• Customer Loyalty Mobile App (Android APK Demo): Download Customer App Demo APK (Google Drive)
• Super Admin Command App Credentials: Email: admin@stationrewards.com | Password: 12345678
• ⛽ Staff Attendant POS App Credentials: Email: staff@stationrewards.com | Password: 12345678 (Central Downtown Branch)
• Customer Loyalty Mobile App Credentials: Email: customer@stationrewards.com | Password: 12345678 (Also supports passwordless 6-digit OTP verification)

⚠️ External Services & Upfront Cost Disclosures

TRANSPARENCY NOTICE TO BUYERS: FuelVantage is architected with a cost-minimization philosophy, utilizing free-tier services and zero-paid map layers. You own your deployment 100% with zero monthly royalties or transaction commission cuts:

• ️ OpenStreetMap & CartoDB Maps ($0 / Month Forever): Unlike competing apps that require Google Maps API keys with steep pay-per-request monthly bills ($200+ surprises), FuelVantage uses a free, high-speed vector Leaflet WebView layer.
• MongoDB Atlas Database (Free Sandbox with Paid Tiers): Includes a permanent free M0 Sandbox cluster (512MB storage) with automated backups, ideal for development and testing. Production deployments with hundreds of thousands of transactions can upgrade to dedicated M10+ tiers.
• Firebase Cloud Messaging (FCM) (100% Free on Spark Plan): Firebase Cloud Messaging and Expo Notifications provide unlimited free transactional push notifications on the standard Firebase Spark plan with zero per-message fees.
• ☁️ Cloudinary Media Storage (Free 25GB Tier): Used for hosting reward catalog images, station branch photos, and attendant profile avatars with 25GB free monthly bandwidth.
• ✉️ Nodemailer SMTP Mailer (Free Options): Works with free Google App Passwords, Brevo (300 free emails/day), Mailgun, SendGrid, Amazon SES, or custom station webmail.
• Cloud Hosting ($0 – $10 / Month): The Node.js & Express backend can be hosted for free or low-cost on Render.com, Railway.app, Heroku, or any $5/month Ubuntu VPS (DigitalOcean, Linode, AWS Lightsail).

Complete Codebase Architecture & Included Modules

1. Customer Loyalty Mobile App (customerapp/)

• Passwordless OTP Onboarding: Frictionless sign up and login via email OTP with welcome bonus points and referral attribution.
• Dynamic 60s Member QR Pass: Fullscreen glowing QR pass with animated circular timer cycling AES-256 encrypted nonces every 60 seconds.
• Interactive Forecourt Station Locator: Leaflet vector map with live dispenser pump availability, current fuel rates per liter, and 1-tap navigation deep-linking.
• Forecourt Rewards Catalog: Categorized rewards (Fuel Discounts, Car Wash, Coffee, C-Store) with 1-tap points redemption.
• My Vouchers Wallet: Thermal wallet tickets featuring Code-128 linear barcodes and 2D QR codes ready for cashier scanning.
• Viral Refer & Earn Engine: Monospace referral code card, QR sharing, 1-tap clipboard copy, and native WhatsApp/SMS invite sharing.
• Itemized Digital Receipts & PDF Export: Detailed transaction receipts with 1-tap thermal slip printing (expo-print) and PDF sharing (expo-sharing).
• GDPR / CCPA / Apple Compliant Account Deletion: In-app “Delete My Account” button permanently purges user data in compliance with Apple App Store Guideline 5.1.1(v).

2. ⛽ Staff Attendant Forecourt POS App (staffapp/)

• Station & Shift Lock: Attendant logs in with assigned station credentials, locking to their active branch and dispenser pump bays.
• Hardware Camera QR Decoder: Hardware-accelerated camera scanner (expo-camera) validating customer profiles and VIP tier multipliers in under 100ms.
• Dispenser Bay & Fuel Grade Selector: Select dispenser lane (Pump #1 to #16+) and fuel grade (Regular 87, Diesel Ultra, Premium 93, EV Fast).
• Volume & Financial Calculator: Preset volume chips (10L, 25L, 40L, 60L) and dollar amount chips ($20, $50, $100) with live tier multiplier bonus points.
• Tender Settlement: Multi-tender support: Cash, Credit/Debit Card POS, Loyalty Points/Vouchers, and Fleet Accounts with optional odometer/plate entry.
• Voucher Validation & Redemption Terminal: In-lane barcode scanner validating voucher status, expiry dates, and minimum spend thresholds.
• Shift Closeout Audit & Official Z-Report: Cash drawer count reconciliation calculating overage/shortage variance with printable Z-Report audit slips.
• Manual Dispense Fallback: Phone number and email customer lookup for offline drivers or dead phone batteries.

3. Super Admin Command Center Mobile App (adminapp/)

• Executive KPI Overview: Real-time dashboard showing Gross Fuel Revenue, Total Liters Dispensed, Transaction Volume, and Active Loyalty Members.
• Interactive Revenue & Volume Trends: Multi-period visual trend charts (7-day, 30-day, 90-day) powered by react-native-gifted-charts.
• Multi-Branch & Pump Bay Manager: Create and edit station locations with GPS coordinates, operating hours, and custom dispenser pump bays.
• Live Fuel Price Board Editor: Update fuel rates per liter across branches with instant WebSocket push to all customer and staff screens.
• Customer CRM Directory: Searchable member directory filtered by VIP tier (Bronze, Silver, Gold, Platinum) with lifetime visit history.
• Manual Loyalty Points Adjustment: Admin manual points credit/debit adjustments with mandatory audit remarks.
• Staff Shift Roster & Leaderboards: Attendant provisioning and performance rankings by vehicle throughput and liters dispensed.
• Broadcast Promotional Push Engine: Dispatch targeted promotional push notifications to all drivers or specific VIP tiers via Firebase FCM.

4. ⚙️ Real-Time Centralized Backend API (backend/)

• Express & Strict TypeScript: Modular layered architecture with Zod schema validation and native async error handling.
• 13 Comprehensive REST API Controllers: Full coverage for /auth, /qr, /transactions, /rewards, /vouchers, /branches, /pumps, /users, /staff, /analytics, /settings, /notifications, /upload, and /health.
• AES-256 Cryptographic QR Nonce Engine: Rolling 60-second token generation and atomic server-side verification.
• MongoDB Multi-Document ACID Transactions: Serialized write locks preventing race conditions during simultaneous fueling or voucher redemption.
• Socket.io Bidirectional WebSockets: Real-time price broadcasts, live attendant event streams, and customer haptic points credit alerts.
• OpenAPI Swagger Interactive Specification: Embedded at /api-docs for live browser testing and API documentation.

What You Get (Download Package Contents)

• Complete Customer Mobile App Source Code (customerapp/): Full React Native / latest Expo SDK project ready for Android & iOS EAS builds.
• ⛽ Complete Staff Attendant POS App Source Code (staffapp/): Full React Native / latest Expo SDK project with camera scanner & Z-report generator.
• Complete Super Admin Mobile App Source Code (adminapp/): Full React Native / latest Expo SDK project with Gifted Charts KPI analytics.
• ⚙️ Complete Real-Time Backend Source Code (backend/): Full Node.js / Express / TypeScript / MongoDB API server.
• Comprehensive Interactive Documentation (documentation/index.html): 28-section searchable HTML documentation with color swatches, eas.json templates, store submission checklists, and FAQ accordions.
• Automated Database Seeders & Sample Data (npm run db:seed): Initial demo admin, attendants, customer accounts, branches, pumps, tiers, and reward vouchers.
• Free Lifetime Updates & Dedicated Support: Access to all future feature updates, Expo SDK upgrades, and fast technical support.

⚙️ Technical Specifications & Compatibility

• Software Version: v1.0.0 (Commercial Production Release)
• Mobile Apps Framework: React Native, latest Expo SDK, Expo Router, NativeWind (Tailwind CSS)
• Backend Framework: Node.js (LTS), Express, TypeScript, Mongoose ODM, Socket.io
• Database: MongoDB (Local Replica Set) or MongoDB Atlas Cloud Cluster
• Styling & Theme Engine: Tailwind CSS & NativeWind with customizable @theme tokens in global.css
• Supported Platforms: Android 9.0+ (Oreo to Android 15+) & iOS 14.0+ (iPhone & iPad)
• Build Tooling: Expo Application Services (EAS Build) with standalone APK and Bare React Native support

Dedicated Support & Developer Contact

Need assistance with setup, cloud deployment, customization, or have pre-purchase questions? Our team provides fast, dedicated technical support:

• Direct Email Support: shakeelsoftwaredev@gmail.com
• WhatsApp Direct Chat: +92 313 6900591
• ⚡ Response Time: Within 24-48 business hours with complete post-purchase installation guidance.