Skip to content

Flutter Codebase Reference 📱

This is a comprehensive guide to every directory and file in the REward Flutter application.

Directory Structure Overview

lib/
├── app/          # Centralized app configuration (Routes, Theme)
├── core/         # Shared logic, models, services, and global widgets
├── features/     # Modular business logic (The "Meat" of the app)
└── main.dart     # Entry point of the application

🏗️ Core Configuration (lib/app/)

File Responsibility
routes.dart Defines the navigation map using GoRouter. Handles screen transitions and deep links.
theme.dart Contains the global Design System (Colors, Typography, Button styles). Uses ThemeData.

🧠 Shared Logic (lib/core/)

Services (lib/core/services/)

These handle external data sources.

File Purpose
auth_service.dart General interface for authentication logic.
firebase_auth_service.dart Implementation of Firebase Auth (Email/Google Sign-In).
ble_service.dart Handles Bluetooth Low Energy communication with the ESP32 kiosk.
home_service.dart Fetches data for the home dashboard (stats, active kiosks).
kiosk_service.dart Manages kiosk-related data and status updates.
location_service.dart Uses the geolocator package to find the user's GPS position.
notification_service.dart Manages Firebase Cloud Messaging and local push notifications.
offers_service.dart Fetches and manages recycling rewards and partner offers.

Models (lib/core/models/)

Data structures (Classes) used to parse JSON from the database.

File Description
global_stats_model.dart Data structure for total plastic/metal recycled globally.
home_card_model.dart Defines the layout and data for cards shown on the home screen.

Global Widgets (lib/core/widgets/)

Reusable UI components used across multiple features.

Widget Usage
animated_background.dart A beautiful, moving background used for aesthetic appeal.
auth_background.dart Shared background for Login and Signup screens.
main_scaffold.dart The shell of the app that contains the Bottom Navigation Bar.
profile_completion_popup.dart A reminder shown to new users to finish their profile setup.

🚀 Features (lib/features/)

Each feature is a self-contained module with its own screens and logic.

Auth (Login & Registration)

  • login_screen.dart: Main entry for returning users.
  • signup_screen.dart: Account creation workflow.
  • forgot_password_screen.dart: Email recovery process.

Home

  • home_screen.dart: The dashboard showing points and recent activity.
  • plastic_metal_screen.dart: Detailed view of recycling statistics.
  • home_carousel.dart: Sliding banner for announcements.

Map

  • map_screen.dart: Interactive Google Maps view showing nearby kiosks and distance.

Notifications

  • notifications_screen.dart: List of all received alerts (points earned, new offers).

Offers & Rewards

  • offers_screen.dart: Browsing available rewards.
  • apps/rewards_screen.dart: Redeeming points for specific vouchers.

Profile

  • profile_screen.dart: User settings and progress overview.
  • edit_profile_screen.dart: Update name, email, or avatar.
  • qr_code_screen.dart: Displays the user's unique ID for scanning at kiosks.
  • points_history.dart: A list of every recycling transaction.

Rankings

  • rankings_screen.dart: The global and local Leaderboard.

📦 Core Packages (Dependencies)

We use several powerful packages from pub.dev to speed up development:

Package Category Usage in REward
firebase_core Backend Connects the app to Google Firebase.
cloud_firestore Database Real-time storage for user points and kiosk status.
go_router Navigation Clean management of screen changes.
flutter_blue_plus Bluetooth Talking to the ESP32 without using Wi-Fi.
google_maps_flutter Maps Drawing the kiosk map.
provider State Sharing data (like user balance) between many screens.
lottie Animation Playing cool animations when you recycle something!