GymPulse 🏋️‍♂️📊

Real-time gym occupancy tracking via passive geofencing — check crowd levels before you leave home, no hardware required.

GymPulse solves a simple, universal problem: nobody wants to drive to the gym only to find every rack taken. Most occupancy-tracking solutions (turnstiles, badge scanners) require gyms to buy hardware — which prices out most independent and small gyms. GymPulse gets the same result using only members' phones: background geofencing silently detects when someone enters or exits the gym, and that data powers live occupancy counts, historical crowd patterns, and quiet-hour predictions.

---

💡 The Idea

"I want to know if my gym is busy before I leave the house — not after I get there."

That's the entire product in one sentence. Everything else — auth, geofencing, dashboards — exists to make that one number (and its trend) accurate, fast, and trustworthy.

Why this is harder than it sounds: Android aggressively throttles and kills background location callbacks (Doze mode, App Standby, OEM battery optimizations). A naive geofence implementation silently drops exit events, leaving "ghost" check-ins that never close — which quietly poisons the one number the whole app is built around. A meaningful chunk of this project's engineering effort goes into making that occupancy count trustworthy despite Android's background execution limits, not just making the UI look good.

---

🛠️ Tech Stack

The project is built entirely in Kotlin using modern Android development practices and clean architectural design patterns.

• UI Framework: Jetpack Compose (Material 3)
• Architecture: Model-View-ViewModel (MVVM) with Repositories and StateFlow
• Navigation: Jetpack Navigation Compose
• Authentication: Firebase Authentication (Email/Password & Google Sign-In)
• Database: Firebase Firestore (for storing Users, Gyms, and Sessions)
• Location & Geofencing: Google Play Services Location API (GeofencingClient, GeofenceBroadcastReceiver)
• Background Reliability: Android WorkManager (auto-checkout fallback for missed geofence exits)
• Artificial Intelligence: Google Gemini API (com.google.ai.client.generativeai.GenerativeModel) — used for crowd-pattern predictions, not generic chat
• Asynchronous Programming: Kotlin Coroutines & Flows

---

✨ Features

📍 Passive Geofence Check-In (core mechanic)

• Smart Automation: Replaces physical key fobs by using a GeofenceManager and a GeofenceBroadcastReceiver to detect when a member enters or exits the gym's perimeter — no manual check-in, no QR code.
• Session Tracking: Automatically creates or concludes a Session (recording checkInTime and checkOutTime) in the background.
• Push Notifications: Alerts users via system notifications when they have been successfully checked in or out using the GeofenceNotificationHelper.

📊 Live & Historical Occupancy (the core USP)

• Live Counts: The GymViewModel tracks and broadcasts the currentCount of members currently at a specific location, allowing users to see how busy the gym is right now — before they arrive.
• Historical Patterns: Session data is aggregated into busiest/quietest hour trends per gym, so members can plan around typical crowds, not just the live snapshot.
• Data Freshness Indicator: A "last updated X min ago" label keeps the live number honest instead of presenting a possibly-stale value as certain.

🔔 Quiet-Gym Alerts

• Firebase Cloud Messaging notification when a gym's occupancy drops below a member-set threshold — turns "check the app" into "the app tells you."

🔐 Authentication & Roles

• Multi-Role Support: Users are assigned roles as either a "member" or an "owner".
• Secure Login: Features a seamless LoginScreen and RegisterScreen supporting both standard credentials and Google Sign-In via GoogleAuthProvider.
• Role-Based Routing: Automatically redirects users to the MemberHomeScreen or OwnerHomeScreen upon login based on their account type.

🤖 GymPulse AI Insights

• Gemini Integration: Uses the AnalyticsViewModel and AnalyticsRepository to interact with a Generative AI model, turning raw session data into plain-language predictions (e.g. "This gym is usually quietest Tuesday evenings") — tied directly to the occupancy USP rather than generic fitness tips.
• Smart Dashboard: The MemberHomeScreen features a "GymPulse AI Insights" card that provides users with dynamically generated text insights, loading states, and error handling for retry attempts.

🏢 Gym Management

• Gym Selection: Members can browse and select their preferred gym location using the SelectGymScreen.
• Owner Tools: Owners can register their gym's geographic location (using LocationServices to fetch latitude and longitude coordinates) from the OwnerHomeScreen.

---

🧠 Engineering Challenges Worth Knowing About

• Background execution limits: Android's Doze mode and OEM battery optimizations can delay or drop geofence exit events, causing sessions that never close. An auto-checkout fallback via WorkManager periodically reconciles stale sessions so live occupancy doesn't silently drift wrong.
• Trust over precision: Since the entire USP depends on members trusting one number, the app favors surfacing when data was last updated over hiding uncertainty — a deliberate UX tradeoff.

---

🚀 Project Status & Roadmap

While the core geofencing and analytics features are fully scaffolded, the project is actively under development. Several UI panels and backend implementations are currently mapped out as part of the roadmap, prioritized by impact on the app's core occupancy USP:

• Auto-Checkout Fallback: Implement an Android WorkManager routine to forcefully check out users who bypass the geofence exit trigger (e.g., if a device runs out of battery), utilizing the autoCheckedOut boolean flag. (Top priority — protects the accuracy of the core occupancy feature.)
• Historical Occupancy Charts: Visualize busiest/quietest hours per gym using existing Session data (dayOfWeek, hourSlot).
• Quiet-Gym Push Notifications: FCM alert when a gym's occupancy drops below a user-defined threshold.
• Session History Panel: Add a "History" route in AppNavigation to let members view their past workouts.
• Gamification UI: Build out the leaderboard screens and repository logic to utilize the points and streakCount properties stored in the User model.
• Owner Dashboard Depth: Expand the OwnerHomeScreen beyond basic location configurations into an advanced dashboard displaying live capacity, member management lists, and analytics.
• Profile & Settings Screen: Create dedicated navigation routes for users to update profile information, switch selected gyms, or perform password resets.
• Data Validation & UI Polish: Add loading shimmers, visual feedback, and empty states across screens like SelectGymScreen.