🏀 SlamView

Real-Time Basketball Match Tracker & Team Management Platform
Built with Flutter · Powered by Firebase · Designed with Material 3

---

📋 Table of Contents

• Overview
• Key Features
• Screenshots
• Architecture
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Installation
  • Firebase Setup
  • Running the App
• Firebase Cloud Functions
• Theming & Design System
• Authentication Flow
• State Management
• Supported Platforms
• Environment Variables & Security
• Contributing
• Roadmap
• License
• Contact

---

🌟 Overview

SlamView is a feature-rich, cross-platform basketball match tracking application that delivers real-time live scores, comprehensive team management, and push notification alerts — all wrapped in a premium Material 3 user interface with full dark/light theme support.

Whether you're following a college tournament, tracking a friendly pickup game, or managing rosters, SlamView provides a seamless, courtside-like experience right from your device.

Why SlamView?
Traditional scoreboards are static and require you to be physically present. SlamView brings the action to your fingertips with real-time Firebase synchronization, automated push notifications when matches go live, and a beautifully crafted basketball-themed UI with immersive animations.

---

🚀 Key Features

🔴 Live Match Tracking

• Real-time score updates powered by Firebase Realtime Database
• Auto-refreshing match cards with background polling
• Support for both tournament matches (/live_score/) and custom/friendly matches (/custom_live_score/)
• Tap any match card to drill into detailed match statistics

📊 Match Details

• Comprehensive match detail view with quarter-by-quarter scoring breakdown
• Team rosters with individual player statistics
• Real-time status indicators (Live 🔴 / Completed ✅)
• Custom basketball-themed painters and decorative UI elements

✅ Completed Matches

• Historical archive of all finished matches
• Final scores with win/loss indicators
• Formatted end-time display
• Animated list rendering with staggered entrance animations

👥 Teams & Roster Management

• Browse all registered teams categorized by gender (Men's / Women's)
• View full player rosters with detailed player information
• Follow/Unfollow teams — synced to Firebase per user account
• Auto-refresh with periodic background data fetching

❤️ Followed Teams

• Personalized feed of your followed teams
• Quick access to team rosters and upcoming matches
• Gradient-styled team cards differentiated by gender category

🔔 Push Notifications

• Firebase Cloud Messaging (FCM) integration
• Automatic notifications when any match goes live
• Background message handling for uninterrupted alerts
• Permission management for iOS and Android 13+

🔐 Authentication System

• Firebase Authentication with email/password
• Secure sign-up with automatic user registration in Firebase Realtime Database
• Password reset via email
• Auth-guarded navigation with AuthWrapper
• Double-layer verification: Firebase Auth + usersappauth database node

🎨 Premium UI/UX

• Material 3 design language with ColorScheme.fromSeed
• System-aware dark/light theme toggling
• Custom basketball-themed splash screen with particle animations
• Animated loading screens with basketball court motifs
• Gradient navigation cards, stat cards, and welcome banners
• Smooth micro-animations and haptic-style feedback

---

📸 Screenshots

Screenshots coming soon — run the app locally to experience the full UI.

---

🏗 Architecture

SlamView follows a page-based architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────┐
│                    main.dart                         │
│         (Firebase Init, FCM, MaterialApp)            │
├─────────────────────────────────────────────────────┤
│                  SplashScreen                        │
│       (Animated intro + Auth state check)            │
├──────────────┬──────────────────────────────────────┤
│  AuthPage    │           AuthWrapper                 │
│  (Login/     │  (StreamBuilder on authStateChanges)  │
│   SignUp)    │  (FutureBuilder on usersappauth)       │
├──────────────┴──────────────────────────────────────┤
│                    HomePage                          │
│         (Dashboard, Quick Stats, Nav Grid)           │
├──────────┬───────────┬──────────┬───────────────────┤
│  Live    │ Completed │  Teams   │  Followed Teams    │
│ Matches  │  Matches  │  Page    │     Page           │
│  Page    │   Page    │          │                     │
├──────────┴───────────┴──────────┴───────────────────┤
│              MatchDetailsPage                        │
│    (Quarter scores, rosters, live status)             │
├─────────────────────────────────────────────────────┤
│             Firebase Realtime Database                │
│     /live_score  /custom_live_score  /teams           │
│     /usersappauth  /completed_matches                │
└─────────────────────────────────────────────────────┘

---

🛠 Tech Stack

