# habitrpg/habitica-android architecture

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

- Interactive diagram: https://gitdiagram.com/habitrpg/habitica-android
- Repository: https://github.com/habitrpg/habitica-android

## Overview

This project is the Android client for Habitica – a mobile habit building RPG – and it is structured as a multi-module Android application with shared and platform-specific code. The repository contains several modules, including the main Android app (in the "Habitica" module), support for Wear OS (in the "wearos" module), common utilities and resources (in "common"), and multi-platform shared code (in "shared"). This design indicates a layered architecture with clear separations between presentation, domain, data, and platform-specific concerns.

##### Main Components
- Client Modules:
- Habitica Android App: Contains core Android UI components (activities, fragments, adapters, view models) located under Habitica/src/main.
- Wear OS Module: A separate module for wearable-specific code (UI, activities, and data repository adaptations) under wearos.
- Shared Code: "common" and "shared" modules provide shared models, utility functions, API definitions, and platform-agnostic logic.
- Data Layer:
- API Services & Network: Folder structures like Habitica/src/main/java/com/habitrpg/android/habitica/api and similar in wearos define services (e.g., ApiService.kt, ApiClient.kt) with JSON deserialization and network configuration.
- Repositories & Local Data: Components in data, such as repositories (both remote and local versions) and their implementations under data/implementation and data/local, manage persistence, caching, and database interactions.
- Domain & Business Logic:
- Interactors: Use cases (for instance, LevelUpUseCase.kt, HatchPetUseCase.kt) encapsulate business rules and operations.
- Models: Located across modules (Habitica/src/main/java/com/habitrpg/android/habitica/models, common, shared) represent the core data structures (tasks, user, notifications, inventory).
- Presentation Layer:
- UI Components: Activities, fragments, and adapters (organized under Habitica/src/main/java/com/habitrpg/android/habitica/ui and wearos equivalents) form the user interface.
- ViewModels: Component in the ui/viewmodels folder are responsible for state management using MVVM.
- Platform Integration:
- Dependency Injection / Modules: The modules folder (e.g., ApiModule.kt, DeveloperModule.kt) provides dependency injection configuration.
- External Services: Integrations such as Firebase (via google-services.json) and third-party libraries included in libs indicate external dependencies.
- Build & Configuration:
- Build Configuration Files: The multi-level Gradle (build.gradle.kts, settings.gradle.kts, build-logic) create a consistent build environment along with configuration files like habitica.properties and habitica.resources.

##### Relationships and Interactions
- Flow from UI to Business Logic to Data Access:
- UI components (activities and fragments) communicate with ViewModels that, in turn, invoke interactors/use cases.
- The interactors leverage repositories to fetch data either over the network (API service) or from local storage (local repository implementations).
- Dependency flows between modules (for example, the Habitica module references shared and common modules, and the wearos module has similar dependencies).

##### Architectural Patterns & Design Principles
- MVVM: Clear split between UI (Activities/Fragments), ViewModels (state management), and underlying business logic.
- Repository Pattern: Abstracting data access through repositories that handle API calls and local persistence.
- Modularization & Multi-platform: Separation into platform-specific (Android vs. Wear OS) and shared modules supports code reuse and clean boundaries.
- Dependency Injection: Utilize modules (found in modules/ directory) to decouple dependencies (often implemented with Dagger/Hilt or similar).

