https://github.com/spongycode/song-quest
A fully functional Android quiz game featuring audio challenges, leaderboards, and multiple categories.
https://github.com/spongycode/song-quest
android clean-architecture firebase game-development hilt jetpack-compose kotlin ktor-client mongodb music mvvm
Last synced: about 22 hours ago
JSON representation
A fully functional Android quiz game featuring audio challenges, leaderboards, and multiple categories.
- Host: GitHub
- URL: https://github.com/spongycode/song-quest
- Owner: spongycode
- Created: 2024-01-06T21:59:07.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-11-13T15:33:02.000Z (6 months ago)
- Last Synced: 2025-11-13T17:24:18.806Z (6 months ago)
- Topics: android, clean-architecture, firebase, game-development, hilt, jetpack-compose, kotlin, ktor-client, mongodb, music, mvvm
- Language: Kotlin
- Homepage: https://songquest.vercel.app
- Size: 31.1 MB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚧 Under Development
This repository is currently in active development to support **multiplatform** targets:
- Android
- iOS
- Web
For more details and latest progress, check out the [`multiplatform`](https://github.com/spongycode/song-quest/tree/multiplatform) branch.
Song Quest 🎶
A fully functional Android quiz game featuring audio challenges, leaderboards, and multiple categories.
## Installation
[
](https://indusapp.store/pad93i9h)
[
](https://github.com/spongycode/song-quest/releases/latest)
## Features 🌟
### Authentication
- Login: Users can securely log in to their accounts.
- Registration: New users can easily create accounts to start playing.
- Password Reset: Reset your password through the app, and a one-time password will be sent to your email.
### Gameplay
- Guess the Answer: Test your knowledge by guessing the correct answer listening the audio.-
- Multiple Categories: Choose from various exciting categories, each with tailored questions for an engaging gameplay experience.
- Limited Attempts: You have limited wrong attempts in each game play.
- Leaderboard: Compete with others and view the consistent leaderboard based on the highest scores.
- Game History: Track your progress by reviewing the history of games you've played.
### Profile
- Update Profile: Customize your profile details in the basic settings.
## Screenshots 📷
## Video Preview 📹
[![Video Preview]()](https://github.com/spongycode/song-quest/assets/65273165/08f1f156-683c-49bd-9451-53132774e2b9)
## App Flow & Architecture 👷♂️
## Tech Stack 🛠️
- [Kotlin](https://kotlinlang.org/): Primary language for Android app development.
- [NextJS API Backend](https://nextjs.org/docs/pages/building-your-application/routing/api-routes): Utilizes NextJS for a powerful and flexible backend. See [here](https://github.com/spongycode/song-quest-backend) for implementation details.
- [Firebase](https://firebase.google.com/): Used for storing audio files, providing a scalable and reliable cloud storage solution.
- [MongoDB](https://www.mongodb.com/): Employed for a NoSQL database, handling normal query data storage efficiently.
- [Clean Architecture Pattern](https://developer.android.com/topic/architecture): Organizes code into distinct layers (UI, Domain, Data) for modularity and maintainability in Android app development.
- [MVVM](https://developer.android.com/topic/libraries/architecture/viewmodel): Architecture pattern (Model-View-ViewModel) for a structured and maintainable app design.
- [Hilt](https://developer.android.com/training/dependency-injection/hilt-android): Simplifies dependency injection in Android apps.
- [Ktor client](https://ktor.io/docs/getting-started-ktor-client.html): Facilitates asynchronous client-server communication.
- [Jetpack Compose](https://developer.android.com/jetpack/compose): Declarative UI toolkit for native Android apps.
- [Compose Navigation](https://developer.android.com/jetpack/compose/navigation): Navigation component for Jetpack Compose.
- [Material 3](https://m3.material.io/): Latest Material Design system for unified app aesthetics.
- [Datastore](https://developer.android.com/topic/libraries/architecture/datastore): Modern local data storage solution.
## Backend details
### Routes `api/mobile`
- `/gameplay`
- `/create`: Create a new game.
- `/question`: Upload new questions and fetch questions category-wise.
- `/check`: Check the correct answer for the question.
- `/highscore`: Fetch the leaderboard category-wise.
- `/history`: Fetch the user's game history.
- `/save`: Save the game.
- `/users`
- `/register`: Register new users.
- `/login`: Login users.
- `/profile`: Get and update profile details.
- `/resetPassword`: Reset password and send OTP via email.
### Data Models
- Game Model
```json
{
"game": {
"player": "String (required)",
"score": "Number (default: 0.0)",
"accurate": "Number (default: 0)",
"questionsId": "Array of ObjectId (ref: 'Question')",
"category": "String (required)",
"isGameSaved": "Boolean (default: false)",
"createdAt": "Date (default: Current timestamp)",
"expireAt": "Date (default: Current timestamp)"
}
}
```
**Note:** This project utilizes a [TTL (Time-to-Live) index](https://www.mongodb.com/docs/manual/core/index-ttl/) to automatically delete unsaved games after `300 seconds`. The index is based on the `expireAt` field and is configured to delete games where `isGameSaved` is false. This ensures efficient cleanup of temporary data.
- Question Model
```json
{
"question": {
"title": "String (required)",
"songUrl": "String",
"options": [
{
"optionid": "Number (required)",
"value": "String (required)"
}
],
"correctOptionId": "Number (required)",
"category": "String (required)",
"totalAttempts": "Number (default: 0)",
"difficulty": "Number (default: 0.5)",
"altText": "String (default: '')",
"createdAt": "Date (default: Current timestamp)"
}
}
```
- User Model
```json
{
"user": {
"username": "String (required, unique, trim)",
"email": "String (required, unique, trim)",
"imageUrl": "String",
"password": "String (required, 'Password is required')",
"gamesPlayed": "Number (default: 0)",
"forgotPasswordToken": "String",
"forgotPasswordTokenExpiry": "Date",
"refreshToken": "String",
"createdAt": "Date (default: Current timestamp)"
}
}
```
### Scoring
The score for each question is determined using the formula below.
```math
score = max(0, -0.00057 \times timeTaken^3 + 0.037 \times timeTaken^2 - 0.96 \times timeTaken + 10)
```
## Getting Started 🚀
To begin using Song Quest, clone the repository and open the project in Android Studio. Clone the backend server from [here](https://github.com/spongycode/song-quest-backend) and fill up the required environment variables mentioned in the `sample.env` file to set up your own server.
## Contributing 🤝
Feel free to contribute to this project by submitting issues, pull requests, or providing valuable feedback. Your contributions are always welcome! 🙌
## License 📄
Song Quest is released under the [MIT License](https://opensource.org/licenses/MIT). Feel free to modify or add to this list based on the specific features of your app.
## Happy coding! 🎉👩💻👨💻