Layer	Technology
Framework	Flutter 3.8+ / Dart 3.8+
UI	Material 3, Google Fonts, ScreenUtil
State	StatefulWidget + Flutter Riverpod (available)
Navigation	Go Router (configured), page-based push navigation
Backend	Firebase Realtime Database
Auth	Firebase Authentication (Email/Password)
Storage	Firebase Storage
Analytics	Firebase Analytics
Messaging	Firebase Cloud Messaging (FCM)
Cloud Functions	Firebase Cloud Functions (Node.js)
Forms	Form Builder Validators
Toasts	Fluttertoast
Icons	Cupertino Icons, Material Icons
Hosting	Firebase Hosting (Web build)

---

📁 Project Structure

slamview/
├── android/                    # Android platform configuration
├── ios/                        # iOS platform configuration
├── web/                        # Web platform configuration
├── windows/                    # Windows platform configuration
├── macos/                      # macOS platform configuration
├── linux/                      # Linux platform configuration
│
├── assets/
│   ├── icon.png                # High-res app icon (1696 KB)
│   └── app_icon.png            # Optimized app icon
│
├── lib/
│   ├── main.dart               # App entry point — Firebase init, FCM, theming
│   ├── firebase_options.dart   # Auto-generated Firebase config (FlutterFire CLI)
│   ├── splash_screen.dart      # Animated splash with particle effects & auth check
│   ├── auth_page.dart          # Login / Sign-Up / Forgot Password UI
│   ├── auth_wrapper.dart       # Auth state guard (Firebase Auth + DB validation)
│   ├── home_page.dart          # Dashboard with stats, nav grid, welcome banner
│   ├── live_matches_page.dart  # Real-time live match feed with auto-refresh
│   ├── match_details_page.dart # Detailed match view with quarter scores & rosters
│   ├── completed_matches_page.dart  # Archive of completed matches
│   ├── teams_page.dart         # Browse & follow teams (Men's / Women's)
│   └── followed_teams_page.dart     # Personalized followed teams feed
│
├── functions/
│   └── index.js                # Firebase Cloud Functions — live match notifications
│
├── test/                       # Flutter test directory
├── pubspec.yaml                # Flutter dependencies & project metadata
├── firebase.json               # Firebase project configuration
├── .firebaserc                 # Firebase project aliases
├── .gitignore                  # Git ignore rules
└── analysis_options.yaml       # Dart static analysis configuration

---

⚡ Getting Started

Prerequisites

Ensure you have the following installed on your development machine:

Tool	Version	Installation
Flutter SDK	≥ 3.8.1	flutter.dev/get-started
Dart SDK	≥ 3.8.1	Bundled with Flutter
Node.js	≥ 18.x	nodejs.org (for Cloud Functions)
Firebase CLI	Latest	npm install -g firebase-tools
Git	Latest	git-scm.com

Installation

1. Clone the repository

   git clone https://github.com/<your-username>/slamview.git
   cd slamview

2. Install Flutter dependencies

   flutter pub get

3. Install Cloud Functions dependencies

   cd functions
   npm install
   cd ..

Firebase Setup

1. Create a Firebase project at console.firebase.google.com

2. Install and configure FlutterFire CLI

   dart pub global activate flutterfire_cli
   flutterfire configure --project=<your-firebase-project-id>

   This generates lib/firebase_options.dart automatically.

3. Enable the following Firebase services in the Firebase Console:

   • ✅ Authentication → Email/Password provider
   • ✅ Realtime Database → Set up security rules
   • ✅ Cloud Messaging → For push notifications
   • ✅ Cloud Functions → Deploy functions/index.js
   • ✅ Hosting (optional) → For web deployment
   • ✅ Analytics → Enabled by default

4. Set up Realtime Database structure

   {
     "live_score": {},
     "custom_live_score": {},
     "completed_matches": {},
     "teams": {
       "men": {},
       "women": {}
     },
     "usersappauth": {}
   }

5. Deploy Cloud Functions

   firebase deploy --only functions

Running the App

# Run on connected device / emulator
flutter run

# Run on specific platform
flutter run -d chrome        # Web
flutter run -d windows       # Windows
flutter run -d macos          # macOS
flutter run -d linux          # Linux

# Build for production
flutter build apk             # Android APK
flutter build ios              # iOS (requires macOS)
flutter build web              # Web (output: build/web/)

Deploy web build to Firebase Hosting:

flutter build web
firebase deploy --only hosting

---

☁️ Firebase Cloud Functions

SlamView includes serverless Cloud Functions that automatically send push notifications when matches go live.

notifyLiveScore

