# Important Modules in the alfaazplus/quranapp Android Project: Architecture Guide

> Explore the important modules in the alfaazplus/quranapp Android project. Discover the core :app and :peacedesign UI modules guiding this multi-module Gradle architecture.

- Repository: [AlfaazPlus/quranapp](https://github.com/alfaazplus/quranapp)
- Tags: architecture
- Published: 2026-02-24

---

**The alfaazplus/quranapp Android project is organized as a multi-module Gradle project comprising two primary modules: `:app` for core application logic and `:peacedesign` for reusable UI components.**

The Quran App follows modern Android architectural patterns by separating business logic from presentation utilities. Understanding these important modules in the alfaazplus/quranapp Android project is essential for contributing to or extending the codebase. Both modules are defined in `settings.gradle.kts` and work together to produce the final APK.

## Module Overview: `:app` and `:peacedesign`

The project structure divides responsibilities between two distinct modules:

- **`:app`** – Contains the core Android application including Activities, Fragments, API clients, database helpers, and business logic.
- **`:peacedesign`** – Provides a standalone UI widget library with custom dialogs, animations, and view utilities under the `com.peacedesign` namespace.

This separation ensures that presentation utilities remain decoupled from domain logic, making the UI components reusable across different contexts.

## The `:app` Module: Core Application Architecture

The `:app` module serves as the primary entry point and houses all domain-specific code. It manages everything from user navigation to local data caching and remote API communication.

### Entry Points and Navigation

The user journey begins in [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java), which bootstraps the interface and initializes the navigation system.

- **MainActivity.java** – Located at [`app/src/main/java/com/quranapp/android/activities/MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/MainActivity.java), this Activity checks onboarding status and configures the header, view-pager, and bottom navigation.
- **BottomTabLayout.java** – Found at [`app/src/main/java/com/quranapp/android/widgets/tablayout/BottomTabLayout.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/widgets/tablayout/BottomTabLayout.java), this custom widget renders the main navigation bar.
- **IndexMenu.java** – At [`app/src/main/java/com/quranapp/android/suppliments/IndexMenu.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/suppliments/IndexMenu.java), this class manages the slide-out menu displaying Juz and Chapter shortcuts.
- **ViewPagerAdapter2.java** – In [`app/src/main/java/com/quranapp/android/adapters/utility/ViewPagerAdapter2.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/adapters/utility/ViewPagerAdapter2.java), this adapter handles fragment paging for the main UI.

```java
// Example: Configuring bottom navigation in MainActivity
BottomTabLayout bottomTabLayout = findViewById(R.id.bottomTabLayout);
bottomTabLayout.setTabs(getBottomTabs());
bottomTabLayout.setKingTab(
    new BottomTab(R.drawable.quran_kareem),
    kingTab -> launchActivity(ActivityReaderIndexPage.class)
);

```

### Data Layer and Networking

The module implements a robust data layer combining remote APIs with local SQLite storage.

- **RetrofitInstance.java** – At [`app/src/main/java/com/quranapp/android/api/RetrofitInstance.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/api/RetrofitInstance.java), this class configures the Retrofit client with base URLs and converters.
- **AlfaazPlusApi.java** – Found in [`app/src/main/java/com/quranapp/android/api/AlfaazPlusApi.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/api/AlfaazPlusApi.java), this interface declares HTTP endpoints for translations, tafsirs, and recitations.
- **QuranTranslDBHelper.kt** – Located at [`app/src/main/java/com/quranapp/android/db/translation/QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/db/translation/QuranTranslDBHelper.kt), this SQLite helper manages cached translation data.

### Background Utilities and State Management

Several utility classes handle asynchronous operations and persistent state:

- **UpdateManager.java** – In [`app/src/main/java/com/quranapp/android/utils/app/UpdateManager.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/utils/app/UpdateManager.java), this utility checks for app updates and critical releases.
- **SPAppActions.java** – At [`app/src/main/java/com/quranapp/android/utils/sharedPrefs/SPAppActions.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/utils/sharedPrefs/SPAppActions.java), this class manages shared preferences including onboarding flags.

```java
// Example: Triggering the index menu from MainActivity
mBinding.header.indexMenu.setOnClickListener(v -> mIndexMenu.open());

```

## The `:peacedesign` Module: Reusable UI Toolkit

The `:peacedesign` module functions as an independent library supplying generic UI components. It eliminates code duplication by centralizing dialog management, animations, and view manipulation utilities.

### Custom Dialog Framework

The dialog system provides a consistent look-and-feel across the application:

- **PeaceDialog.java** – Located at [`peacedesign/src/main/java/com/peacedesign/android/widget/dialog/base/PeaceDialog.java`](https://github.com/alfaazplus/quranapp/blob/main/peacedesign/src/main/java/com/peacedesign/android/widget/dialog/base/PeaceDialog.java), this base class powers all custom dialogs.
- **PeaceDialogController.java** – At [`peacedesign/src/main/java/com/peacedesign/android/widget/dialog/base/PeaceDialogController.java`](https://github.com/alfaazplus/quranapp/blob/main/peacedesign/src/main/java/com/peacedesign/android/widget/dialog/base/PeaceDialogController.java), this controller manages dialog lifecycles and UI bindings.
- **PeaceProgressDialog.kt** – Found in [`app/src/main/java/com/quranapp/android/widgets/dialog/loader/PeaceProgressDialog.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/widgets/dialog/loader/PeaceProgressDialog.kt), this implementation displays loading indicators using the peacedesign framework.

```java
// Example: Displaying a custom dialog
PeaceDialogParams params = new PeaceDialogParams()
    .setTitle("Update available")
    .setMessage("A new version is ready to download.")
    .setPositiveButton("Download", v -> startDownload())
    .setNegativeButton("Later", null);

new PeaceDialog(this, params).show();

```

### Animation and View Utilities

Supporting classes handle visual transitions and text styling:

- **HeightAnimation.java** – In [`peacedesign/src/main/java/com/peacedesign/android/utils/anim/HeightAnimation.java`](https://github.com/alfaazplus/quranapp/blob/main/peacedesign/src/main/java/com/peacedesign/android/utils/anim/HeightAnimation.java), this utility enables smooth height changes for expandable views.
- **TypefaceSpan2.java** – At [`peacedesign/src/main/java/com/peacedesign/android/utils/span/TypefaceSpan2.java`](https://github.com/alfaazplus/quranapp/blob/main/peacedesign/src/main/java/com/peacedesign/android/utils/span/TypefaceSpan2.java), this custom span applies typeface styling to text components.
- **ViewUtils.java** – Provides general view helpers for visibility toggles and margin adjustments.

## Module Interactions and Build Configuration

The `settings.gradle.kts` file registers both modules in the Gradle build system. The `:app` module declares a dependency on `project(":peacedesign")`, allowing direct instantiation of Peace widgets within application code.

This architecture enforces strict separation of concerns:

1. **`:app`** concentrates on domain logic, data fetching, and navigation patterns.
2. **`:peacedesign`** focuses exclusively on presentation utilities, remaining agnostic to business rules.

## Summary

- The **`:app`** module contains all core functionality including `MainActivity`, API clients (`AlfaazPlusApi`), database helpers (`QuranTranslDBHelper`), and navigation components (`BottomTabLayout`).
- The **`:peacedesign`** module supplies reusable UI infrastructure through `PeaceDialog`, animation utilities (`HeightAnimation`), and view helpers (`ViewUtils`).
- Both modules are configured in `settings.gradle.kts`, with `:app` depending on `:peacedesign` to maintain consistent styling across the application.
- Key entry points reside in `app/src/main/java/com/quranapp/android/activities/`, while shared UI components live under `peacedesign/src/main/java/com/peacedesign/`.

## Frequently Asked Questions

### What is the purpose of the `:peacedesign` module in quranapp?

The `:peacedesign` module serves as a reusable UI widget library that supplies custom dialogs, animations, and view utilities under the `com.peacedesign` namespace. It decouples presentation logic from business rules, allowing consistent styling across Activities and Fragments while remaining portable for future projects.

### How does the `:app` module handle data persistence?

The `:app` module implements SQLite-based local storage through specialized helpers like [`QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranTranslDBHelper.kt) for translations, `ReadHistoryDBHelper` for reading history, and `BookmarkDBHelper` for user bookmarks. These classes manage CRUD operations and caching strategies to support offline functionality.

### Where is the main navigation logic implemented in the alfaazplus/quranapp project?

Main navigation resides in [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java) at [`app/src/main/java/com/quranapp/android/activities/MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/MainActivity.java), which coordinates `ViewPager2` with `ViewPagerAdapter2` for fragment paging. The custom `BottomTabLayout` widget handles bottom-bar interactions, while [`IndexMenu.java`](https://github.com/alfaazplus/quranapp/blob/main/IndexMenu.java) manages the slide-out navigation drawer for Juz and Chapter access.

### Can the `:peacedesign` module be used independently of the Quran App?

Yes, the `:peacedesign` module is structured as a standalone library with no dependencies on Quranic domain logic. Its generic widgets—such as `PeaceDialog`, `HeightAnimation`, and `TypefaceSpan2`—can be imported into any Android project by declaring the module dependency in Gradle, making it suitable for reuse in unrelated applications.