# marianagoto/catimagelist architecture

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

- Interactive diagram: https://gitdiagram.com/marianagoto/catimagelist
- Repository: https://github.com/marianagoto/catimagelist

## Overview

1. **Project shape**
   - Single-module Android app (`app`) written in Kotlin.
   - UI is built with classic **XML layouts + Fragments/Activities**, not Compose.
   - The repository follows a **Clean Architecture** style with clear `data`, `domain`, and `ui`/presentation boundaries.

2. **Top-level screen structure**
   - `MainActivity` is the main entry point and likely hosts the app’s primary navigation/content.
   - The UI is split into dedicated fragments for different states and views:
     - `HomeFragment`
     - `FavoritesFragment`
     - `LoadingFragment`
     - `ErrorFragment`
     - `EmptyFavoritesFragment`
   - This indicates a screen/state-driven UI where each state has its own fragment/layout.

3. **Presentation layer**
   - The presentation layer lives under `ui/` and `viewmodel/`.
   - `CatViewModel` is the central state holder for cat list/favorites screens.
   - `CatUiState` defines the UI state model used by the presentation layer.
   - `CatAdapter` renders the list of cat items, so the main content screen is list-based.

4. **Navigation and interaction model**
   - The app includes a `bottom_menu.xml`, suggesting bottom navigation between main sections such as home and favorites.
   - User actions like selecting a cat or toggling favorite status flow from the UI into the `ViewModel`, then back out as updated UI state.

5. **Domain layer**
   - The domain layer contains the business rules:
     - `CatImage` is the core domain model for a cat item.
     - `GetCatsUseCase` encapsulates loading the cat list.
     - `ToogleFavoriteUseCase` handles favorite toggling logic.
   - This layer is intentionally isolated from Android UI and networking details.

6. **Data layer**
   - `CatRepository` is the main data abstraction.
   - It sits between use cases and the remote API, hiding where cat data comes from.
   - The tree shows no database module, so persistence appears either absent or very lightweight; favorites may be handled in memory or through repository-managed state rather than a formal local storage layer.

7. **Remote/network boundary**
   - Network access is concentrated in:
     - `RetrofitClient`
     - `CatApiService`
   - This is the app’s external dependency boundary, where cat images are fetched from an API.
   - Retrofit is the key infrastructure piece shaping the data flow from remote service to repository.

8. **End-to-end data flow**
   - The typical flow is:
     - Fragment/UI event
     - `CatViewModel`
     - Use case (`GetCatsUseCase` or `ToogleFavoriteUseCase`)
     - `CatRepository`
     - `CatApiService` through `RetrofitClient`
     - Domain model (`CatImage`)
     - UI state (`CatUiState`) and adapter rendering
   - This separation is useful for diagramming because each layer has a distinct responsibility and boundary.

9. **UI state handling**
   - The app explicitly models multiple visual states:
     - loading
     - content
     - error
     - empty favorites
   - The presence of dedicated fragments plus Lottie assets in `res/raw` suggests state changes are visually emphasized rather than handled only inside one screen.

10. **Visual assets and feedback**
   - `res/raw` contains Lottie JSON files for loading/error/favorites states.
   - `res/drawable` includes cat-themed icons and illustrations.
   - These assets are part of the presentation layer and support the app’s feedback states, not core business logic.

11. **Theme and resources**
   - Theme definitions exist in two places: `ui/theme` and `ui/catlist/ui/theme`, plus app-level `res/values/themes.xml`.
   - This suggests the project has generated or duplicated theme scaffolding, but the architecture remains a standard Android resource-driven UI setup.
   - Layouts are organized per fragment and item view (`fragment_*.xml`, `item_cat.xml`).

12. **Dependency injection**
   - `CatViewModelFactory` is used for manual dependency injection.
   - There is no Hilt/Koin structure visible, so dependency wiring is likely explicit and localized to activity/fragment setup.

13. **Testing and platform scope**
   - The repo includes standard `test` and `androidTest` source sets, indicating both unit and instrumentation test support.
   - `gradle`/`wrapper` and Kotlin DSL build files show a conventional Android build pipeline.
   - The app targets Android API 24+ per the README, which influences runtime compatibility but not the core architecture.

14. **What to draw in an architecture diagram**
   - Draw three main layers: **UI/presentation**, **domain**, and **data/remote**.
   - Show `MainActivity` hosting fragments, with `CatViewModel` as the presentation orchestrator.
   - Connect use cases to `CatRepository`, then to `RetrofitClient` → `CatApiService` as the external API boundary.
   - Treat Lottie assets, XML layouts, and drawable resources as supporting presentation assets around the UI layer.

