An immersive location-based treasure hunt experience built with modern Android architecture
NYC Rat Race is a sophisticated Android application that transforms New York City into an interactive playground. Users embark on a digital scavenger hunt, solving riddles and discovering iconic landmarks through GPS-based location detection. The app demonstrates advanced Android development skills including Jetpack Compose, MVVM architecture, and real-time location services.
- GPS-Based Location Detection: Precise proximity detection (25m radius) using Haversine distance calculation
- Interactive Clue System: Engaging riddles that lead users to real NYC landmarks
- Real-Time Timer: Live tracking of hunt duration with pause/resume functionality
- Smart Hint System: Progressive hints to help users when stuck
- Modern UI/UX: Material 3 design with dynamic theming and dark mode support
- Responsive Design: Optimized for various screen sizes and orientations
UI Layer (Jetpack Compose)
↓
ViewModel Layer (StateFlow + Coroutines)
↓
Repository Layer (Data Abstraction)
↓
Data Sources (JSON + Location Services)
| Category | Technology | Purpose |
|---|---|---|
| UI Framework | Jetpack Compose | Modern declarative UI |
| Architecture | MVVM + Repository Pattern | Clean separation of concerns |
| State Management | StateFlow + Coroutines | Reactive state handling |
| Navigation | Navigation Compose | Type-safe screen navigation |
| Location | Google Play Services | GPS and location tracking |
| Data | Gson + JSON | Local data persistence |
| Theming | Material 3 | Dynamic theming support |
app/src/main/java/com/example/mobile_treasure_hunt/
├── data/
│ ├── model/Clue.kt # Data models
│ └── repository/ClueRepository.kt # Data access layer
├── location/
│ ├── Haversine.kt # Distance calculations
│ └── LocationHelper.kt # GPS integration
├── ui/
│ ├── navigation/AppNavigation.kt # Navigation logic
│ ├── screens/ # UI screens
│ └── theme/ # Material 3 theming
└── viewmodel/GameViewModel.kt # Business logic
- Real-time GPS tracking with configurable update intervals
- Haversine formula for accurate distance calculations
- Proximity-based clue validation (25-meter radius)
- Background location handling with proper lifecycle management
data class GameUiState(
val allClues: List<Clue> = emptyList(),
val currentClueIndex: Int = 0,
val elapsedTime: Long = 0L,
val isTimerRunning: Boolean = false,
val huntStatus: HuntStatus = HuntStatus.NOT_STARTED,
val userLocation: Location? = null
)- ViewModel: Manages UI-related data with lifecycle awareness
- Repository Pattern: Abstracts data sources for testability
- StateFlow: Reactive state management with coroutines
- Dependency Injection: Clean separation via ViewModelFactory
- Dynamic theming support (Android 12+)
- Custom color schemes for immersive experience
- Responsive typography and spacing
- Dark mode compatibility
- Start Screen: Welcome interface with game rules
- Clue Screen: Active hunt with timer and location detection
- Solved Screen: Celebration and location information
- Completion Screen: Final results and replay option
- Proximity Detection: Automatic clue validation when near targets
- Hint System: Progressive assistance without spoilers
- Timer Management: Pause/resume functionality
- Error Handling: Graceful location permission and GPS issues
- Android Studio (Latest stable version)
- Android SDK API Level 24+ (Android 7.0)
- Physical device or emulator with GPS support
- Clone the repository:
git clone https://github.com/jscervantes/nyc-rat-race
- Open the project in Android Studio (latest stable version recommended).
- Let Gradle sync and download dependencies.
- Connect an Android device or start an Android Emulator (API level 21+ recommended, API level 31+ for Dynamic Color).
- Select the
appconfiguration and click the "Run" button (green play icon).
- Min SDK: 24 (Android 7.0)
- Target SDK: 36 (Android 14)
- Compile SDK: 36
- Kotlin: 2.0.21
- Gradle: 8.11.1
Built with modern Android development practices