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

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, which bootstraps the interface and initializes the navigation system.

• MainActivity.java – Located at 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, this custom widget renders the main navigation bar.
• IndexMenu.java – At 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, this adapter handles fragment paging for the main UI.

// 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, 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, 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, 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, this utility checks for app updates and critical releases.
• SPAppActions.java – At app/src/main/java/com/quranapp/android/utils/sharedPrefs/SPAppActions.java, this class manages shared preferences including onboarding flags.

// 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, this base class powers all custom dialogs.
• PeaceDialogController.java – At 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, this implementation displays loading indicators using the peacedesign framework.

// 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, this utility enables smooth height changes for expandable views.
• TypefaceSpan2.java – At 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 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 at 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}