# How to Understand the Architecture of alfaazplus/quranapp: A Developer's Guide

> Uncover the alfaazplus/quranapp architecture by tracing its MVVM flow through custom widgets, ViewModels, and modules. A developer's guide to understanding the code structure.

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

---

**The recommended way to understand the architecture of alfaazplus/quranapp is to start with [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java) and trace the MVVM-inspired flow through custom widgets, ViewModels, and data helpers, following the modular separation between the `:app` and `:peacedesign` modules.**

QuranApp is an Android-based, ad-free, privacy-focused mobile application for reading and exploring the Holy Qur'an. To effectively understand the architecture of alfaazplus/quranapp, you need to grasp its modular, MVVM-inspired structure that cleanly separates UI, business logic, data handling, and utilities across distinct Gradle modules.

## Architectural Overview of QuranApp

The codebase follows a layered architecture that organizes code by responsibility. Understanding these layers is essential to navigate the repository effectively.

| Layer | Purpose | Key Files |
|-------|---------|-----------|
| **Presentation** | Activities, Fragments, UI widgets, and adapters | [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java), [`FragMain.kt`](https://github.com/alfaazplus/quranapp/blob/main/FragMain.kt), [`BottomTabLayout.java`](https://github.com/alfaazplus/quranapp/blob/main/BottomTabLayout.java) |
| **View-Model / State** | Holds UI state and communicates with repositories | [`TafsirViewModel.kt`](https://github.com/alfaazplus/quranapp/blob/main/TafsirViewModel.kt), [`FavChaptersViewModel.kt`](https://github.com/alfaazplus/quranapp/blob/main/FavChaptersViewModel.kt) |
| **Domain / Business Logic** | Parsers, managers, and services for Qur'an features | [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt), [`RecitationManager.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationManager.kt) |
| **Data / Persistence** | SQLite helpers and contracts for local storage | [`QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranTranslDBHelper.kt), [`SearchHistoryDBHelper.java`](https://github.com/alfaazplus/quranapp/blob/main/SearchHistoryDBHelper.java) |
| **Utilities** | Common helpers for resources, networking, and configuration | [`ResUtils.kt`](https://github.com/alfaazplus/quranapp/blob/main/ResUtils.kt), [`SPAppConfigs.kt`](https://github.com/alfaazplus/quranapp/blob/main/SPAppConfigs.kt) |
| **Modules** | `:app` (main application) and `:peacedesign` (UI theming) | `settings.gradle.kts` |

## Core Architectural Patterns

### Modular Gradle Structure

The project defines two distinct modules in `settings.gradle.kts`: `:app` and `:peacedesign`. The `:app` module contains the core Qur'an functionality, while `:peacedesign` houses reusable UI-theming and animation utilities. This separation allows the UI components to remain independent from core application logic, making the codebase easier to maintain and test.

### MVVM-Inspired Data Flow

While the app does not strictly use Android Architecture Components like LiveData, it follows an MVVM-like pattern:

1. **Activity/Fragment** creates UI widgets and binds to a **ViewModel** (e.g., [`TafsirViewModel.kt`](https://github.com/alfaazplus/quranapp/blob/main/TafsirViewModel.kt))
2. **ViewModel** pulls data from **Repository/Manager** classes (e.g., [`RecitationManager.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationManager.kt), [`QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranTranslDBHelper.kt))
3. **Managers** handle business logic and data persistence, keeping UI logic out of Activities

### Widget-Centric Navigation

Instead of relying solely on standard Android navigation components, QuranApp implements custom navigation widgets. The [`BottomTabLayout.java`](https://github.com/alfaazplus/quranapp/blob/main/BottomTabLayout.java) and [`BottomTab.java`](https://github.com/alfaazplus/quranapp/blob/main/BottomTab.java) classes in `com.quranapp.android.widgets.tablayout` handle the main navigation flow. In [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java), the `initBottomNavigation()` method configures these tabs to either swap fragments via `ViewPager2` or launch new Activities.

### Manual Dependency Injection

The app does not use a dedicated DI framework like Dagger or Hilt. Instead, objects are instantiated manually (e.g., `new UpdateManager(this, null)`). This lightweight approach reduces build complexity and keeps the project accessible for single-developer maintenance.

## Key Components and File Structure

To understand the architecture of alfaazplus/quranapp, explore these critical files:

- **[`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)** – Entry point that orchestrates header, view-pager, and bottom navigation initialization.
- **[`app/src/main/java/com/quranapp/android/frags/main/FragMain.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/frags/main/FragMain.kt)** – Home fragment containing the dashboard, Verse-of-the-Day widget, and quick navigation links.
- **[`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)** – Generic adapter for ViewPager2 used across multiple Activities.
- **[`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)** – Custom bottom navigation implementation.
- **[`app/src/main/java/com/quranapp/android/utils/quran/parser/QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/utils/quran/parser/QuranParser.kt)** – Core parser for Qur'an text, metadata, and structural data.
- **[`app/src/main/java/com/quranapp/android/utils/reader/recitation/RecitationManager.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/utils/reader/recitation/RecitationManager.kt)** – Handles audio recitation playback, download management, and caching.
- **[`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)** – SQLite helper for translation storage and retrieval.
- **[`peacedesign/src/main/java/com/peacedesign/android/utils/anim/DimensionAnimator.kt`](https://github.com/alfaazplus/quranapp/blob/main/peacedesign/src/main/java/com/peacedesign/android/utils/anim/DimensionAnimator.kt)** – Reusable animation utility for consistent UI transitions.

## Data Flow: From UI to Persistence

### Presentation Layer

The presentation layer resides in `activities/` and `frags/` packages. [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java) initializes the UI through its `init()` method, setting up the header, `ViewPager2` with `FragMain`, and the custom `BottomTabLayout`. This layer handles user interactions and delegates data needs to ViewModels.

### Business Logic Layer

Domain logic lives in `utils/` subpackages. [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt) processes Qur'an JSON assets into usable data structures, while [`RecitationManager.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationManager.kt) coordinates audio playback and download states. These managers abstract complex operations from the UI, providing clean APIs for Activities and ViewModels.

### Data Persistence Layer

Local data storage uses SQLite via helpers in `db/`. [`QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranTranslDBHelper.kt) manages translation tables, while [`SearchHistoryDBHelper.java`](https://github.com/alfaazplus/quranapp/blob/main/SearchHistoryDBHelper.java) handles user search history. Raw data originates from JSON files in `inventory/` (e.g., [`available_recitations_info.json`](https://github.com/alfaazplus/quranapp/blob/main/available_recitations_info.json)), which the app parses and caches into the local database on first run.

## Background Services and Utilities

QuranApp implements several background services for uninterrupted user experience:

- **[`RecitationService.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationService.kt)** – Foreground service managing audio playback with notification controls.
- **[`KFQPCScriptFontsDownloadService.kt`](https://github.com/alfaazplus/quranapp/blob/main/KFQPCScriptFontsDownloadService.kt)** – Handles download of Qur'anic fonts as a foreground service.
- **`VotdReceiver`** – Broadcast receiver listening for system events like boot or network changes to update the Verse-of-the-Day widget.

The `:peacedesign` module provides reusable utilities like [`DimensionAnimator.kt`](https://github.com/alfaazplus/quranapp/blob/main/DimensionAnimator.kt) for consistent UI animations across the application.

## Step-by-Step Guide to Exploring the Codebase

Follow this sequence to effectively understand the architecture of alfaazplus/quranapp:

1. **Start at [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java)** – Follow the `init()` method to see the flow of UI initialization, including header setup and bottom navigation configuration.

2. **Trace the Bottom Navigation** – Open [`BottomTabLayout.java`](https://github.com/alfaazplus/quranapp/blob/main/BottomTabLayout.java) to understand how tabs are constructed and how click callbacks launch Activities like `ActivityReaderIndexPage`.

3. **Inspect the Home Fragment** – [`FragMain.kt`](https://github.com/alfaazplus/quranapp/blob/main/FragMain.kt) loads widgets like the Verse-of-the-Day and links to other features; examine its view-binding and data observation patterns.

4. **Look at Data Access** – Pick a feature (e.g., translations) and follow the path: `QuranTranslDBHelper` → translation contracts → JSON files under `inventory/translations`.

5. **Review Background Services** – For audio features, examine [`RecitationService.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationService.kt) and its receiver [`RecitationHeadsetReceiver.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationHeadsetReceiver.kt) to understand foreground service implementation.

6. **Read the Utility Modules** – Explore the `peacedesign` module for reusable UI helpers that maintain consistent theming across the app.

## Code Example: MainActivity Initialization

Below is a minimal snippet extracted from [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java) that demonstrates how the app builds its main UI:

```java
// Inside MainActivity.init()
private void init() {
    // 1️⃣ Build the top header (index menu & VOTD widget)
    initHeader();                     // → IndexMenu creation
    updateAllVotdWidgets(this);       // Refresh Verse‑of‑the‑Day widget

    // 2️⃣ Initialise the ViewPager with the home fragment
    ViewPager2 viewPager = mBinding.viewPager;
    ViewPagerAdapter2 adapter = new ViewPagerAdapter2(this);
    adapter.addFragment(new FragMain(), getString(R.string.strLabelNavHome));
    viewPager.setAdapter(adapter);
    viewPager.setUserInputEnabled(false); // disable swipe navigation

    // 3️⃣ Set up BottomTab navigation
    BottomTabLayout bottomTabLayout = mBinding.bottomTabLayout;
    bottomTabLayout.setTabs(getBottomTabs()); // builds Home / Search tabs
    bottomTabLayout.setKingTab(
        new BottomTab(R.drawable.quran_kareem),
        kingTab -> launchActivity(ActivityReaderIndexPage.class));
}

```

**Key architectural points demonstrated:**

- **View Binding** – The layout is accessed via `ActivityMainBinding`.
- **ViewPager2** – Holds a single fragment (`FragMain`) for the home screen.
- **Custom Navigation** – `BottomTabLayout` supplies standard tabs and a "king" tab (Qur'an icon) that launches the reader Activity.

## Summary

To understand the architecture of alfaazplus/quranapp, focus on these key aspects:

- **Modular Structure** – The project splits core functionality (`:app`) from UI theming (`:peacedesign`) via Gradle modules defined in `settings.gradle.kts`.
- **MVVM-Inspired Flow** – UI components (Activities/Fragments) delegate to ViewModels, which coordinate with Manager and Helper classes for business logic and data persistence.
- **Custom Widgets** – Navigation relies on bespoke components like `BottomTabLayout` rather than standard Android components, centralizing UI behavior in reusable classes.
- **Manual Data Management** – SQLite helpers (e.g., [`QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranTranslDBHelper.kt)) and JSON asset parsers (e.g., [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt)) handle local storage without external ORMs.
- **Foreground Services** – Background tasks like audio recitation ([`RecitationService.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationService.kt)) and font downloads run as foreground services with proper system integration.

## Frequently Asked Questions

### What architectural pattern does QuranApp use?

QuranApp follows an **MVVM-inspired architecture** where Activities and Fragments (Presentation layer) bind to ViewModels that manage UI state. These ViewModels interact with Manager classes (like [`RecitationManager.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationManager.kt)) and Database Helpers (like [`QuranTranslDBHelper.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranTranslDBHelper.kt)) to handle business logic and data persistence, keeping the UI layer thin and focused on rendering.

### How is the code organized between the :app and :peacedesign modules?

The project uses a **modular Gradle structure** defined in `settings.gradle.kts`. The `:app` module contains all core Qur'an functionality, including Activities, Fragments, database helpers, and parsers. The `:peacedesign` module is a separate library containing reusable UI utilities like [`DimensionAnimator.kt`](https://github.com/alfaazplus/quranapp/blob/main/DimensionAnimator.kt) for animations and theming components, allowing consistent styling across the application while keeping the main app logic isolated.

### Where should I start reading the QuranApp source code?

**Start with [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java)** in `app/src/main/java/com/quranapp/android/activities/`. Follow the `init()` method to understand how the UI is constructed, including the header setup, ViewPager2 initialization with `FragMain`, and the custom `BottomTabLayout` configuration. From there, trace into [`FragMain.kt`](https://github.com/alfaazplus/quranapp/blob/main/FragMain.kt) for the home screen logic, or explore [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt) and the `db/` package to understand data handling.

### Does QuranApp use a dependency injection framework?

**No**, QuranApp does not use a dedicated DI framework like Dagger or Hilt. Instead, it employs **manual dependency injection** where objects are instantiated directly (for example, `new UpdateManager(this, null)`). This lightweight approach reduces build complexity and keeps the project accessible for maintenance without the overhead of annotation processing or complex dependency graphs.