How habitrpg/habitica-android works
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.