Skip to content

Phase 1: Core & Shell 🏗️

This phase covers the foundational files that initialize the application, handle navigation, define the visual design, and manage logging.

1. lib/main.dart

The Front Door of the App

This file is the starting point. When you run flutter run, this is where the execution begins.

Key Responsibilities:

  • Binding Initialization: WidgetsFlutterBinding.ensureInitialized() ensures Flutter's internal engine is ready before we start Firebase.
  • Firebase Setup: Calls Firebase.initializeApp() to connect the app to your cloud backend (Firestore, Auth, etc.).
  • Global Services: Initializes NotificationService (for push alerts) and LocationService (for the map).
  • Dependency Injection (DI): Uses MultiProvider to wrap the entire app. This makes FirebaseAuthService and BleService available to every single screen in the app.

Important Snippet:

runApp(
  MultiProvider(
    providers: [
      ChangeNotifierProvider(create: (_) => FirebaseAuthService()),
      ChangeNotifierProvider(create: (_) => BleService()),
    ],
    child: const RewardApp(),
  ),
);

Why this matters: By putting these at the root, the user's login state and Bluetooth connection status are shared globally.

2. lib/app/routes.dart

The Navigation Map

This file uses the go_router package to define every "URL" or screen in the app.

Key Responsibilities:

  • Centralized Paths: Instead of using strings like '/login' everywhere, we use constants like RoutePaths.login. This prevents bugs from typos.
  • ShellRoute (Bottom Nav): This is a clever feature that keeps the Bottom Navigation Bar visible while you switch between Home, Map, and Profile. It "shells" the main content inside a persistent layout.
  • Error Handling: Defines an errorBuilder that shows a "Page Not Found" screen if the app tries to navigate to a broken link.

Path Hierarchy:

  • / → Splash Screen.
  • /auth/login → Entrance.
  • /main/home → Inside the Shell (Bottom Nav).

3. lib/app/theme.dart

The Design System

Instead of picking colors on every screen, we define everything here once. If you want to change the "Green" to "Blue", you only change one line in this file!

Key Responsibilities:

  • AppColors: A class containing the exact HEX codes for "Forest Green" (#1E3A34) and "Mint" (#4CAF50).
  • Typography: Uses GoogleFonts.inter to give the app a premium, modern feel. It defines sizes for headlineLarge, bodyMedium, etc.
  • Component Themes: Sets the default look for every ElevatedButton, TextField, and Card in the app. This ensures the app looks consistent from start to finish.

Design Choice:

The theme uses Material 3, Google's latest design language, which supports smooth animations and adaptive layouts.

4. lib/core/utils/logger.dart

The Flight Recorder

When you are developing, print() is messy. This utility provides a better way to see what's happening.

Key Responsibilities:

  • Levels: You can log at different levels: verbose, debug, info, warning, error, and fatal.
  • Formatting: It makes console logs look beautiful and easy to read, with emojis and timestamps.
  • Production Safety: We can configure it to turn off certain logs in production to keep the app fast and secure.

Usage Example:

AppLogger.debug("Hardware scan started...");
AppLogger.error("Failed to connect to ESP32", e, stack);

Phase 1 Complete. Next, we move to Phase 2: Authentication.