Skip to content

App Architecture

Overview

The REward Flutter app follows a feature-based architecture with clean separation of concerns.

Directory Structure

lib/
├── app/                    # Application configuration
│   ├── theme.dart          # Colors, typography, themes
│   ├── routes.dart         # GoRouter navigation
│   └── constants.dart      # App-wide constants
│
├── core/                   # Shared functionality
│   ├── services/           # Business logic services
│   │   ├── firebase_auth_service.dart
│   │   ├── notification_service.dart
│   │   ├── location_service.dart
│   │   ├── kiosk_service.dart
│   │   ├── offers_service.dart
│   │   └── ble_service.dart
│   │
│   ├── widgets/            # Reusable widgets
│   │   ├── animated_background.dart
│   │   └── profile_completion_popup.dart
│   │
│   └── utils/              # Utilities
│       └── logger.dart
│
└── features/               # Feature modules
    ├── auth/               # Authentication
    │   └── screens/
    │       ├── login_screen.dart
    │       ├── register_screen.dart
    │       └── welcome_screen.dart
    │
    ├── home/               # Home/Dashboard
    │   └── screens/
    │       └── home_screen.dart
    │
    ├── profile/            # User profile
    │   └── screens/
    │       ├── profile_screen.dart
    │       └── edit_profile_screen.dart
    │
    ├── map/                # Kiosk locator
    │   └── screens/
    │       └── map_screen.dart
    │
    ├── rankings/           # Leaderboard
    │   └── screens/
    │       └── rankings_screen.dart
    │
    ├── offers/             # Rewards & offers
    │   └── screens/
    │       └── offers_screen.dart
    │
    ├── notifications/      # User notifications
    │   └── screens/
    │       └── notifications_screen.dart
    │
    └── admin/              # Admin panel
        └── screens/
            └── admin_dashboard_screen.dart

Key Services

FirebaseAuthService

Handles authentication, user management, and leaderboard data.

final authService = context.read<FirebaseAuthService>();
await authService.login(email: email, password: password);

NotificationService

Manages FCM push notifications and local notifications.

await NotificationService().initialize();
await NotificationService().sendPushToTopic(topic: 'all_users', title: 'Hello', body: 'World');

LocationService

Handles GPS permissions and distance calculations.

final position = await LocationService().getCurrentLocation();
final distance = LocationService.distanceBetween(lat1, lng1, lat2, lng2);

KioskService

Manages kiosk data and transactions via Firestore.

Stream<List<Kiosk>> kiosks = KioskService().getKiosksStream();

State Management

Uses Provider for dependency injection and state management.

// In main.dart
MultiProvider(
  providers: [
    ChangeNotifierProvider(create: (_) => FirebaseAuthService()),
    Provider(create: (_) => BleService()),
  ],
  child: RewardApp(),
)

// In widgets
final authService = context.watch<FirebaseAuthService>();
final user = authService.currentUser;

Uses GoRouter for declarative routing.

// Navigate
context.go('/main/home');
context.push('/offers');

// Routes defined in app/routes.dart

Adding New Features

  1. Create feature directory: lib/features/my_feature/
  2. Add screens: lib/features/my_feature/screens/
  3. Add widgets: lib/features/my_feature/widgets/ (if needed)
  4. Register route in app/routes.dart
  5. Add service in core/services/ (if needed)