Main entry points: [`app/src/main/java/com/marianagoto/catimagelist/MainActivity.kt`](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/MainActivity.kt) (MainActivity), [`app/src/main/java/com/marianagoto/catimagelist/ui/viewmodel/CatViewModel.kt`](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/viewmodel/CatViewModel.kt) (CatViewModel), [`app/src/main/java/com/marianagoto/catimagelist/HomeFragment.kt`](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/HomeFragment.kt) (Home), [`app/src/main/res/layout/fragment_home.xml`](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/fragment_home.xml) (Fragment layouts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI / presentation"]
  node_main_activity["MainActivity<br/>activity host<br/>[MainActivity.kt]"]
  node_home_fragment["Home<br/>fragment<br/>[HomeFragment.kt]"]
  node_favorites_fragment["Favorites<br/>fragment"]
  node_loading_fragment["Loading<br/>fragment<br/>[LoadingFragment.kt]"]
  node_error_fragment["Error<br/>fragment<br/>[ErrorFragment.kt]"]
  node_empty_favorites_fragment["Empty Fav<br/>fragment"]
  node_cat_viewmodel["CatViewModel<br/>view model<br/>[CatViewModel.kt]"]
  node_cat_ui_state["CatUiState<br/>ui state<br/>[CatUiState.kt]"]
  node_cat_adapter["CatAdapter<br/>list adapter<br/>[CatAdapter.kt]"]
  node_cat_list_activity["CatListActivity<br/>secondary activity<br/>[CatListActivity.kt]"]
end

subgraph group_domain["Domain"]
  node_cat_image["CatImage<br/>domain model<br/>[CatImage.kt]"]
  node_get_cats_use_case["GetCats<br/>use case<br/>[GetCatsUseCase.kt]"]
  node_toggle_favorite_use_case["Toggle Fav<br/>use case"]
end

subgraph group_data["Data / remote"]
  node_cat_repository["CatRepository<br/>[CatRepository.kt]"]
  node_retrofit_client["RetrofitClient<br/>network client<br/>[RetrofitClient.kt]"]
  node_cat_api_service["CatApiService<br/>remote api<br/>[CatApiService.kt]"]
  node_cat_viewmodel_factory["ViewModelFactory"]
end

subgraph group_resources["Resources"]
  node_activity_main_xml["activity_main.xml<br/>layout<br/>[activity_main.xml]"]
  node_fragment_layouts["Fragment layouts<br/>[fragment_home.xml]"]
  node_item_cat_xml["item_cat.xml<br/>item layout<br/>[item_cat.xml]"]
  node_bottom_menu_xml["bottom_menu.xml<br/>[bottom_menu.xml]"]
  node_lottie_assets["Lottie assets<br/>raw assets<br/>[cat_loading.json]"]
  node_drawables["Drawables<br/>icons/illustrations<br/>[cat_icon.xml]"]
end

node_main_activity -->|"inflates"| node_activity_main_xml
node_main_activity -->|"hosts"| node_home_fragment
node_main_activity -->|"hosts"| node_favorites_fragment
node_main_activity -->|"hosts"| node_loading_fragment
node_main_activity -->|"hosts"| node_error_fragment
node_main_activity -->|"hosts"| node_empty_favorites_fragment
node_main_activity -->|"uses"| node_bottom_menu_xml
node_main_activity -->|"creates"| node_cat_viewmodel_factory
node_home_fragment -->|"observes"| node_cat_viewmodel
node_favorites_fragment -->|"observes"| node_cat_viewmodel
node_loading_fragment -->|"represents"| node_cat_ui_state
node_error_fragment -->|"represents"| node_cat_ui_state
node_empty_favorites_fragment -->|"represents"| node_cat_ui_state
node_cat_viewmodel -->|"publishes"| node_cat_ui_state
node_cat_viewmodel -->|"calls"| node_get_cats_use_case
node_cat_viewmodel -->|"calls"| node_toggle_favorite_use_case
node_cat_viewmodel -->|"feeds"| node_cat_adapter
node_get_cats_use_case -->|"depends on"| node_cat_repository
node_toggle_favorite_use_case -->|"depends on"| node_cat_repository
node_cat_repository -->|"uses"| node_retrofit_client
node_retrofit_client -->|"builds"| node_cat_api_service
node_cat_repository -->|"returns"| node_cat_image
node_cat_adapter -->|"binds"| node_item_cat_xml
node_home_fragment -->|"displays"| node_cat_adapter
node_home_fragment -->|"inflates"| node_fragment_layouts
node_favorites_fragment -->|"inflates"| node_fragment_layouts
node_loading_fragment -->|"inflates"| node_fragment_layouts
node_error_fragment -->|"inflates"| node_fragment_layouts
node_empty_favorites_fragment -->|"inflates"| node_fragment_layouts
node_home_fragment -->|"uses"| node_lottie_assets
node_error_fragment -->|"uses"| node_drawables

click node_main_activity "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/MainActivity.kt"
click node_home_fragment "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/HomeFragment.kt"
click node_favorites_fragment "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/FavoritesFragment.kt"
click node_loading_fragment "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/LoadingFragment.kt"
click node_error_fragment "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ErrorFragment.kt"
click node_empty_favorites_fragment "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/EmptyFavoritesFragment.kt"
click node_cat_viewmodel "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/viewmodel/CatViewModel.kt"
click node_cat_ui_state "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatUiState.kt"
click node_cat_adapter "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatAdapter.kt"
click node_cat_list_activity "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatListActivity.kt"
click node_cat_image "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/domain/model/CatImage.kt"
click node_get_cats_use_case "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/domain/usecase/GetCatsUseCase.kt"
click node_toggle_favorite_use_case "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/domain/usecase/ToogleFavoriteUseCase.kt"
click node_cat_repository "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/data/repository/CatRepository.kt"
click node_retrofit_client "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/data/network/RetrofitClient.kt"
click node_cat_api_service "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/data/remote/api/CatApiService.kt"
click node_cat_viewmodel_factory "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/di/CatViewModelFactory.kt"
click node_activity_main_xml "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/activity_main.xml"
click node_fragment_layouts "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/fragment_home.xml"
click node_item_cat_xml "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/item_cat.xml"
click node_bottom_menu_xml "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/menu/bottom_menu.xml"
click node_lottie_assets "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/raw/cat_loading.json"
click node_drawables "https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/drawable/cat_icon.xml"

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_main_activity,node_home_fragment,node_favorites_fragment,node_loading_fragment,node_error_fragment,node_empty_favorites_fragment,node_cat_viewmodel,node_cat_ui_state,node_cat_adapter,node_cat_list_activity toneBlue
class node_cat_image,node_get_cats_use_case,node_toggle_favorite_use_case toneAmber
class node_cat_repository,node_retrofit_client,node_cat_api_service,node_cat_viewmodel_factory toneMint
class node_activity_main_xml,node_fragment_layouts,node_item_cat_xml,node_bottom_menu_xml,node_lottie_assets,node_drawables toneRose
```

## Components

### UI / presentation

Activities, fragments, view model, and list rendering.

- [MainActivity](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/MainActivity.kt): activity host · App entry point that hosts the main UI and navigation container. · `app/src/main/java/com/marianagoto/catimagelist/MainActivity.kt`
- [Home](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/HomeFragment.kt): fragment · Primary cat list screen. · `app/src/main/java/com/marianagoto/catimagelist/HomeFragment.kt`
- [Favorites](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/FavoritesFragment.kt): fragment · Saved cats screen. · `app/src/main/java/com/marianagoto/catimagelist/FavoritesFragment.kt`
- [Loading](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/LoadingFragment.kt): fragment · Loading state screen. · `app/src/main/java/com/marianagoto/catimagelist/LoadingFragment.kt`
- [Error](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ErrorFragment.kt): fragment · Error state screen. · `app/src/main/java/com/marianagoto/catimagelist/ErrorFragment.kt`
- [Empty Fav](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/EmptyFavoritesFragment.kt): fragment · Empty favorites state screen. · `app/src/main/java/com/marianagoto/catimagelist/EmptyFavoritesFragment.kt`
- [CatViewModel](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/viewmodel/CatViewModel.kt): view model · Orchestrates UI state and user actions for cat screens. · `app/src/main/java/com/marianagoto/catimagelist/ui/viewmodel/CatViewModel.kt`
- [CatUiState](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatUiState.kt): ui state · State model consumed by fragments and adapter. · `app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatUiState.kt`
- [CatAdapter](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatAdapter.kt): list adapter · Renders cat items in the list UI. · `app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatAdapter.kt`
- [CatListActivity](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatListActivity.kt): secondary activity · Additional activity in the cat list UI package. · `app/src/main/java/com/marianagoto/catimagelist/ui/catlist/CatListActivity.kt`

### Domain

Core model and use cases.

- [CatImage](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/domain/model/CatImage.kt): domain model · Core cat item entity used across layers. · `app/src/main/java/com/marianagoto/catimagelist/domain/model/CatImage.kt`
- [GetCats](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/domain/usecase/GetCatsUseCase.kt): use case · Loads cat images for the presentation layer. · `app/src/main/java/com/marianagoto/catimagelist/domain/usecase/GetCatsUseCase.kt`
- [Toggle Fav](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/domain/usecase/ToogleFavoriteUseCase.kt): use case · Encapsulates favorite toggling rules. · `app/src/main/java/com/marianagoto/catimagelist/domain/usecase/ToogleFavoriteUseCase.kt`

### Data / remote

Repository and network boundary.

- [CatRepository](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/data/repository/CatRepository.kt): repository · Coordinates data access between use cases and remote API. · `app/src/main/java/com/marianagoto/catimagelist/data/repository/CatRepository.kt`
- [RetrofitClient](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/data/network/RetrofitClient.kt): network client · Builds the Retrofit networking boundary. · `app/src/main/java/com/marianagoto/catimagelist/data/network/RetrofitClient.kt`
- [CatApiService](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/data/remote/api/CatApiService.kt): remote api · Remote service definition for fetching cats. · `app/src/main/java/com/marianagoto/catimagelist/data/remote/api/CatApiService.kt`
- [ViewModelFactory](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/java/com/marianagoto/catimagelist/di/CatViewModelFactory.kt): factory · Manual dependency injection for creating the view model. · `app/src/main/java/com/marianagoto/catimagelist/di/CatViewModelFactory.kt`

### Resources

Layouts, menus, assets, and theme resources.

- [activity_main.xml](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/activity_main.xml): layout · Main activity layout container. · `app/src/main/res/layout/activity_main.xml`
- [Fragment layouts](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/fragment_home.xml): layouts · XML layouts for home, favorites, loading, error, and empty states. · `app/src/main/res/layout/fragment_home.xml`
- [item_cat.xml](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/layout/item_cat.xml): item layout · Recycler item layout for a cat entry. · `app/src/main/res/layout/item_cat.xml`
- [bottom_menu.xml](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/menu/bottom_menu.xml): menu · Bottom navigation menu definition. · `app/src/main/res/menu/bottom_menu.xml`
- [Lottie assets](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/raw/cat_loading.json): raw assets · Animated feedback assets for loading, error, and favorite states. · `app/src/main/res/raw/cat_loading.json`
- [Drawables](https://github.com/marianagoto/catimagelist/blob/main/app/src/main/res/drawable/cat_icon.xml): icons/illustrations · Cat-themed icons and supporting vector assets. · `app/src/main/res/drawable/cat_icon.xml`

## Connections

- MainActivity → activity_main.xml: inflates · Main activity uses the main container layout.
- MainActivity → Home: hosts · Activity provides the primary fragment container.
- MainActivity → Favorites: hosts · Activity switches to the favorites screen.
- MainActivity → Loading: hosts · Activity can show loading state.
- MainActivity → Error: hosts · Activity can show error state.
- MainActivity → Empty Fav: hosts · Activity can show empty favorites state.
- MainActivity → bottom_menu.xml: uses · Bottom navigation drives top-level section switching.
- MainActivity → ViewModelFactory: creates · Manual wiring for view model dependencies.
- Home → CatViewModel: observes · Home screen consumes UI state and actions.
- Favorites → CatViewModel: observes · Favorites screen shares the same state holder.
- Loading → CatUiState: represents · Loading state is modeled in UI state.
- Error → CatUiState: represents · Error state is modeled in UI state.
- Empty Fav → CatUiState: represents · Empty favorites state is modeled in UI state.
- CatViewModel → CatUiState: publishes · View model exposes screen state to the UI.
- CatViewModel → GetCats: calls · Loads cat content through the domain layer.
- CatViewModel → Toggle Fav: calls · Handles favorite toggles through domain logic.
- CatViewModel → CatAdapter: feeds · View model data is rendered by the list adapter.
- GetCats → CatRepository: depends on · Use case delegates data retrieval to repository.
- Toggle Fav → CatRepository: depends on · Use case delegates favorite updates to repository.
- CatRepository → RetrofitClient: uses · Repository relies on the Retrofit boundary.
- RetrofitClient → CatApiService: builds · Client creates the remote API service.
- CatRepository → CatImage: returns · Repository converts remote data into domain entities.
- CatAdapter → item_cat.xml: binds · Adapter inflates the list item layout.
- Home → CatAdapter: displays · Home screen presents the cat list.
- Home → Fragment layouts: inflates · Home and related fragments use XML layouts.
- Favorites → Fragment layouts: inflates · Favorites screen uses XML layouts.
- Loading → Fragment layouts: inflates · Loading screen uses XML layout.
- Error → Fragment layouts: inflates · Error screen uses XML layout.
- Empty Fav → Fragment layouts: inflates · Empty favorites screen uses XML layout.
- Home → Lottie assets: uses · Presentation states are supported by animated assets.
- Error → Drawables: uses · Error and empty states use supporting illustrations.