# tbsten/android-project-template architecture

> Architecture diagram of the GitHub repository tbsten/android-project-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tbsten/android-project-template
- Repository: https://github.com/tbsten/android-project-template

## Overview

##### Main Components
- App Module: This is the main Android application module (found under the “app” directory) that contains the entry points such as MainActivity, AppNavHost, and MainApplication.
- UI Module: The “ui” folder is further divided into submodules like designSystem, feature (with multiple features such as example screens for counter, API post lists, and local Db user lists), and navigation. This layer is responsible for the presentation layer using Jetpack Compose.
- Domain Module: The “domain” folder contains business logic, use cases, and domain models. It is split into sub-modules like error handling and feature-specific business processes (e.g., posts, users).
- Data Module: The “data” directory is split into multiple submodules:
- API: Contains Retrofit, okhttp, and generated API interfaces using OpenAPI generator.
- Database: Uses Room; it includes the Room database classes, DAOs, and database schemas.
- Preferences: Contains the DataStore or other managed key-value stores for preferences.
- Example implementations for repository interfaces that link the data sources to the domain.
- Common Module: Contains cross-cutting utilities and common code used throughout the app (e.g., logging, lazy delegates).
- Build Logic: The “buildLogic” directory houses the customized Gradle scripts and plugins that standardize module configuration (e.g., AndroidLibraryModulePlugin, ComposeDsl, HiltPlugin) and enforce code quality with Ktlint, Detekt, and Roborazzi.
- Tools (Debug): The “tools/debug” module includes a debug menu and related UI components that facilitate in-app debugging.

##### Out the Interactions and Relationships
- UI Layer to Domain Layer:
- UI screens (Compose UIs, ViewModels) initiate user-driven actions.
- Each UI component (for example, the ExampleApiPostListScreen, ExampleCounterScreen, etc.) uses a ViewModel that triggers Use Cases from the domain layer.
- Domain Layer to Data Layer:
- The Use Cases in “domain” invoke repository interfaces. For example, the “GetPostsUseCase” and its implementation interact with the repositories provided by the “data” modules.
- The Data layer abstracts how data flows from persistence (Room in “data/database”), remote (Retrofit in “data/api”), or preferences (DataStore in “data/preferences”).
- External Dependencies & Frameworks:
- Use of Dagger Hilt for dependency injection across modules.
- Jetpack Compose supports declarative UI.
- Error handling from the domain/error module is integrated to provide consistent error states throughout the app.
- Build and Quality:
- BuildLogic and configuration scripts ensure consistent build behavior and module separation.
- CI integrations with Github Actions (as specified in the README and workflows) set up automated testing and validation.
- Debugging Support:
- The debug tool module under “tools/debug” integrates a debug menu that is dynamically available for troubleshooting during development builds.

