# anoopmaddasseri/githubtrendingrepos architecture

> Architecture diagram of the GitHub repository anoopmaddasseri/githubtrendingrepos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anoopmaddasseri/githubtrendingrepos
- Repository: https://github.com/anoopmaddasseri/githubtrendingrepos

## Overview

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: [`app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepositoryViewModel.kt`](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepositoryViewModel.kt) (Repo VM), [`app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchActivity.kt`](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchActivity.kt) (Search Screen), [`data/src/main/kotlin/com/mvvmclean/trendingrepos/data/source/TrendingRepoSearchDataSource.kt`](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/source/TrendingRepoSearchDataSource.kt) (Data Source), [`data/src/main/kotlin/com/mvvmclean/trendingrepos/data/repository/TrendingRepoSearchRepository.kt`](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/repository/TrendingRepoSearchRepository.kt) (Repo Impl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["app"]
  node_app_application["App"]
  node_app_activity["Search Screen<br/>Activity"]
  node_app_viewmodel["Repo VM<br/>ViewModel"]
  node_app_uistate["UI State<br/>state base<br/>[UiState.kt]"]
  node_app_adapter["List Adapter<br/>RecyclerView adapter"]
  node_app_mapper["UI Mapper<br/>presentation mapper"]
  node_app_models["UI Models<br/>presentation models"]
  node_app_di{{"App DI<br/>Dagger graph<br/>[AppComponent.kt]"}}
end

subgraph group_domain["domain"]
  node_domain_model["Trending Repo<br/>domain model<br/>[TrendingRepo.kt]"]
  node_domain_contract["Repo Contract<br/>repository contract"]
  node_domain_usecase["Use Case"]
end

subgraph group_data["data"]
  node_data_repository["Repo Impl<br/>repository impl"]
  node_data_source["Data Source<br/>source coordinator"]
  node_data_api["API Service<br/>retrofit service"]
  node_data_http["HTTP Stack<br/>client config<br/>[HttpClient.kt]"]
  node_data_db[("Room DB<br/>database<br/>[AppDatabase.kt]")]
  node_data_dao["Repo DAO<br/>[TrendingRepoDao.kt]"]
  node_data_net_model["API Models<br/>response models"]
  node_data_entity["Repo Entity<br/>room entity"]
  node_data_mapper_net["Json Map<br/>mapper<br/>[JsonToEntity.kt]"]
  node_data_mapper_domain["Domain Map<br/>mapper<br/>[EntityToDomain.kt]"]
end

node_app_activity -->|"observes"| node_app_viewmodel
node_app_viewmodel -->|"emits"| node_app_uistate
node_app_viewmodel -->|"calls"| node_domain_usecase
node_app_viewmodel -->|"maps"| node_app_mapper
node_app_mapper -->|"creates"| node_app_models
node_app_activity -->|"renders"| node_app_adapter
node_app_activity -->|"injected by"| node_app_di
node_app_di -->|"bootstraps"| node_app_application
node_app_di -->|"provides"| node_app_viewmodel
node_domain_usecase -->|"depends on"| node_domain_contract
node_domain_usecase -->|"returns"| node_domain_model
node_data_repository -->|"implements"| node_domain_contract
node_data_repository -->|"coordinates"| node_data_source
node_data_source -->|"fetches from"| node_data_api
node_data_source -->|"reads/writes"| node_data_db
node_data_api -->|"uses"| node_data_http
node_data_db -->|"exposes"| node_data_dao
node_data_source -->|"maps"| node_data_mapper_net
node_data_mapper_net -->|"consumes"| node_data_net_model
node_data_mapper_net -->|"produces"| node_data_entity
node_data_mapper_domain -->|"consumes"| node_data_entity
node_data_mapper_domain -->|"produces"| node_domain_model
node_data_repository -->|"maps"| node_data_mapper_domain
node_app_activity -->|"starts with"| node_app_application

click node_app_application "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/GithubTrendingReposApplication.kt"
click node_app_activity "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchActivity.kt"
click node_app_viewmodel "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepositoryViewModel.kt"
click node_app_uistate "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/commons/UiState.kt"
click node_app_adapter "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchResultAdapter.kt"
click node_app_mapper "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/mappers/DomainToPresentationMapper.kt"
click node_app_models "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/models/TrendingRepositoryUiModel.kt"
click node_app_di "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/di/AppComponent.kt"
click node_domain_model "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/models/TrendingRepo.kt"
click node_domain_contract "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/repository/ITrendingRepoSearchRepository.kt"
click node_domain_usecase "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/usecases/TrendingRepositoryUseCase.kt"
click node_data_repository "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/repository/TrendingRepoSearchRepository.kt"
click node_data_source "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/source/TrendingRepoSearchDataSource.kt"
click node_data_api "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/TrendingRepoApiService.kt"
click node_data_http "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/HttpClient.kt"
click node_data_db "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/AppDatabase.kt"
click node_data_dao "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/TrendingRepoDao.kt"
click node_data_net_model "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/response/TrendingRepoResponse.kt"
click node_data_entity "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/entity/TrendingRepoEntity.kt"
click node_data_mapper_net "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/JsonToEntity.kt"
click node_data_mapper_domain "https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/EntityToDomain.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_application,node_app_activity,node_app_viewmodel,node_app_uistate,node_app_adapter,node_app_mapper,node_app_models,node_app_di toneBlue
class node_domain_model,node_domain_contract,node_domain_usecase toneAmber
class node_data_repository,node_data_source,node_data_api,node_data_http,node_data_db,node_data_dao,node_data_net_model,node_data_entity,node_data_mapper_net,node_data_mapper_domain toneMint
```

## Components

### app

Android UI, MVVM, and dependency injection

- [App](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/GithubTrendingReposApplication.kt): Application · Process entrypoint and app-wide setup · `app/src/main/kotlin/com/mvvmclean/trendingrepos/GithubTrendingReposApplication.kt`
- [Search Screen](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchActivity.kt): Activity · Main UI screen for trending repo search and sorting · `app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchActivity.kt`
- [Repo VM](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepositoryViewModel.kt): ViewModel · Bridges UI state and domain use case · `app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepositoryViewModel.kt`
- [UI State](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/commons/UiState.kt): state base · Shared loading/success/error state model and ViewModel support · `app/src/main/kotlin/com/mvvmclean/trendingrepos/commons/UiState.kt`
- [List Adapter](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchResultAdapter.kt): RecyclerView adapter · Renders trending repository rows · `app/src/main/kotlin/com/mvvmclean/trendingrepos/features/trendingrepo/TrendingRepoSearchResultAdapter.kt`
- [UI Mapper](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/mappers/DomainToPresentationMapper.kt): presentation mapper · Converts domain models into display models · `app/src/main/kotlin/com/mvvmclean/trendingrepos/mappers/DomainToPresentationMapper.kt`
- [UI Models](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/models/TrendingRepositoryUiModel.kt): presentation models · Sort and item models used by the screen · `app/src/main/kotlin/com/mvvmclean/trendingrepos/models/TrendingRepositoryUiModel.kt`
- [App DI](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/app/src/main/kotlin/com/mvvmclean/trendingrepos/di/AppComponent.kt): Dagger graph · Application, activity, and ViewModel wiring · `app/src/main/kotlin/com/mvvmclean/trendingrepos/di/AppComponent.kt`

### domain

Pure business rules, models, and contracts

- [Trending Repo](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/models/TrendingRepo.kt): domain model · Business-facing repository representation · `domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/models/TrendingRepo.kt`
- [Repo Contract](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/repository/ITrendingRepoSearchRepository.kt): repository contract · Abstract source of trending repositories · `domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/repository/ITrendingRepoSearchRepository.kt`
- [Use Case](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/domain/src/main/kotlin/com/mvvmclean/trendingrepos/domain/usecases/TrendingRepositoryUseCase.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](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/repository/TrendingRepoSearchRepository.kt): repository impl · Coordinates remote fetch, cache, and mapping · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/repository/TrendingRepoSearchRepository.kt`
- [Data Source](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/source/TrendingRepoSearchDataSource.kt): source coordinator · Selects and combines remote and local data sources · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/source/TrendingRepoSearchDataSource.kt`
- [API Service](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/TrendingRepoApiService.kt): retrofit service · GitHub Trending HTTP boundary · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/TrendingRepoApiService.kt`
- [HTTP Stack](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/HttpClient.kt): client config · OkHttp client and logging interceptor · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/api/HttpClient.kt`
- [Room DB](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/AppDatabase.kt): database · Local cache database · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/AppDatabase.kt`
- [Repo DAO](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/TrendingRepoDao.kt): dao · Persistence access for cached trending repos · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/db/TrendingRepoDao.kt`
- [API Models](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/response/TrendingRepoResponse.kt): response models · Network response shapes from the API · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/response/TrendingRepoResponse.kt`
- [Repo Entity](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/entity/TrendingRepoEntity.kt): room entity · Cached storage model · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/models/entity/TrendingRepoEntity.kt`
- [Json Map](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/JsonToEntity.kt): mapper · Maps API response to database entity · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/JsonToEntity.kt`
- [Domain Map](https://github.com/anoopmaddasseri/githubtrendingrepos/blob/master/data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/EntityToDomain.kt): mapper · Maps entity data into domain models · `data/src/main/kotlin/com/mvvmclean/trendingrepos/data/mappers/EntityToDomain.kt`

## Connections

- 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