• Trigger: onUpdate on /live_score/{matchId}/live
• Action: When the live field transitions from false → true, sends a push notification to the live_matches FCM topic
• Payload: "🏀 Match Went Live! A College Tournament Match is now live. Tap to watch now!"

notifyCustomLiveScore

• Trigger: onUpdate on /custom_live_score/{matchId}/live
• Action: Same as above but for custom/friendly matches
• Payload: "🏀 Match Went Live! A Friendly or Custom Match is now live. Tap to watch now!"

functions/
└── index.js          # Node.js Cloud Functions (Firebase Admin SDK)

---

🎨 Theming & Design System

SlamView leverages Material 3 for a modern, adaptive design:

• Color Scheme: Generated from Colors.deepPurple seed using ColorScheme.fromSeed()
• Theme Mode: Automatically follows the system preference (ThemeMode.system)
• Dual Themes: Both light and dark themes are fully configured
• Typography: Google Fonts integration available via the google_fonts package
• Responsive Layout: flutter_screenutil for adaptive sizing across devices
• Custom Painters: Basketball-themed decorative elements (BasketballPainter, EnhancedBasketballPainter, PremiumParticlesPainter)

Design Highlights

• 🌊 Gradient navigation cards with basketball-themed iconography
• ✨ Particle animation system on the splash screen
• 🏟️ Basketball court-style loading animations
• 📊 Animated stat cards with staggered entrance effects
• 🎯 Custom snackbar designs with basketball theming

---

🔐 Authentication Flow

App Launch
    │
    ▼
SplashScreen (Animated Intro)
    │
    ├── User authenticated + exists in /usersappauth?
    │       ├── YES → HomePage (Dashboard)
    │       └── NO  → AuthPage (Login / Sign Up)
    │
    ▼
AuthPage
    ├── Sign In → Firebase Auth → Verify in /usersappauth → HomePage
    ├── Sign Up → Firebase Auth → Write to /usersappauth → HomePage
    └── Forgot Password → Send reset email

Double-layer security:

1. Firebase Authentication verifies credentials
2. AuthWrapper checks if the user's UID exists in the /usersappauth database node
3. If the user is not in the database, they are signed out and redirected to the login page

---

🧠 State Management

The project uses StatefulWidget with lifecycle methods for local state management and StreamBuilder / FutureBuilder for reactive Firebase data binding. The flutter_riverpod package is included as a dependency for future scalability.

Pattern	Usage
StatefulWidget	Page-level state (match lists, animations)
StreamBuilder	Auth state changes (authStateChanges())
FutureBuilder	Async DB lookups (usersappauth verification)
Timer.periodic	Background data refresh (live scores, teams)
AnimationController	Splash screen, loading, and transition effects

---

📱 Supported Platforms

Platform	Status	Notes
Android	✅ Supported	Full support including FCM notifications
iOS	✅ Supported	Requires Xcode & Apple Developer account
Web	✅ Supported	Deployable via Firebase Hosting
Windows	✅ Supported	Native desktop build
macOS	✅ Supported	Requires macOS for building
Linux	✅ Supported	Native desktop build

---

🔒 Environment Variables & Security

⚠️ Important: Never commit API keys or sensitive Firebase configuration to version control.

• lib/firebase_options.dart is auto-generated by FlutterFire CLI and contains platform-specific Firebase config. Consider adding it to .gitignore for public repositories.
• The functions/ directory should not expose any service account keys.
• Use Firebase Security Rules to protect your Realtime Database.

Recommended .gitignore additions for public repos:

lib/firebase_options.dart
android/app/google-services.json
ios/Runner/GoogleService-Info.plist

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Commit your changes

   git commit -m "feat: add amazing feature"

4. Push to the branch

   git push origin feature/amazing-feature

5. Open a Pull Request

Commit Convention

This project follows Conventional Commits:

Prefix	Usage
feat:	New feature
fix:	Bug fix
docs:	Documentation changes
style:	Formatting, no code change
refactor:	Code restructuring
test:	Adding or updating tests
chore:	Build process or tooling

---

🗺 Roadmap

• Add player statistics leaderboard
• Implement in-app match scheduling
• Add team chat functionality
• Integrate social media sharing for match results
• Support tournament bracket visualization
• Add offline mode with local caching
• Implement Riverpod-based global state management
• Add unit and widget tests for all pages

---

📄 License

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

You are free to use, modify, and distribute this project. Contributions are welcome!

---

📬 Contact

• GitHub: @AryantKumar
• Repository: github.com/AryantKumar/Slamview

---

Built with ❤️ and 🏀 by the SlamView Team
Bringing the courtside experience to your fingertips