##### Architectural Patterns and Technical Stack Highlights
- MVVM Architecture: The project has a clear separation between the presentation (UI/ViewModel), domain (use cases and business logic), and data (repository implementations) layers.
- Dependency Injection: Dagger Hilt manages dependencies throughout the application.
- Modularization: The project is split into clear modules (app, common, data, domain, ui) to facilitate separation of concerns and easier scalable development.
- Build Customization: Extensive use of Gradle scripts and custom DSLs under buildLogic, enforcing standards and project-wide configurations.
- External Libraries: Retrofit + OkHttp for HTTP, Room for local database management, and Jetpack Compose for the UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% App Shell
    subgraph "App Shell"
        APPA["MainApplication"]:::appModule
        APPACT["MainActivity"]:::appModule
        APPNAV["AppNavHost"]:::appModule
    end

    %% Presentation Layer (UI)
    subgraph "Presentation Layer (UI)"
        U1["Compose Screens & Navigation"]:::uiLayer
        subgraph "Feature Modules"
            U11["ExampleCounterScreen"]:::uiLayer
            U12["ExampleApiPostListScreen"]:::uiLayer
            U13["ExampleLocalDbUserListScreen"]:::uiLayer
        end
        U2["ViewModels"]:::uiLayer
    end

    %% Domain Layer
    subgraph "Domain Layer"
        D1["Use Cases (e.g., GetPostsUseCase)"]:::domainLayer
        D2["Business Logic & Repo Interfaces"]:::domainLayer
    end

    %% Data Layer
    subgraph "Data Layer"
        subgraph "API Module"
            API1["RetrofitModule"]:::dataLayer
            API2["PostsApi"]:::dataLayer
        end
        subgraph "Database Module"
            DB1["AppDatabase (Room)"]:::dataLayer
            DB2["UserDao"]:::dataLayer
        end
        subgraph "Preferences Module"
            P1["DataStore"]:::dataLayer
        end
        subgraph "Repository Implementations"
            R1["UserRepositoryImpl"]:::dataLayer
            R2["PostsRepositoryImpl"]:::dataLayer
        end
    end

    %% Common Module
    subgraph "Common Module"
        C1["Common Utilities"]:::commonLayer
    end

    %% Build & Dev Tools
    subgraph "Build & Dev Tools"
        B1["Build Logic"]:::buildLayer
        B2["CI & Gradle Scripts"]:::buildLayer
        DT["Debug Tools"]:::buildLayer
    end

    %% External Frameworks
    subgraph "External Frameworks"
        EF1["Jetpack Compose"]:::external
        EF2["Dagger Hilt"]:::external
        EF3["Retrofit"]:::external
        EF4["Room"]:::external
    end

    %% Relationships
    %% UI triggers Domain Use Cases
    U1 -->|"triggers"| D1
    U2 -->|"binds"| D1

    %% Domain calls Repository implementations
    D1 -->|"calls"| R1
    D1 -->|"calls"| R2
    D2 -->|"supports"| D1

    %% Repository implementations fetch data from Data modules
    R1 -->|"reads from"| API1
    R1 -->|"reads from"| DB1
    R1 -->|"reads from"| P1
    R2 -->|"reads from"| API2
    R2 -->|"reads from"| DB2

    %% External Frameworks integration
    EF1 -->|"framework"| U1
    EF2 -->|"injects"| U2
    EF2 -->|"injects"| D1
    EF2 -->|"injects"| R1
    EF2 -->|"injects"| R2
    EF3 -->|"framework"| API1
    EF4 -->|"framework"| DB1

    %% Debug Tools interaction
    DT -->|"debugs"| APPA
    DT -->|"debugs"| U1

    %% Build & Dev Tools influence
    B1 -->|"configures"| APPA
    B2 -->|"CI/CD"| B1

    %% Click Events
    click APPA "https://github.com/tbsten/android-project-template/tree/main/app/src/main/kotlin/your/projectPackage/app"
    click APPACT "https://github.com/tbsten/android-project-template/tree/main/app/src/main/kotlin/your/projectPackage/app"
    click APPNAV "https://github.com/tbsten/android-project-template/tree/main/app/src/main/kotlin/your/projectPackage/app"
    click U11 "https://github.com/tbsten/android-project-template/tree/main/ui/feature/example"
    click U12 "https://github.com/tbsten/android-project-template/tree/main/ui/feature/example"
    click U13 "https://github.com/tbsten/android-project-template/tree/main/ui/feature/example"
    click D1 "https://github.com/tbsten/android-project-template/tree/main/domain/src/main/kotlin/your/projectPackage/domain/example"
    click API1 "https://github.com/tbsten/android-project-template/tree/main/data/api"
    click API2 "https://github.com/tbsten/android-project-template/tree/main/data/api"
    click DB1 "https://github.com/tbsten/android-project-template/tree/main/data/database"
    click DB2 "https://github.com/tbsten/android-project-template/tree/main/data/database"
    click P1 "https://github.com/tbsten/android-project-template/tree/main/data/preferences"
    click R1 "https://github.com/tbsten/android-project-template/tree/main/data/src/main/kotlin/your/projectPackage/data/example"
    click R2 "https://github.com/tbsten/android-project-template/tree/main/data/src/main/kotlin/your/projectPackage/data/example"
    click C1 "https://github.com/tbsten/android-project-template/tree/main/common/src/main/kotlin/your/projectPackage/common"
    click B1 "https://github.com/tbsten/android-project-template/tree/main/buildLogic"
    click B2 "https://github.com/tbsten/android-project-template/tree/main/buildLogic"
    click DT "https://github.com/tbsten/android-project-template/tree/main/tools/debug"

    %% Styles
    classDef appModule fill:#A3E4D7,stroke:#2980B9,stroke-width:2px;
    classDef uiLayer fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef domainLayer fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef dataLayer fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef commonLayer fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef buildLayer fill:#D5DBDB,stroke:#7F8C8D,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
```
