🎥 RandomBoxd 🍿

RandomBoxd is a Compose Multiplatform project designed to fetch a random movie from a Letterboxd user's watchlists or custom lists. This app is built for Android and iOS devices. 📱🎬

📲 Download

• Android (phones & tablets): Available now on Google Play.
• iOS (iPhone & iPad): Coming soon to the App Store.

✨ Features

• 🎲 Fetch a random movie from a Letterboxd user's watchlist or custom lists.
• 📱 Supports Android and iOS platforms.
• 🔗 Seamless deep linking with the Letterboxd app.
• 🔍 Intuitive user search functionality.
• 🏷️ Stores and displays previously entered UserNames locally via Room, shown as tappable tags for quick reuse or deletion.
• ∩∪ Intersection & Union → Combine multiple users' watchlists and pick a random movie either from their shared movies (Intersection) or from the merged pool (Union).
• 🎭 Genre Filters → Narrow results to one or more genres at once. Works in both single-user and multi-user modes.

🧙‍♂️ Watch the Magic

🏗️ Project Architecture

This project follows the Clean Architecture principles to ensure a scalable and maintainable codebase. For a detailed breakdown of layers, patterns, conventions, and technical decisions, see the Architecture Document.

🏛️ KMP Structure

• /composeApp is for code that will be shared across your Compose Multiplatform applications.

  • commonMain contains code common for all targets.
  • Other folders include platform-specific code (e.g., iosMain for iOS-specific code like CoreCrypto integration).

• /iosApp contains iOS applications.

  • Even if you're sharing UI with Compose Multiplatform, this folder is the entry point for the iOS app.
  • This is also where you can add SwiftUI code if needed.

🔧 Tech Stack

• Compose Multiplatform (CMP) - Shared logic for Android and iOS with Compose.
• Jetpack Compose - UI for Android.
• Ktor - Network requests.
• Coroutines & Flow - Asynchronous programming.
• Koin - Dependency Injection.
• Coil - Image loading.
• Room - Database.
• Ksoup - HTML parsing.
• Navigation Compose - Jetpack Compose navigation.
• Kotlinx Serialization - JSON serialization.
• Spotless - Code formatting.
• Junit5 - Unit testing.
• Turbine - State testing.
• Jacoco - Code coverage.

🌍 Localization Support

RandomBoxd is built with full localization support, allowing the app to be translated into any language.

• 🏳️ Uses Kotlin Multiplatform's localization tools for seamless translations.
• 📝 Supports dynamic text updates based on user preferences.
• 🌐 Easily adaptable for different regions and languages.

✅ Testing

RandomBoxd's codebase is tested with:

• 🧪 JUnit5 for unit tests.
• 🌊 Turbine for verifying Kotlin Flow emissions and state changes.
• 🔌 Ktor Client Mock for mocking and testing network requests.
• 📈 Jacoco to measure and ensure code coverage across the project.

📸 Screenshots

🤖 Android

🍏 iOS

🔍 Search user lists & Deeplinking

🔗 Intersection & Union of Users' Watchlists

RandomBoxd allows you to combine multiple users' watchlists by holding the Submit button or selecting multiple user tags.
From there, a single random movie is chosen based on two available modes:

• ∩ Intersection → Selects only movies that are present in every selected user's watchlist.
• ∪ Union → Combines all movies from the selected users' watchlists and randomly picks one from the full collection.

✍️ See Previous UserName Prompts

🎭 Genre Filters

RandomBoxd lets you narrow your random pick to specific genres using the Genre button next to the search bar.
Select one or more genres and the app will only consider movies that match your selection:

• Single genre → e.g. only Horror movies from your watchlist.
• Multiple genres → combines genres so any matching movie can be picked.
• Reset anytime → clear the filter with one tap to go back to the full list.

Works seamlessly with both single-user and multi-user (Intersection & Union) modes.

🚀 Getting Started

1. Clone the repository:

   git clone https://github.com/Nacchofer31/RandomBoxd.git

2. Open the project in Android Studio (latest version with CMP Plugin).

3. Run on an Android Emulator or an iOS Simulator.

4. Run spotless commmands:

   ./gradlew :composeApp:spotlessApply 

5. Generate jacoco reports:

   ./gradlew :composeApp:jacocoTestReport

6. Start selecting random movies from Letterboxd lists! 🎞️

🤝 Contributing

Feel free to open issues or submit pull requests to improve the project. 🛠️

📜 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---

Enjoy RandomBoxd and never struggle to pick a movie again! 🎬🍀