CardCade - Customer Card Manager

CardCade is a React-based customer card management application with barcode scanning capabilities and location-based shop selection. The app allows users to store and manage customer loyalty cards with smart features for finding the closest relevant shop.

Features

• 📱 Barcode Scanning: Scan customer cards using your device's camera
• 🎰 Magic Click: Click the logo to automatically select the closest shop based on your location
• 🗺️ Location-Based Selection: Uses hardcoded shop coordinates to find nearby shops and match them with your cards
• 🔥 Firebase Integration: Cloud storage for all your customer cards
• 📱 Responsive Design: Works on mobile and desktop devices
• 🎨 Material Design: Clean, modern UI with Material-UI components
• 💾 Progressive Web App (PWA): Install on Android and iOS devices, works offline with service worker caching

PWA Features

CardCade is a fully-featured Progressive Web App that can be installed on both Android and iOS devices:

Installation

Android (Chrome/Edge):

1. Open the app in Chrome or Edge
2. Tap the menu (three dots) and select "Install app" or "Add to Home Screen"
3. The app will be installed and can be launched from your home screen

iOS (Safari):

1. Open the app in Safari
2. Tap the Share button (square with arrow)
3. Scroll down and tap "Add to Home Screen"
4. Tap "Add" to confirm
5. The app will appear on your home screen

Offline Support

The PWA includes a service worker that caches resources for offline use:

• All app assets (JS, CSS, images) are cached after first visit
• Cards and data are stored in Firebase, which has its own offline persistence
• Google Fonts are cached for consistent styling offline

PWA Benefits

• Fast Loading: Cached assets load instantly
• Offline Access: Core functionality works without internet
• Native-like Experience: Runs in standalone mode without browser UI
• Auto-updates: New versions are automatically downloaded and activated
• Responsive: Adapts to any screen size and orientation

Magic Click Feature

The "Magic Click" feature uses your device's GPS location to:

1. Get your current position
2. Calculate distances to all shop locations stored with your cards
3. Find the closest shop location
4. Automatically select and display the card for the closest shop
5. Fall back to random selection if no shop locations are available

Setup and Installation

Prerequisites

• Node.js 20.19+ or 22.12+
• A Firebase project

Environment Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Configure your environment variables in .env:

Firebase Configuration

VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abcdef123456
VITE_FIRESTORE_COLLECTION=customer_cards
VITE_APP_NAME=CardCade

Installation

1. Install dependencies:

   npm install

2. Start the development server:

   npm run dev

3. Build for production:

   npm run build

4. Deploy to Firebase Hosting:

   firebase deploy --only hosting

Usage

1. Add Cards: Click "Add Card" to scan or manually enter customer card information

   • Shop Locations: Expand the "Shop Locations" section to add GPS coordinates for shop locations
   • Multiple Locations: Add multiple locations for chains with multiple stores
   • Coordinates: Find coordinates using Google Maps by clicking on a location

2. Magic Click: Click the CardCade logo to find the closest shop and display its card

3. View Cards: Browse all your stored cards in the responsive grid layout

4. Card Details: Click any card to view its full details and barcode

Adding Shop Locations

When adding a new card, you can specify one or more shop locations:

1. Expand the "Shop Locations" accordion in the add card form
2. Enter latitude and longitude coordinates for each shop location
3. Add multiple locations for chains (e.g., different McDonald's locations)
4. Use Google Maps to find coordinates:
   • Search for the shop on Google Maps
   • Click on the location to get coordinates
   • Copy the coordinates to the form

Example coordinates:

• New York City: 40.7128, -74.0060
• Los Angeles: 34.0522, -118.2437
• London: 51.5074, -0.1278

Technical Stack

• Frontend: React 18 + TypeScript + Vite
• UI Library: Material-UI (MUI)
• Backend: Firebase Firestore
• Barcode Scanning: Quagga2
• Location Services: Browser Geolocation API
• PWA: vite-plugin-pwa with Workbox
• Service Worker: Auto-updating with runtime caching
• Deployment: Firebase Hosting

Architecture

src/
├── components/
│   ├── AddCardForm.tsx    # Card input form with barcode scanning and location management
│   └── CardList.tsx       # Card display grid with modal
├── utils/
│   └── magicClick.ts      # Location-based shop selection logic
├── types.ts               # TypeScript type definitions including ShopLocation
├── firebase.ts            # Firebase configuration
└── App.tsx               # Main application component

Data Structure

Each customer card now includes shop locations:

interface CardContent {
  id: string;
  store_name: string;
  code: string;
  barcode_type: string;
  shop_locations: ShopLocation[];
}

interface ShopLocation {
  lat: number;
  lng: number;
}

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit your changes: git commit -am 'Add feature'
4. Push to the branch: git push origin feature-name
5. Submit a pull request

Security Notes

• Never commit your .env file to version control
• Configure Firebase security rules appropriately
• Use HTTPS in production for geolocation access
• Be mindful of location privacy when sharing cards