About the app module

The app module is the heart of the Lawnicons Android application. It's where you'll find the code for the user interface, application logic, and data management. We've structured this module using Modern Android Development (MAD) principles to promote clarity and maintainability.

Architectural layers

The app module primarily follows an architecture similar to Model-View-ViewModel (MVVM). This pattern separates concerns into distinct layers:

flowchart LR
  UI["UI Layer<br/>(Jetpack Compose:<br/>Screens & Components)"]
  VM["ViewModel Layer<br/>(Business Logic & UI State)"]
  REPO["Data Layer<br/>(Repositories & Data Abstraction)"]
  DATA["Data Sources<br/>(Local XML/Assets/Prefs,<br/>Remote APIs via Retrofit)"]

  DATA --> REPO
  REPO --> VM
  VM --> UI

Loading

• UI Layer: Built with Jetpack Compose. This layer is responsible for displaying data to the user and capturing user input. For more details, see UI Layer (Compose).
• ViewModel Layer: Manages UI-related state and contains the business logic. ViewModels react to user events and interact with Repositories to fetch or update data. Dive deeper in ViewModel & State Management.
• Data Layer (Repositories): This layer abstracts the underlying data sources (like local files, SharedPreferences, or remote APIs). Repositories provide a clean API for ViewModels to access data, often using Kotlin Flow for reactive updates. Explore this in Data Layer & Repositories.
• Dependency Injection: We use Metro to manage dependencies between these layers, making the code more modular and easier to test. Learn more at Dependency Injection (Metro).

Key packages and their roles

Here's a breakdown of the main packages within the app module (app/src/main/kotlin/app/lawnchair/lawnicons/) and what they do:

• Root package (app.lawnchair.lawnicons)
  • MainActivity.kt: The app's single entry point (Activity). It sets up Jetpack Compose, determines screen size, and handles intents like ICON_PICKER_INTENT_ACTION.
  • LawniconsApplication.kt: The custom Application class. Initializes Metro by creating the LawniconsGraph via createGraphFactory<LawniconsGraph.Factory>().
  • LawniconsGraph.kt: The Metro dependency graph, annotated with @DependencyGraph(LawniconsScope::class). Implements ViewModelGraph and exposes the MetroViewModelFactoryImpl.
• data/api/
  • Contains Retrofit interfaces that define how the app communicates with external web services: GitHubContributorsAPI, IconRequestSettingsAPI, and AnnouncementsAPI.
• data/model/
  • Defines Kotlin data classes (for example, IconInfo, GitHubContributor, Announcement, IconRequestModel). These classes represent the data structures used throughout the app. Many are marked @Serializable for use with Kotlinx Serialization.
• data/repository/
  • Contains concrete implementations of the Repository pattern, each annotated with @ContributesBinding(LawniconsScope::class) to automatically bind to their interfaces.
  • home/: IconRepository (icon loading & search), AnnouncementsRepository (home screen announcements), GetIconInfo.kt (XML parsing helper).
  • iconrequest/: IconRequestRepository (unthemed app detection), IconRequestHandler (request flow logic), GetSystemPackageList.kt, AdaptiveIconBitmap.kt.
  • Root level: NewIconsRepository (new icons diff), OssLibraryRepository (open-source licenses), GitHubContributorsRepository (GitHub API), PreferenceManager.kt (SharedPreferences wrapper).
• di/
  • Houses Metro module interfaces that provide dependencies not available via constructor injection:
  • GithubApiModule.kt: Provides GitHubContributorsAPI (Retrofit service for https://api.github.com/).
  • WebsiteApiModule.kt: Provides IconRequestSettingsAPI, AnnouncementsAPI, and a shared OkHttpClient with caching.
  • PreferencesModule.kt: Provides preference-related dependencies.
  • MetroViewModelFactoryImpl.kt: The MetroViewModelFactory implementation, populated by Metro's @ContributesIntoMap ViewModel map.
• ui/
  • Holds all Jetpack Compose UI code.
  • Lawnicons.kt: The root Composable containing the NavDisplay which manages navigation between screens using Navigation3.
  • NavigationState.kt: Custom back-stack state holder with rememberNavigationState() and NavigationState.toEntries().
  • Navigator.kt: Handles forward navigation and back actions by updating the NavigationState.
  • theme/: Defines the app's visual appearance, including LawniconsTheme.kt (Material 3 Expressive, dynamic colors, contrast modes) and LawniconsColor.kt.
  • components/: Reusable UI elements. core/ has generic components (like LawniconsScaffold.kt, SimpleListRow.kt), while other subpackages have feature-specific ones.
  • destination/: Each feature has its own subpackage containing both the screen Composable and its ViewModel:
    • home/: Home.kt (home screen), HomeViewModel.kt (icon list, search, announcements).
    • about/: About.kt (about screen).
    • contributors/: Contributors.kt, ContributorsViewModel.kt.
    • acknowledgements/: Acknowledgements.kt, AcknowledgementsViewModel.kt.
    • newicons/: NewIcons.kt, NewIconsViewModel.kt.
    • iconrequest/: IconRequest.kt, IconRequestViewModel.kt.
    • debugmenu/: DebugMenu.kt, DebugMenuViewModel.kt.
  • util/: Helper functions and constants (Constants.kt, PreviewUtils.kt).