🎁 MySuf Blind Box — NFC Registration & Game System

A modern, enterprise-grade Flutter application for student registration, NFC card interaction, and blind box prize management.

---

📌 Overview

MySuf Blind Box is an interactive mobile application built for school/event participant registration and blind box prize draws powered by NFC (Near Field Communication) technology.

The app features a custom-crafted Neo-Brutalist UI Design System featuring high-contrast geometric borders, hard unblurred offset shadows, and clean modern typography (Manrope), delivering an engaging and tactile user experience.

---

✨ Key Features

• ⚡ NFC Card Registration & Writing: Scan participant NFC tags, automatically match student records, and write session payloads directly to NFC cards.
• 🎁 Blind Box Game & Prize Claiming: Instant prize tier evaluation, blind box availability tracking, and claim confirmation.
• 📊 Real-time Dashboard: Live counters for registered participants, total claims, available prize boxes, and event activity.
• 📜 Audit History & Logs: Complete searchable history of student registrations and reward disbursements.
• 🎨 Neo-Brutalist Design System: Centralized design system components (BrutalButton, BrutalCard, BrutalTextField, BrutalDialog, BrutalTable, BrutalBadge).
• 🔐 Authentication & Mock Fallback: Secure Firebase Authentication with built-in Mock Backend fallback for offline development and testing.

---

🎨 Design System Principles

The UI follows strict Neo-Brutalist Architecture rules:

Token	Specification	Usage
Primary Accent	#E31837 (Crimson Red)	Main call-to-action buttons, active states, key focal points
Foreground / Border	#0F172A (Dark Slate)	Structural 2–3px solid borders, primary typography
Background / Surface	#FFFFFF (Clean White)	Page background, cards, input fields
Shadows	4px 4px Hard Offset (#0F172A, 0 blur)	Physical pressable button feedback & cards
Typography	Manrope (Google Fonts)	Bold display headers and clear body hierarchy

---

🏗 Project Architecture

The project follows clean architecture principles with feature-based modularity:

lib/
├── features/
│   ├── auth/           # Staff authentication & login screens
│   ├── dashboard/      # Event overview & real-time analytics
│   ├── history/        # Registration & prize claim logs
│   ├── navigation/     # Bottom bar & main application scaffolding
│   ├── nfc/            # NFC scanning, reading, and writing logic
│   ├── registration/   # Participant data entry & validation
│   └── settings/       # App settings & debug diagnostic screen
├── ui/
│   ├── components/     # Neo-Brutalist reusable UI components
│   │   ├── brutal_app_bar.dart
│   │   ├── brutal_badge.dart
│   │   ├── brutal_button.dart
│   │   ├── brutal_card.dart
│   │   ├── brutal_dialog.dart
│   │   ├── brutal_input.dart
│   │   ├── brutal_responsive_layout.dart
│   │   └── brutal_table.dart
│   ├── theme/          # Centralized tokens (colors, spacing, typography, theme)
│   └── brutal_ui.dart  # Central design system barrel export
├── firebase_options.dart
└── main.dart

---

🚀 Tech Stack & Dependencies

• Framework: Flutter SDK (Dart SDK ^3.12.0)
• State Management: Flutter Riverpod (^2.6.1)
• Backend & Database:
  • Firebase Core (^4.13.0)
  • Cloud Firestore (^6.8.0)
  • Firebase Auth (^6.5.7)
• Hardware Integration: NFC Manager (^4.2.1)
• UI & Typography: Google Fonts (Manrope) (^8.2.1)
• Date & Utility: Intl (^0.20.3)

---

🛠 Getting Started

Prerequisites

• Flutter SDK (v3.12.0 or higher) installed on your system.
• Android device with NFC enabled (or iOS device with NFC support).
• Firebase Project setup (optional if using Mock Mode).

Installation Steps

1. Clone the repository:

   git clone https://github.com/your-username/mysuf_blind_box.git
   cd mysuf_blind_box

2. Install dependencies:

   flutter pub get

3. Firebase Configuration (Optional):

   • Place your google-services.json in android/app/.
   • Place your GoogleService-Info.plist in ios/Runner/.
   • Update lib/firebase_options.dart if needed. Note: If Firebase is not configured, the application automatically activates Mock Backend Mode for testing.

4. Run the application:

   flutter run

---

🧪 Testing & Debugging

A dedicated Debug & Diagnostics Screen is accessible via Settings to:

• Test NFC tag reading/writing capabilities.
• Toggle between Live Firebase and Mock Backend providers.
• Generate sample student registration payloads for testing blind box draws.

---

🔒 Security & Credentials

Sensitive configuration files and credentials (e.g., google-services.json, firestore.rules, private admin keys) are listed in .gitignore and excluded from version control for security compliance.

---

📄 License

This project is proprietary and built for MySuf Blind Box Event Management. All rights reserved.