CMP MovieDB

A Kotlin Multiplatform (KMP) multi-module application built with Compose Multiplatform (CMP) that displays movies, TV shows and Actors information. The app targets both Android and iOS platforms with shared business logic and UI components using a modular architecture approach.

📲 Download the App

• Google Play: https://play.google.com/store/apps/details?id=com.elna.moviedb
• App Store: https://apps.apple.com/il/app/elnas-movie-db/id6756095438

🏗️ Architecture

The project follows Clean Architecture principles with a feature-based multi-module architecture:

• Multi-Module Design: Separated into core modules and feature modules for scalability
• MVI Pattern: Model-View-Intent with unidirectional data flow (UDF)
• Repository Pattern: Data layer abstraction across modules
• Dependency Injection: Koin for DI coordination across all modules
• Compose Multiplatform: Shared UI components in dedicated modules
• Room Database: Local database management
• DataStore: Typed data storage for preferences and pagination state persistence

📱 Features

Currently Implemented

• Movies: Browse popular, top-rated, and now-playing movies with infinite scroll pagination
• Movie Details: View comprehensive movie information including:
  • Overview, genres, runtime, release date, ratings
  • Budget and revenue with formatted numbers
  • Production companies and countries
  • Cast & Crew: Browse cast members with profile images and character names
  • Trailers: Watch official trailers and videos
• TV Shows: Explore popular, top-rated, and on-the-air TV shows with pagination support
• TV Show Details: View detailed information including:
  • Series information (seasons, episodes, status)
  • Networks, languages, and production details
  • Cast Section: Browse TV show cast with character information
  • Trailers: Watch official trailers and promotional videos
  • Episode runtime and air dates
• Person Details: View cast and crew member information with:
  • Biography and personal information (birthdate, birthplace)
  • Filmography with work credits
  • Profile images and known roles
• Search: Multi-type search functionality across movies, TV shows, and people with filter options
• Profile: User profile management with language and theme selection
• Cross-platform: Shared multi-module codebase for Android and iOS
• Offline Support (Currently for movies section only): Local database caching with Room for movies, movie details, cast members, and trailers
• Persistent Pagination: Pagination state persists across app restarts via DataStore
• Internationalization: Support for 4 languages (English, Hebrew, Hindi, Arabic) with dynamic switching and automatic content refresh
• Dark Mode Support: System-based dark/light theme with Material 3
• Modern UI: Material 3 design system with tile-based layouts and responsive components

🌍 Language Support

The app supports 4 languages with full UI localization:

• English (Default)
• العربية (Arabic) - Right-to-left (RTL) layout support
• עברית (Hebrew) - Right-to-left (RTL) layout support
• हिन्दी (Hindi)

Features

• Dynamic language switching from the Profile screen
• Automatic content refresh when language changes
• Language-aware cache invalidation
• RTL layout support for Arabic and Hebrew
• All string resources fully localized

📁 Project Structure

cmp-moviedb/
├── androidApp/           # Android application module (APK entry point)
│   └── src/main/         # Android-specific code (MainActivity, resources)
│
├── iosApp/               # iOS app wrapper with Xcode project
│
├── composeApp/           # Shared Compose Multiplatform library
│   ├── androidMain/      # Android-specific locale configuration
│   ├── commonMain/       # Shared app code (App.kt, navigation, DI)
│   └── iosMain/          # iOS-specific code (MainViewController, Locale, DI)
│
├── core/                 # Core shared modules
│   ├── common/           # Common infrastructure utilities (AppDispatchers)
│   ├── database/         # Room database with cross-platform drivers
│   ├── datastore/        # DataStore for preferences, pagination state, and language coordination
│   ├── model/            # Cross-feature shared models
│   ├── network/          # Ktor HTTP client and TMDB API integration
│   └── ui/               # Shared UI components, Material 3 design system, Compose resources
│
├── features/             # Feature-specific modules (each with data/domain/presentation layers)
│   ├── movies/           # Movies feature
│   │   ├── data/         # Repository implementation, data sources, Room entities
│   │   ├── domain/       # Repository interface, domain models
│   │   └── presentation/ # ViewModels, UI composables, navigation
│   ├── tv-shows/         # TV shows feature
│   │   ├── data/         # Repository implementation, in-memory data sources
│   │   ├── domain/       # Repository interface, domain models
│   │   └── presentation/ # ViewModels, UI composables, navigation
│   ├── person/           # Person details feature
│   │   ├── data/         # Repository implementation, data sources
│   │   ├── domain/       # Repository interface, domain models
│   │   └── presentation/ # ViewModels, UI composables
│   ├── search/           # Multi-type search feature
│   │   ├── data/         # Repository implementation, search strategies
│   │   ├── domain/       # Repository interface, search models
│   │   └── presentation/ # ViewModels, UI composables
│   └── profile/          # User profile and settings feature
│       └── presentation/ # ViewModels, UI composables (no data layer needed)
│
├── build-logic/          # Custom Gradle convention plugins
├── gradle/               # Gradle configuration and version catalog
└── Configuration files   # Build scripts, API keys, properties

🛠️ Technology Stack

