Song Quest 🎶

A fully functional Android quiz game featuring audio challenges, leaderboards, and multiple categories.

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.mp4

App Flow & Architecture 👷‍♂️

Tech Stack 🛠️

• Kotlin: Primary language for Android app development.
• NextJS API Backend: Utilizes NextJS for a powerful and flexible backend. See here for implementation details.
• Firebase: Used for storing audio files, providing a scalable and reliable cloud storage solution.
• MongoDB: Employed for a NoSQL database, handling normal query data storage efficiently.
• Clean Architecture Pattern: Organizes code into distinct layers (UI, Domain, Data) for modularity and maintainability in Android app development.
• MVVM: Architecture pattern (Model-View-ViewModel) for a structured and maintainable app design.
• Hilt: Simplifies dependency injection in Android apps.
• Ktor client: Facilitates asynchronous client-server communication.
• Jetpack Compose: Declarative UI toolkit for native Android apps.
• Compose Navigation: Navigation component for Jetpack Compose.
• Material 3: Latest Material Design system for unified app aesthetics.
• Datastore: Modern local data storage solution.

Installation

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

{
  "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 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

{
  "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

{
  "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.

$$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 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. Feel free to modify or add to this list based on the specific features of your app.

Happy coding! 🎉👩‍💻👨‍💻