# phuhuynhh/moviefindr architecture

> Architecture diagram of the GitHub repository phuhuynhh/moviefindr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phuhuynhh/moviefindr
- Repository: https://github.com/phuhuynhh/moviefindr

## Overview

##### Project Type and Purpose
- This is a native Android mobile application (“Movie Findr”) written in Kotlin, using Jetpack Compose for UI.
- It follows Clean Architecture: three Gradle modules named app (presentation), domain (business logic), and data (data access).
- It fetches movie data from The Movie Database (TMDB) API, caches results in Room, and supports offline mode.

##### Overall Architectural Pattern
- Presentation layer (app module) depends on domain.
- Domain layer defines use-case interfaces and business models.
- Data layer implements repositories that satisfy domain interfaces, providing remote (Retrofit+OkHttp+Moshi) and local (Room) data sources.
- Dependency injection modules wire everything together.

##### Main Components
A. Mobile Client (Android Device)
- Presentation / UI
– Jetpack Compose screens & components
– ViewModels (extend BaseViewModel)
– Navigation graph (AppNavGraph, MainNavGraph)
- DI Container
– Modules: AppModule, MoshiModule, OkHttpClientModule, RetrofitModule, RepositoryModule, StorageModule
B. Domain Layer (jar module)
- Use cases: GetMoviesUseCase, GetMovieDetailUseCase
- Repository interfaces: MoviesRepository, MovieDetailRepository
- Models: MovieInfo, MovieDetailInfo, PaginatedList, DataResult, NetworkError
C. Data Layer (aar module)
- Remote Data Source
– Retrofit / Moshi
– ApiService + AuthorizationParamInterceptor
– NetworkObserver
- Local Data Source
– Room database (WhatMovieDatabase)
– DAOs: MoviesDao, MoviePageDao, MovieDetailEntityDao
- Repositories implementing domain interfaces
– MoviesRepositoryImpl (decides fetch-from-cache vs fetch-from-network)
– MovieDetailRepositoryImpl
D. External Service
- TMDB REST API (requires API token stored in gradle.properties)

##### Relationships and Data Flow
1. UI Layer triggers an action (e.g., “Load Movies”)
2. ViewModel calls the corresponding UseCase in domain
3. UseCase invokes repository interface
4. RepositoryImpl chooses:
- Remote call: Retrofit → TMDB API → JSON → Moshi → domain models
- Local call: Room DAO → Entities → mappers → domain models
5. Domain models returned to ViewModel
6. ViewModel maps domain models → UI models (UiMovie, UiMovieDetail)
7. Compose UI observes state flows and renders screens
8. Offline scenario: repository detects no network via NetworkObserver and falls back to Room cache

##### Important Architectural Patterns & Principles
- Clean / Hexagonal Architecture (clear module boundaries, dependency inversion)
- Single Responsibility: each layer handles its own concern (UI vs business vs data)
- Repository pattern for data abstraction
- Dependency injection for decoupling and testability
- MVVM in presentation (ViewModel + Compose UI)
- Coroutines + DispatchersProvider to control threading

