# How to Explore the alfaazplus/quranapp Codebase: A Complete Guide

> Effectively explore the alfaazplus/quranapp codebase. Understand module boundaries via settings.gradle.kts and trace the architecture from MainActivity.java.

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

---

**To effectively explore the alfaazplus/quranapp codebase, start with the `settings.gradle.kts` to understand module boundaries, then navigate through [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java) as the entry point, following the inheritance chain through `BaseActivity` to understand the architecture.**

The alfaazplus/quranapp is a modern Android application written in Java and Kotlin that provides Quranic reading capabilities with a modular, component-based architecture. When you explore the alfaazplus/quranapp codebase, you will find a clean separation between UI components, business logic, and data layers that makes navigation intuitive for developers. This guide provides a structured approach to understanding the repository structure, key entry points, and architectural patterns.

## Understanding the Project Structure

The repository follows a multi-module Gradle setup that separates concerns between the main application and reusable UI components.

### Gradle Module Configuration

The root `settings.gradle.kts` declares two distinct sub-projects: `:app` (the main Android application) and `:peacedesign` (a UI helper library). This configuration determines how the build system compiles and links dependencies between modules.

Key file: `settings.gradle.kts` at repository root.

### The Main Application Module (`:app`)

The `app` module contains the core Android application code, including activities, fragments, adapters, utilities, and UI components. This is where you will spend most of your time when exploring functionality.

Key entry point: [`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).

### The UI Library Module (`:peacedesign`)

The `peacedesign` module holds reusable UI utilities and animations that can be shared across different parts of the application or potentially other projects.

Example component: [`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).

## Navigating the Activity Architecture

The activity layer follows a clear inheritance pattern that centralizes common functionality in abstract base classes.

### BaseActivity as the Foundation

`BaseActivity` (located at [`app/src/main/java/com/quranapp/android/activities/base/BaseActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/base/BaseActivity.java)) serves as the abstract foundation for all activities in the application. It handles critical system-level concerns including:

- Locale configuration and language switching via `updateBaseContextLocale()`
- Font-scale normalization for accessibility
- Network-state listening and connectivity changes
- Asynchronous layout inflation for performance
- System-bar styling and theming

It also provides navigation helper methods such as `launchActivity()`, `launchMainActivity()`, and `restartMainActivity()` that standardize activity transitions across the app.

### MainActivity Entry Point

`MainActivity` extends `BaseActivity` and orchestrates the primary user interface. The initialization flow follows a specific sequence:

1. **`initCreate()`** checks onboarding status via `isOnboardingRequired()`, initializes the `UpdateManager`, and inflates the layout ([`activity_main.xml`](https://github.com/alfaazplus/quranapp/blob/main/activity_main.xml)).
2. **`init()`** sets up the header, configures the `ViewPager2` with `FragMain`, initializes the `BottomTabLayout` navigation, and refreshes "Verse of the Day" widgets.

The bottom navigation uses `BottomTabLayout` and `BottomTab` objects, mapping each tab to specific fragments or activities such as `ActivityReaderIndexPage` and `ActivitySearch`.

### Activity Hierarchy and Navigation Flow

The inheritance structure follows this pattern:

```

BaseActivity
 └─ MainActivity
      ├─ FragMain (home screen fragment)
      ├─ ActivityReaderIndexPage (Kareem tab)
      └─ ActivitySearch (search tab)

```

When exploring navigation logic, trace method calls from `BottomTabLayout` selection listeners through `launchActivity()` calls to understand how the app transitions between screens.

## Exploring UI Components and Fragments

The UI layer is organized into reusable widgets, fragment-based screens, and adapter-backed lists.

### Custom Widgets and Components

Custom views are located under `app/src/main/java/com/quranapp/android/widgets/` and `app/src/main/java/com/quranapp/android/components/`. Key components include:

- **`BottomTabLayout`** and **`BottomTab`**: Custom bottom navigation implementation that handles tab selection and visual states.
- **Header components**: Custom toolbar and title views used across activities.

### Fragment Organization

Major screens are implemented as fragments stored under `app/src/main/java/com/quranapp/android/frags/`. Examples include:

- **`FragMain`**: The primary home screen displayed in the main ViewPager.
- **`FragOnboardLanguage`**: Language selection during onboarding.

### ViewPager2 Implementation

The app uses `ViewPager2` for horizontal screen navigation. The **`ViewPagerAdapter2`** class (located at [`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)) supplies fragments to the ViewPager, managing the lifecycle and instantiation of screen components.

## Understanding Data and API Models

The data layer is defined in `app/src/main/java/com/quranapp/android/api/models/` and includes JSON schema definitions for remote content.

Key model classes include:

- **`TranslationBookInfoModel`**: Defines the structure for translation metadata.
- **`TafsirModel`**: Represents tafsir (exegesis) content structure.
- **`AvailableTafsirsModel`**: Manages available tafsir sources from the API.