Shared

• Kotlin Multiplatform (2.3.21) - Multi-platform development
• Compose Multiplatform - UI framework
• Koin - Dependency injection with Compose and ViewModel support
• Room - Local database with SQLite bundled driver
• DataStore - Typed data storage for preferences and pagination state
• Ktor - HTTP client for API calls with OkHttp (Android) and Darwin (iOS) engines
• Kotlin Coroutines & Flow - Asynchronous programming and reactive streams
• Coil - Image loading with Compose integration, Ktor network driver, and SVG support
• Kotlinx Serialization - JSON serialization for API responses
• Navigation 3 - Navigation 3 framework with Koin integration
• Material 3 - Design system components
• KSP - Kotlin Symbol Processing for Room code generation
• BuildKonfig - Build-time constant generation for secrets and configuration
• kotlin-test & kotlinx-coroutines-test - Multiplatform unit testing for ViewModels (runTest, UnconfinedTestDispatcher, fake repositories)

Android

• Jetpack Compose - UI toolkit
• OkHttp - Network engine for Ktor

iOS

• SwiftUI Integration - iOS native integration
• Darwin Engine - Native networking for Ktor

🚀 Getting Started

Prerequisites

• Android Studio - Ladybug or later with KMP plugin
• Xcode 15+ (for iOS development)
• JDK 17-21
• Kotlin Multiplatform Mobile plugin
• TMDB API Key (see setup instructions below)
• Minimum SDK: Android 24, iOS 13+
• Target SDK: Android 36

🔑 API Key Setup

This app uses The Movie Database (TMDB) API. You'll need to obtain an API key and configure it using BuildKonfig.

Step 1: Get TMDB API Key

1. Create TMDB Account

   • Visit The Movie Database
   • Sign up for a free account or log in if you already have one

2. Request API Key

   • Go to TMDB Developer Portal
   • Navigate to your account settings
   • Click on "API" in the sidebar
   • Click "Create" and select "Developer"
   • Fill out the application form:
     • Application Name: CMP MovieDB (or your preferred name)
     • Application Summary: Brief description of your movie app
     • Application URL: Your app's URL or GitHub repository
   • Agree to the terms and submit

3. Get Your API Key

   • Once approved, you'll receive your API key
   • Copy the API Key (v3 auth) - this is what you'll use

Step 2: Configure API Key (secrets.properties)

The project uses BuildKonfig to generate build-time constants from secrets.properties. This approach works seamlessly for both Android and iOS.

1. Create secrets.properties file in the project root directory:

   touch secrets.properties
   

2. Add your API key to secrets.properties:

   TMDB_API_KEY=your_actual_api_key_here
   

   Replace your_actual_api_key_here with your actual TMDB API key.

3. Verify .gitignore - The file should already be excluded from Git:

   /secrets.properties
   

Step 3: Build the Project

BuildKonfig will automatically generate the BuildKonfig object containing your API key during the Gradle build process. The generated constant is available to both Android and iOS platforms.

How it works:

• The core/network/build.gradle.kts reads secrets.properties at build time
• BuildKonfig generates a BuildKonfig.TMDB_API_KEY constant
• The constant is accessible across all platforms without platform-specific code

⚠️ Important:

• Never commit secrets.properties to version control (it's gitignored)
• If the API key is not set, you'll see a build warning but the app will compile
• API calls will fail at runtime if the key is missing

Running the Project

Android

# Install debug build on connected device
./gradlew :androidApp:installDebug

# Or assemble APK without installing
./gradlew :androidApp:assembleDebug

iOS

1. Open the project in Android Studio
2. Select iOS target from the run configuration
3. Run the project

Building

# Clean and build all modules
./gradlew clean build

# Build Android app
./gradlew :androidApp:build

# Build shared library
./gradlew :composeApp:build

Testing

ViewModel unit tests live in each feature module's commonTest source set (e.g. MoviesViewModelTest, ProfileViewModelTest, SearchViewModelTest). They use kotlin-test assertions, kotlinx-coroutines-test (runTest + UnconfinedTestDispatcher), and fake repositories from the core modules.

# Run all multiplatform tests for a feature module
./gradlew :features:movies:allTests
./gradlew :features:profile:allTests

ℹ️ The feature modules do not enable Android host tests (withHostTest {}), so the shared commonTest suites currently execute on the iOS simulator target via allTests. Running ./gradlew test (the Android/JVM unit-test task) will report success without executing these tests.

🏛️ Architecture Overview

Feature-Based Clean Architecture

Each feature module follows Clean Architecture with three distinct layers:

1. Presentation Layer (presentation/) - Compose UI, ViewModels, MVI state management, Navigation
2. Domain Layer (domain/) - Repository interfaces, domain models, business logic contracts
3. Data Layer (data/) - Repository implementations, data sources (network/database), caching strategies

Repository Pattern (Simplified)

The project uses a simplified repository pattern where:

• Repository: Passive data provider that returns Flow<List<T>> and handles cache invalidation
• ViewModel: Active state coordinator that manages loading/error states and UI logic
• Clear Separation: Repository maintains data integrity, ViewModel manages UI s