##### Technology & Framework Highlights
- Kotlin, Jetpack Compose, AndroidX Navigation
- Dagger-style DI modules (could be Koin or Hilt)
- Retrofit + OkHttp + Moshi for networking
- Room for local persistence
- Coroutines for async
- Unit tests in domain/data, AndroidTests in app

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Android App"
    subgraph "Presentation Layer"
      subgraph "DI Container"
        AppModule["AppModule"]:::di
        MoshiModule["MoshiModule"]:::di
        OkHttpClientModule["OkHttpClientModule"]:::di
        RetrofitModule["RetrofitModule"]:::di
        RepositoryModule["RepositoryModule"]:::di
        StorageModule["StorageModule"]:::di
      end
      UI_screens["Compose UI"]:::ui
      HomeVM["HomeViewModel"]:::ui
      DetailVM["MovieDetailViewModel"]:::ui
      BaseVM["BaseViewModel"]:::ui
      AppNav["AppNavGraph"]:::ui
      MainNav["MainNavGraph"]:::ui
    end
    subgraph "Domain Layer"
      UseGetMovies["GetMoviesUseCase"]:::domain
      UseGetDetail["GetMovieDetailUseCase"]:::domain
      RepoIntMovies["MoviesRepository"]:::domain
      RepoIntDetail["MovieDetailRepository"]:::domain
      Model_MI["MovieInfo"]:::domain
      Model_MDI["MovieDetailInfo"]:::domain
      Model_PL["PaginatedList"]:::domain
      Model_DR["DataResult"]:::domain
      Model_NE["NetworkError"]:::domain
    end
    subgraph "Data Layer"
      subgraph "Remote DataSource"
        ApiService["ApiService"]:::data
        AuthInterceptor["AuthorizationParamInterceptor"]:::data
        NetObserver["NetworkObserver"]:::data
      end
      subgraph "Local DataSource"
        DB["WhatMovieDatabase"]:::data
        MoviesDao["MoviesDao"]:::data
        PageDao["MoviePageDao"]:::data
        DetailDao["MovieDetailEntityDao"]:::data
      end
      subgraph "Repositories"
        MoviesRepoImpl["MoviesRepositoryImpl"]:::data
        DetailRepoImpl["MovieDetailRepositoryImpl"]:::data
      end
    end
  end
  TMDB["TMDB API"]:::external

  %% Dependency Injection
  AppModule --> HomeVM
  AppModule --> DetailVM
  MoshiModule --> ApiService
  OkHttpClientModule --> ApiService
  RetrofitModule --> ApiService
  RepositoryModule --> MoviesRepoImpl
  RepositoryModule --> DetailRepoImpl
  StorageModule --> DB

  %% Presentation to Domain
  UI_screens --> HomeVM
  UI_screens --> DetailVM
  BaseVM --> HomeVM
  BaseVM --> DetailVM
  HomeVM --> UseGetMovies
  DetailVM --> UseGetDetail

  %% Domain to Data
  UseGetMovies --> RepoIntMovies
  UseGetDetail --> RepoIntDetail
  RepoIntMovies --> MoviesRepoImpl
  RepoIntDetail --> DetailRepoImpl

  %% Data flows
  MoviesRepoImpl --> ApiService
  MoviesRepoImpl --> MoviesDao
  MoviesRepoImpl --> PageDao
  DetailRepoImpl --> ApiService
  DetailRepoImpl --> DetailDao
  ApiService --> AuthInterceptor
  ApiService --> NetObserver
  ApiService --> TMDB
  MoviesDao --> DB
  PageDao --> DB
  DetailDao --> DB

  %% Click Events
  click UI_screens "https://github.com/phuhuynhh/moviefindr/tree/main/app/src/main/java/com/whatmovie/app/compose/ui"
  click HomeVM "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/ui/screens/main/home/HomeViewModel.kt"
  click DetailVM "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/ui/screens/main/detail/MovieDetailViewModel.kt"
  click BaseVM "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/ui/base/BaseViewModel.kt"
  click AppNav "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/ui/AppNavGraph.kt"
  click MainNav "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/ui/screens/main/MainNavGraph.kt"
  click AppModule "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/di/modules/AppModule.kt"
  click MoshiModule "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/di/modules/MoshiModule.kt"
  click OkHttpClientModule "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/di/modules/OkHttpClientModule.kt"
  click RetrofitModule "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/di/modules/RetrofitModule.kt"
  click RepositoryModule "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/di/modules/RepositoryModule.kt"
  click StorageModule "https://github.com/phuhuynhh/moviefindr/blob/main/app/src/main/java/com/whatmovie/app/compose/di/modules/StorageModule.kt"
  click UseGetMovies "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/usecases/GetMoviesUseCase.kt"
  click UseGetDetail "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/usecases/GetMovieDetailUseCase.kt"
  click RepoIntMovies "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/repositories/MoviesRepository.kt"
  click RepoIntDetail "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/repositories/MovieDetailRepository.kt"
  click Model_MI "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/models/MovieInfo.kt"
  click Model_MDI "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/models/MovieDetailInfo.kt"
  click Model_PL "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/models/PaginatedList.kt"
  click Model_DR "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/models/DataResult.kt"
  click Model_NE "https://github.com/phuhuynhh/moviefindr/blob/main/domain/src/main/java/com/whatmovie/app/compose/domain/models/NetworkError.kt"
  click ApiService "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/remote/services/ApiService.kt"
  click AuthInterceptor "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/remote/authenticators/AuthorizationParamInterceptor.kt"
  click NetObserver "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/remote/services/NetworkObserver.kt"
  click DB "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/database/WhatMovieDatabase.kt"
  click MoviesDao "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/database/dao/MoviesDao.kt"
  click PageDao "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/database/dao/MoviePageDao.kt"
  click DetailDao "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/database/dao/MovieDetailEntityDao.kt"
  click MoviesRepoImpl "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/repositories/MoviesRepositoryImpl.kt"
  click DetailRepoImpl "https://github.com/phuhuynhh/moviefindr/blob/main/data/src/main/java/com/whatmovie/app/compose/data/repositories/MovieDetailRepositoryImpl.kt"

  %% Styles
  classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef domain fill:#90EE90,stroke:#000,stroke-width:1px
  classDef data fill:#FFA500,stroke:#000,stroke-width:1px
  classDef di fill:#D8BFD8,stroke:#000,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
