PulseCard - Loyalty Card Management App

A Flutter application for managing loyalty cards locally. Scan barcodes, store card information, and access your cards anytime without an internet connection.

Features

📱 Core Features

• Barcode Scanning: Scan loyalty card barcodes using your device camera
• Manual Entry: Enter barcode manually if scanning fails
• Card Management: Store card name, store name, barcode value, and format
• Store Logos: Add custom store logos from your photo library
• Local Storage: All data stored locally using Hive (no cloud sync needed)
• Dark Mode: Full support for light and dark themes
• Card Display: View cards in a beautiful grid layout
• Barcode Display: View scannable barcodes on card detail screen

🎨 Theme System

• Light & Dark Mode: Full support with Material 3 design
• Theme Persistence: Automatically saves user's theme preference
• Customizable Colors: Comprehensive color system with semantic naming
• Typography: Pre-configured text styles for consistent UI

🎯 Reusable Widgets

• Input Widgets: Text fields, dropdowns, date/time pickers
• Buttons: Primary, secondary, outlined, and text button variants
• Cards: Consistent card components
• Dialogs: Customizable dialog system
• Loading Indicators: Various loading states

🧭 Navigation

• GoRouter: Modern declarative routing
• Type-safe Routes: Route constants for better maintainability
• Error Handling: Built-in 404 error pages

Prerequisites

• Flutter SDK 3.9.2 or higher
• Dart SDK
• Camera access (for barcode scanning)
• Photo library access (for selecting store logos)

Getting Started

1. Clone the Repository

git clone <repository-url>
cd PulseCardApp

2. Install Dependencies

flutter pub get

3. Generate Hive Adapters

After installing dependencies, generate the Hive type adapters:

flutter pub run build_runner build --delete-conflicting-outputs

4. Run the App

flutter run

Project Structure

lib/
├── main.dart                    # App entry point
├── core/
│   ├── config/                  # Configuration files
│   │   ├── app_config.dart      # App-level configuration
│   │   └── environment.dart     # Environment enum
│   ├── constants/
│   │   └── app_constants.dart   # App-wide constants
│   ├── routing/
│   │   └── app_router.dart      # Navigation configuration
│   ├── theme/                   # Theme system
│   │   ├── app_theme.dart       # Main theme configuration
│   │   ├── app_colors.dart      # Color definitions
│   │   └── app_text_styles.dart # Text style definitions
│   └── utils/
│       └── app_icons.dart        # Icon helper
├── features/                    # Feature modules
│   ├── cards/                   # Loyalty cards feature
│   │   ├── models/              # Card model
│   │   ├── services/            # Storage service
│   │   ├── providers/           # State management
│   │   └── screens/              # Card detail screen
│   ├── home/                    # Home screen
│   ├── scanner/                 # Scanner screen
│   ├── settings/                # Settings screen
│   └── splash/                  # Splash screen
└── shared/
    └── widgets/                 # Reusable widgets
        ├── inputs/               # Input widgets
        ├── buttons/              # Button widgets
        ├── cards/               # Card widgets
        ├── loading/              # Loading indicators
        ├── dialogs/              # Dialog widgets
        └── snackbars/            # Snackbar widgets

Key Dependencies

• mobile_scanner: Barcode scanning using device camera
• hive: Local NoSQL database for storing cards
• hive_flutter: Flutter integration for Hive
• image_picker: Selecting store logos from photo library
• barcode_widget: Displaying scannable barcodes
• path_provider: File system paths for storing images
• provider: State management
• go_router: Navigation
• shared_preferences: Theme persistence

Usage

Scanning a Card

1. Tap the "Scan Card" floating action button on the home screen
2. Point your camera at the barcode
3. Once scanned, fill in the store name (required) and optional card name
4. Optionally add a store logo from your photo library
5. Tap "Save Card" to store it locally

Viewing Cards

• Cards are displayed in a grid on the home screen
• Each card shows the store logo (or placeholder), store name, and card name
• Tap any card to view details including the scannable barcode
• Use the menu button on the detail screen to edit or delete cards

Settings

• Toggle dark mode from the settings screen
• View app version information
• Clear all cards (with confirmation)

Data Storage

All loyalty card data is stored locally on your device using Hive:

• No internet connection required
• No cloud sync
• Data persists across app restarts

Store Images

Store logos are stored locally in the app's document directory:

• When you select an image from your photo library, it's copied to the app's private storage
• The file path is saved in the Hive database along with the card information
• Images are retrieved using File(card.logoPath!) when displaying cards
• If an image file is missing or corrupted, a placeholder icon is shown instead

Permissions

The app requires the following permissions:

• Camera: For scanning barcodes
• Photo Library: For selecting store logos (iOS)

Development

Running Tests

flutter test

Building for Production

# Android
flutter build apk --release

# iOS
flutter build ios --release

Code Generation

If you modify the LoyaltyCard model, regenerate the Hive adapter:

flutter pub run build_runner build --delete-conflicting-outputs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue on the repository.