How anoopmaddasseri/githubtrendingrepos works
1. Overall shape
- This is an Android app organized as a 3-module clean architecture project:
- app: presentation/UI layer
- domain: business rules and contracts
- data: network, persistence, and repository implementation
- The main user-facing feature is listing and sorting GitHub trending repositories from the GitHub Trending API.
2. Presentation boundary (app module)
- The app module contains the Android-specific layer: GithubTrendingReposApplication, activities, RecyclerView adapter, custom views, UI models, and Dagger wiring.
- The primary screen is TrendingRepoSearchActivity, which binds the UI and reacts to state coming from TrendingRepositoryViewModel.
- UI rendering is driven by UiState / UiStateViewModel, so loading, success, and error are handled as explicit view states rather than ad hoc flags.
3. MVVM flow
- TrendingRepoSearchActivity observes the ViewModel and updates the list, loading placeholders, retry/error UI, and sort interactions.
- TrendingRepositoryViewModel is the bridge between the UI and business logic.
- The ViewModel depends on the domain use case rather than directly calling network or database code, which keeps the presentation layer isolated.
4. Domain boundary (domain module)
- The domain module is intentionally small and framework-free.
- It contains:
- TrendingRepo domain model
- ITrendingRepoSearchRepository repository contract
- TrendingRepositoryUseCase
- This layer owns the business-facing representation and orchestration logic, while remaining independent of Android, Retrofit, or Room.
5. Data boundary (data module)
- The data module owns external I/O and storage concerns:
- Retrofit API client and service
- Room database and DAO
- entity/response models
- repository implementation
- mapping between network/entity/domain shapes
- This module is the only place that should know about the GitHub Trending API, local cache schema, and HTTP/database details.
6. Primary data flow
- The normal flow is:
- UI action in TrendingRepoSearchActivity
- ViewModel requests data through TrendingRepositoryUseCase
- use case calls ITrendingRepoSearchRepository
- data repository fetches from remote API and/or local database
- results are mapped into domain models
- ViewModel maps domain data into presentation UI models
- activity renders the final list
- The presence of Room and a scheduled sync strategy indicates the app can serve cached data when offline and refresh in the background.
7. Network subsystem
- TrendingRepoApiService plus HttpClient and LoggingInterceptor form the HTTP stack.
- Moshi appears to be used for JSON parsing, and Retrofit is the service boundary for API calls.
- The app also includes a network_security_config, which suggests deliberate network policy configuration.
8. Persistence subsystem
- AppDatabase and TrendingRepoDao define the local cache.
- TrendingRepoEntity is the storage model, separate from both API response objects and domain models.
- Mapping classes like JsonToEntity and EntityToDomain make the data transformations explicit and keep schemas decoupled.
9. Dependency injection and composition
- Dagger is used to wire the app together.
- AppComponent is the top-level graph, with modules for application setup, API, view models, activity binding, and feature-specific bindings.
- The app module owns presentation DI, while the data module contributes infrastructure implementations.
10. Presentation models and mapping
- The app layer defines TrendingRepositoryUiModel, SortType, and BaseUiModel to shape data for display.
- DomainToPresentationMapper converts domain objects into UI-ready models.
- This keeps the RecyclerView adapter and activity free from business/data translation logic.
11. UI composition
- The screen is built from XML layouts such as activity_trending_repository.xml, item rows, toolbar, loading placeholders, and error status views.
- TrendingRepoSearchResultAdapter handles list rendering.
- Custom widgets (CustomButton, CustomTextView) and utility classes support consistent styling and behavior.
12. Testing architecture
- Unit tests live under app/src/test and focus on ViewModel behavior and supporting helpers.
- Instrumentation tests live under app/src/androidTest and use fake DI modules and a mock application/component setup.
- MockWebServer-style request dispatching and sample data files indicate integration tests verify the UI/data pipeline without hitting the real API.
13. Architectural boundaries to reflect in a diagram
- The clearest separations are:
- UI/MVVM in app
- business contracts and use cases in domain
- API + Room + repository implementation in data
- Data is transformed at each boundary: API response → entity → domain model → UI model.
- External dependencies terminate in the data layer; the domain layer stays pure.
Main entry points: TrendingRepositoryViewModel.kt Repo VM · TrendingRepoSearchActivity.kt Search Screen · TrendingRepoSearchDataSource.kt Data Source · TrendingRepoSearchRepository.kt Repo Impl
Components 21
app
Android UI, MVVM, and dependency injection
- App · Process entrypoint and app-wide setup
app/src/main/kotlin/com/mvvmclean/trendingrepos/GithubTrendingReposApplication.kt - Search Screen · Main UI screen for trending repo search and sorting
app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchActivity.kt - Repo VM · Bridges UI state and domain use case
app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepositoryViewModel.kt - UI State · Shared loading/success/error state model and ViewModel support
app/src/main/kotlin/com/mvvmclean/trendingrepos/commons/UiState.kt - List Adapter · Renders trending repository rows
app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchResultAdapter.kt - UI Mapper · Converts domain models into display models
app/src/main/kotlin/com/mvvmclean/trendingrepos/mappers/DomainToPresentationMapper.kt - UI Models · Sort and item models used by the screen
app/src/main/kotlin/com/mvvmclean/trendingrepos/models/TrendingRepositoryUiModel.kt - App DI · Application, activity, and ViewModel wiring
app/src/main/kotlin/com/mvvmclean/trendingrepos/di/AppComponent.kt
domain
Pure business rules, models, and contracts
- Trending Repo · Business-facing repository representation
domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/models/TrendingRepo.kt - Repo Contract · Abstract source of trending repositories
domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/repository/ITrendingRepoSearchRepository.kt - Use Case · Orchestrates trending repo retrieval for the UI
domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/usecases/TrendingRepositoryUseCase.kt
data
Retrofit, Room, mapping, and repository implementation
- Repo Impl · Coordinates remote fetch, cache, and mapping
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/repository/TrendingRepoSearchRepository.kt - Data Source · Selects and combines remote and local data sources
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/source/TrendingRepoSearchDataSource.kt - API Service · GitHub Trending HTTP boundary
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/TrendingRepoApiService.kt - HTTP Stack · OkHttp client and logging interceptor
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/HttpClient.kt - Room DB · Local cache database
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/AppDatabase.kt - Repo DAO · Persistence access for cached trending repos
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/TrendingRepoDao.kt - API Models · Network response shapes from the API
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/response/TrendingRepoResponse.kt - Repo Entity · Cached storage model
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/entity/TrendingRepoEntity.kt - Json Map · Maps API response to database entity
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/JsonToEntity.kt - Domain Map · Maps entity data into domain models
data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/EntityToDomain.kt
Connections 24
- Search Screen → Repo VM: observes · UI listens to ViewModel state
- Repo VM → UI State: emits · ViewModel publishes loading and result states
- Repo VM → Use Case: calls · Presentation delegates work to domain
- Repo VM → UI Mapper: maps · Domain data becomes UI-ready models
- UI Mapper → UI Models: creates · Produces presentation models
- Search Screen → List Adapter: renders · Screen binds list output to RecyclerView
- Search Screen → App DI: injected by · Activity and ViewModel are provided by Dagger
- App DI → App: bootstraps · Application owns composition root
- App DI → Repo VM: provides · ViewModel wiring is assembled in the app graph
- Use Case → Repo Contract: depends on · Use case works through repository abstraction
- Use Case → Trending Repo: returns · Business logic speaks in domain models
- Repo Impl → Repo Contract: implements · Concrete repository satisfies domain contract
- Repo Impl → Data Source: coordinates · Repository delegates retrieval strategy
- Data Source → API Service: fetches from · Remote trending API is queried through Retrofit
- Data Source → Room DB: reads/writes · Local cache is managed through Room
- API Service → HTTP Stack: uses · Retrofit is backed by configured OkHttp client
- Room DB → Repo DAO: exposes · DAO mediates access to cached records
- Data Source → Json Map: maps · Network models are converted to entities
- Json Map → API Models: consumes · Mapper starts from API response shapes
- Json Map → Repo Entity: produces · Mapper writes entity-ready cache rows
- Domain Map → Repo Entity: consumes · Entity data is read from cache layer
- Domain Map → Trending Repo: produces · Cached data is lifted into domain objects
- Repo Impl → Domain Map: maps · Repository converts stored data to domain output
- Search Screen → App: starts with · App entrypoint creates the Android process graph