##### Relevant Technologies and Frameworks
- Kotlin programming language for most source files.
- Android SDK for UI layers, including Android Architecture Components (LiveData, ViewModel).
- Firebase for messaging and analytics integration.
- Gradle (Kotlin DSL) for building and dependency management.
- Possibly Dagger/Hilt (or a similar DI framework) for dependency injection given the modular structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration and External Services
    BUILD("Build & Configuration"):::config
    FIRE("Firebase Integration"):::external

    %% Habitica Android App Module Subgraph
    subgraph "Habitica Android App Module"
        H_UI("UI Components (Activities,Fragments)"):::ui
        H_VM("ViewModels"):::ui
        H_BL("Business Logic (Interactors)"):::business
        H_DI("Dependency Injection Modules"):::config
        H_DATA("Data Layer (Repositories,API)"):::data
    end

    %% Wear OS Module Subgraph
    subgraph "Wear OS Module"
        WO_UI("UI Components (Wear OS Activities)"):::ui
        WO_VM("ViewModels"):::ui
        WO_DATA("Data Layer (Repositories,API)"):::data
    end

    %% Common and Shared Modules
    COMMON("Common Utilities & Resources"):::shared
    SHARED("Multi‑platform Shared Logic"):::shared

    %% Habitica Data Layer Breakdown
    H_DATA --> H_API("Remote API Services"):::data
    H_DATA --> H_LOCAL("Local Repository"):::data

    %% Wear OS Data Layer Breakdown
    WO_DATA --> WO_API("Remote API Services"):::data
    WO_DATA --> WO_LOCAL("Local Repository"):::data

    %% Connections within Habitica Module
    H_UI -->|"calls"| H_VM
    H_VM -->|"invokes"| H_BL
    H_BL -->|"fetches data"| H_DATA
    H_DI -->|"configures"| H_DATA
    BUILD -->|"configures"| H_DI
    BUILD --> FIRE

    %% Connections from Habitica Module to Shared Code
    H_UI -->|"dependsOn"| COMMON
    H_UI -->|"dependsOn"| SHARED
    H_BL -->|"uses"| COMMON
    H_BL -->|"uses"| SHARED

    %% Connections within Wear OS Module
    WO_UI -->|"calls"| WO_VM
    WO_VM -->|"accesses"| WO_DATA

    %% Connections from Wear OS Module to Shared Code
    WO_UI -->|"dependsOn"| COMMON
    WO_UI -->|"dependsOn"| SHARED

    %% External Service Integration from API Services
    H_API -->|"integrates"| FIRE
    WO_API -->|"integrates"| FIRE

    %% Click Events for Habitica Module
    click H_UI "https://github.com/habitrpg/habitica-android/tree/main/Habitica/src/main/java/com/habitrpg/android/habitica/ui"
    click H_VM "https://github.com/habitrpg/habitica-android/tree/main/Habitica/src/main/java/com/habitrpg/android/habitica/ui/viewmodels"
    click H_BL "https://github.com/habitrpg/habitica-android/tree/main/Habitica/src/main/java/com/habitrpg/android/habitica/interactors"
    click H_API "https://github.com/habitrpg/habitica-android/tree/main/Habitica/src/main/java/com/habitrpg/android/habitica/api"
    click H_LOCAL "https://github.com/habitrpg/habitica-android/tree/main/Habitica/src/main/java/com/habitrpg/android/habitica/data/implementation"
    click H_DI "https://github.com/habitrpg/habitica-android/tree/main/Habitica/src/main/java/com/habitrpg/android/habitica/modules"

    %% Click Events for Wear OS Module
    click WO_UI "https://github.com/habitrpg/habitica-android/tree/main/wearos/src/main/java/com/habitrpg/wearos/habitica/ui"
    click WO_VM "https://github.com/habitrpg/habitica-android/tree/main/wearos/src/main/java/com/habitrpg/wearos/habitica/ui/viewmodels"
    click WO_API "https://github.com/habitrpg/habitica-android/tree/main/wearos/src/main/java/com/habitrpg/wearos/habitica/data"
    click WO_LOCAL "https://github.com/habitrpg/habitica-android/tree/main/wearos/src/main/java/com/habitrpg/wearos/habitica/data/repositories"

    %% Click Events for Shared Modules
    click COMMON "https://github.com/habitrpg/habitica-android/tree/main/common/"
    click SHARED "https://github.com/habitrpg/habitica-android/tree/main/shared/"

    %% Click Events for Build & Configuration / Firebase
    click BUILD "https://github.com/habitrpg/habitica-android/blob/main/build.gradle.kts"
    click FIRE "https://github.com/habitrpg/habitica-android/blob/main/Habitica/google-services.json.example"

%% Styles
classDef ui fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
classDef business fill:#90EE90,stroke:#008000,stroke-width:2px;
classDef data fill:#FFD700,stroke:#FFA500,stroke-width:2px;
classDef config fill:#D3D3D3,stroke:#808080,stroke-width:2px;
classDef shared fill:#E6E6FA,stroke:#9400D3,stroke-width:2px;
classDef external fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
```