The **`UpdateManager`** (located at [`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)) handles checking for app updates and critical patches, integrating with the data layer to fetch version information.

## Key Files and Entry Points for Exploration

When you first explore the alfaazplus/quranapp codebase, prioritize these files to understand the architecture:

| File | Role | Path |
|------|------|------|
| `settings.gradle.kts` | Module declaration | Root |
| `app/build.gradle.kts` | App-level Gradle configuration | `app/build.gradle.kts` |
| [`BaseActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/BaseActivity.java) | Abstract activity core (locale, theming, network) | [`app/src/main/java/com/quranapp/android/activities/base/BaseActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/base/BaseActivity.java) |
| [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.java) | Main UI entry point | [`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) |
| [`FragMain.java`](https://github.com/alfaazplus/quranapp/blob/main/FragMain.java) | Home fragment displayed in the ViewPager | [`app/src/main/java/com/quranapp/android/frags/main/FragMain.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/frags/main/FragMain.java) |
| [`BottomTabLayout.java`](https://github.com/alfaazplus/quranapp/blob/main/BottomTabLayout.java) | Custom bottom navigation component | [`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) |
| [`ViewPagerAdapter2.java`](https://github.com/alfaazplus/quranapp/blob/main/ViewPagerAdapter2.java) | Adapter for ViewPager2 handling fragments | [`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) |
| [`UpdateManager.java`](https://github.com/alfaazplus/quranapp/blob/main/UpdateManager.java) | Handles checking for app updates | [`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) |
| [`DimensionAnimator.kt`](https://github.com/alfaazplus/quranapp/blob/main/DimensionAnimator.kt) | Reusable animation utility in the `peacedesign` module | [`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) |

## Practical Code Examples

The following snippets illustrate typical patterns you will encounter when exploring the alfaazplus/quranapp codebase.

### Activity Navigation from BaseActivity

```java
// Launch a new activity from any BaseActivity subclass
public void launchActivity(Class<?> cls) {
    Intent intent = new Intent(this, cls);
    startActivity(intent);
}

// Example: Open the search screen from the bottom navigation
bottomTabLayout.setSelectionChangeListener(tab -> {
    if (tab.getId() == R.id.navSearch) {
        launchActivity(ActivitySearch.class);
    }
});

```

### Kotlin Utility for Widget Updates

```kotlin
// Kotlin utility: Refresh all "Verse of the Day" widgets after UI init
private fun init() {
    initContent()
    initActions()
    updateAllVotdWidgets(this)   // defined in VotdWidgetKt
}

```

### Locale Configuration in BaseActivity

```java
// Updating the app's locale – called from BaseActivity during attachBaseContext()
private Context updateBaseContextLocale(Context context) {
    String language = SPAppConfigs.getLocale(context);
    if (!LOCALE_DEFAULT.equals(language)) {
        Locale locale = language.contains("-r")
            ? new Locale(language.split("-r")[0], language.split("-r")[1])
            : new Locale(language);
        Locale.setDefault(locale);
        // Apply locale based on OS version
        …
    }
    return context;
}

```

## Summary

- **Start with `settings.gradle.kts`** to understand the two-module structure (`:app` and `:peacedesign`).
- **Trace the activity hierarchy** from `BaseActivity` through `MainActivity` to understand initialization flows and navigation patterns.
- **Explore custom UI components** in the `widgets` and `components` directories, particularly `BottomTabLayout` for navigation.
- **Study data models** in `api/models` to understand how the app consumes translation and tafsir content.
- **Use the practical code examples** above to recognize common patterns for activity launching, locale management, and widget updates.

## Frequently Asked Questions

### How do I find the main entry point when I explore the alfaazplus/quranapp codebase?

The main entry point is [`MainActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/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 class extends `BaseActivity` and initializes the primary user interface including the ViewPager, bottom navigation, and onboarding checks. Start here to understand how the app launches and routes users to different screens.

### What is the purpose of the `peacedesign` module in the QuranApp repository?

The `peacedesign` module is a separate Gradle sub-project that houses reusable UI utilities and animation components shared across the application. For example, it contains [`DimensionAnimator.kt`](https://github.com/alfaazplus/quranapp/blob/main/DimensionAnimator.kt) for dimension-based animations. This modular approach separates generic UI tooling from domain-specific Quran logic, making components reusable and the main app module cleaner.

### How does the app handle language localization and locale changes?

Language management is centralized in [`BaseActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/BaseActivity.java) through the `updateBaseContextLocale()` method, which reads the selected language from `SPAppConfigs` shared preferences. It creates appropriate `Locale` objects (handling region codes with "-r" separators) and applies them using the Android context configuration system. This ensures all activities inherit the correct locale through the `attachBaseContext()` lifecycle method.

### Where are the data models for Quran translations and tafsir content defined?

Data models for API responses are located in `app/src/main/java/com/quranapp/android/api/models/`. Key classes include `TranslationBookInfoModel` for translation metadata, `TafsirModel` for exegesis content structure, and `AvailableTafsirsModel` for managing available tafsir sources. These POJOs define the JSON schema used when fetching remote content from the app's backend services.