Skip to content

Phase 3: Core Infrastructure 🏛️

This phase documents the technical "central nervous system" of the app—the background services that manage hardware communication and the global UI wrappers.

1. lib/core/services/ble_service.dart

The Hardware Bridge

The REward app communicates with the ESP32-powered recycling kiosk via Bluetooth Low Energy (BLE). This service manages that entire lifecycle.

Key Responsibilities:

  • Scanning: Searches for devices with a specific kioskServiceUuid.
  • Session Management: Handles the start (startSession) and end (endSession) of a recycling transaction.
  • Data Parsing: Listens to notifications from the ESP32 to receive real-time counts of bottles and cans deposited.
  • Proximity Logic: Uses Signal Strength (RSSI) to ensure the user is standing close enough to the kiosk to interact with it.

Communication Flow:

  1. User identifies via QR Code → App sends User ID to ESP32.
  2. User deposits items → ESP32 sends counts to App.
  3. User taps "Finish" → App calculates final points and displays a thank you message on the kiosk LCD.

2. lib/core/services/location_service.dart

Proximity & Mapping

While the BLE service handles "contactless" interaction, the Location Service handles "discovery."

Key Responsibilities:

  • Permissions: Manages the complex flow of requesting GPS permissions on Android and iOS.
  • Distance Calculation: Uses the Haversine formula (via the geolocator package) to calculate the distance between the user and the nearest kiosk in kilometers or meters.
  • Real-time Tracking: Provides a stream of location updates to keep the "Map" screen centered on the user.

3. lib/core/services/notification_service.dart

Push Notifications (FCM)

Keeps users engaged by sending alerts even when the app is closed.

Key Responsibilities:

  • Firebase Cloud Messaging (FCM): Handles the registration of unique device tokens.
  • Background Handlers: Processes messages that arrive while the app is in the background or terminated.
  • Local Notifications: Uses flutter_local_notifications to show immediate "Heads-up" alerts (e.g., "Points Earned! 🎉") when the user is actively using the app.
  • Topic Subscription: Automatically subscribes users to the all_users and offers_updates channels.

4. lib/core/widgets/main_scaffold.dart

The Navigation Shell

This is the "Frame" of the app. It ensures the Bottom Navigation Bar is always visible while the user explores different features.

Design Highlights:

  • Circular Notched Rectangle: The center "QR Code" button is docked into a custom notch in the navigation bar for a premium look.
  • Persistent State: Leverages go_router's ShellRoute to keep the background music or active BLE sessions alive while switching tabs.
  • Active States: Highlighting the current tab with the AppColors.primary green to guide the user.

5. lib/core/widgets/animated_background.dart

Micro-Animations & Polish

To make the app feel "alive," we use an animated background on major screens like the Home Dashboard.

Key Responsibilities:

  • Floaters: Uses AnimationController and math.sin to create slow-moving, floating organic shapes.
  • Custom Painting: Instead of heavy images, it uses CustomPainter to draw wavy shapes directly onto the canvas, keeping the app fast and lightweight.
  • Layering: Sits behind the main content, providing subtle visual depth without being distracting.

Phase 3 Complete. Next, we move to Phase 4: Home & Dashboard.