# Main Activities in the alfaazplus/quranapp Android Project: Architecture and Navigation

> Explore the alfaazplus/quranapp Android project and discover its ten main activities for Quran reading, search, bookmarking, and onboarding. Learn about its architecture and navigation.

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

---

**The alfaazplus/quranapp Android project organizes its user interface around ten primary Activity classes—including MainActivity, ActivityReader, ActivitySearch, and ActivityOnboarding—that handle Quran reading, search functionality, bookmark management, and user onboarding, all inheriting from specialized base classes like ReaderPossessingActivity and BaseActivity.**

The Alfaaz Quran app is an open-source Android application that structures its navigation and UI logic through a comprehensive set of Activity components. Located in the `com.quranapp.android.activities` package, these classes manage everything from the initial onboarding flow to complex Quran reading interfaces. Understanding the main activities in the alfaazplus/quranapp Android project is essential for developers looking to customize the app, add features, or contribute to its Java and Kotlin codebase.

## Primary User-Facing Activities

The application implements distinct Activity classes for each major user flow, following Android's single-activity responsibility pattern while sharing common functionality through inheritance.

### MainActivity (Application Entry Point)

**MainActivity** serves as the centralized entry point of the app. 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 hosts the bottom navigation bar and view-pager containing the home fragment. It coordinates launches to other top-level screens including the reader index, search interface, and onboarding flow when required by checking `SPAppActions.getRequireOnboarding()`.

### ActivityReader (Quran Reading Interface)

Found in [`app/src/main/java/com/quranapp/android/activities/ActivityReader.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivityReader.java), **ActivityReader** displays the full Quran reading interface with page navigation, verse selection, and reading-related actions. This class extends `ReaderPossessingActivity` to inherit common reader utilities including bookmark handling and navigation controls, ensuring consistent behavior across reading-related screens.

### ActivityReaderIndexPage (Navigation Index)

Implemented in [`app/src/main/java/com/quranapp/android/activities/ActivityReaderIndexPage.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivityReaderIndexPage.kt), this activity presents the index of Juz, chapters, and verses. Users can jump directly to specific locations in the Quran through this interface. The activity is typically invoked from the "king-tab" in MainActivity and provides quick navigation to any surah or verse position.

### ActivitySearch (Search Functionality)

Located at [`app/src/main/java/com/quranapp/android/activities/ActivitySearch.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivitySearch.java), **ActivitySearch** provides a searchable UI for finding verses, topics, or translations. The activity launches when users tap the search tab from the main navigation bar and implements real-time filtering against the Quran database and translation packs.

### ActivityBookmark (Bookmark Management)

Found in [`app/src/main/java/com/quranapp/android/activities/ActivityBookmark.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivityBookmark.java), this activity displays saved bookmarks and allows users to add or remove them. It implements the `BookmarkCallbacks` interface to enable direct navigation to bookmarked verses, integrating closely with the bookmark persistence layer.

### ActivityChapInfo (Chapter Metadata)

Located at [`app/src/main/java/com/quranapp/android/activities/ActivityChapInfo.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivityChapInfo.java), **ActivityChapInfo** presents detailed information about specific Quran chapters including metadata, Tafsir, and related verses. The activity loads data asynchronously via `LoadChapterInfoTask` to prevent UI blocking while fetching chapter details.

### ActivityReference (Reference Materials)

Found in [`app/src/main/java/com/quranapp/android/activities/reference/ActivityReference.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/reference/ActivityReference.java), this activity shows reference material such as Hadith and scholarly notes linked to particular verses or topics. Like ActivityReader, it extends `ReaderPossessingActivity` to maintain shared reader context and bookmark synchronization.

### ActivityDownloads (Resource Management)

Located at [`app/src/main/java/com/quranapp/android/activities/ActivityDownloads.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivityDownloads.java), **ActivityDownloads** manages the download of translation packs, audio files, and other resources. The activity shows download progress indicators and allows users to trigger updates or remove existing resources to free storage space.

### ActivitySettings (App Configuration)

Found in [`app/src/main/java/com/quranapp/android/activities/readerSettings/ActivitySettings.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/readerSettings/ActivitySettings.java), this activity hosts the app-wide settings screen. It manages theme selection, notification preferences, data usage settings, and applies user preferences immediately through the `SharedPreferences` system.

### ActivityOnboarding (First-Time User Flow)

Implemented in [`app/src/main/java/com/quranapp/android/activities/ActivityOnboarding.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ActivityOnboarding.kt), **ActivityOnboarding** handles the first-time user experience. It walks new users through app features, requests necessary permissions, and completes initial configuration before transitioning to MainActivity, gating access until setup is complete.

## Base Activity Architecture

The project utilizes a three-tier inheritance hierarchy to share common functionality and reduce code duplication across the main activities.

### BaseActivity (Common Functionality)

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), this abstract class provides universal functionality for all activities in the application. It handles status-bar configuration, result callbacks, and common lifecycle methods that every screen requires regardless of specific content.

### ReaderPossessingActivity (Shared Reader Utilities)

Found in [`app/src/main/java/com/quranapp/android/activities/ReaderPossessingActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/ReaderPossessingActivity.java), this abstract class supplies shared reader utilities including bookmark handling, verse navigation, and reference management. Both **ActivityReader** and **ActivityReference** extend this class to inherit consistent reader behavior and state management.

### QuranMetaPossessingActivity (Metadata Handling)

Implemented in [`app/src/main/java/com/quranapp/android/activities/QuranMetaPossessingActivity.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/activities/QuranMetaPossessingActivity.kt), this base class provides Quran metadata such as chapter names, verse counts, and structural information to activities that need this data. It ensures that metadata is loaded efficiently and cached appropriately for child activities.

## Activity Navigation Patterns

The codebase implements consistent navigation patterns using wrapped Intent launching. Here are the typical usage examples found in the source:

To launch the reader from any activity:

```java
launchActivity(ActivityReader.class);

```

To open the chapter-info screen with a specific chapter number:

```java
Intent i = new Intent(this, ActivityChapInfo.class);
i.putExtra("chapterNo", 2); // Surah Al-Baqarah
launchActivity(i);

```

To conditionally start the onboarding flow (as implemented in MainActivity):

```java
if (SPAppActions.getRequireOnboarding(this)) {
    launchActivity(ActivityOnboarding.class);
    finish();
}

```

## Summary

- The alfaazplus/quranapp Android project implements **ten primary Activity classes** that handle distinct user flows from Quran reading to resource downloads.
- **MainActivity** functions as the central navigation hub with bottom navigation, while specialized activities like **ActivityReader** and **ActivityReference** extend **ReaderPossessingActivity** for shared functionality.
- The inheritance hierarchy includes **BaseActivity**, **ReaderPossessingActivity**, and **QuranMetaPossessingActivity** to provide common utilities and metadata access across the application.
- Inter-activity communication uses standard Android Intents with specific extras like `"chapterNo"` to pass contextual data between screens.
- **ActivityOnboarding** controls first-time user access, preventing entry to the main UI until initial configuration and permissions are completed.

## Frequently Asked Questions

### What is the entry point Activity in the alfaazplus/quranapp project?

**MainActivity** 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) serves as the application entry point. It hosts the bottom navigation bar and view-pager, checking whether to launch **ActivityOnboarding** first via `SPAppActions.getRequireOnboarding()` before displaying the main interface.

### How does ActivityReader differ from ActivityReference?

Both extend **ReaderPossessingActivity** to share bookmark handling and navigation utilities, but **ActivityReader** ([`ActivityReader.java`](https://github.com/alfaazplus/quranapp/blob/main/ActivityReader.java)) displays the full Quran text with page navigation, while **ActivityReference** ([`ActivityReference.java`](https://github.com/alfaazplus/quranapp/blob/main/ActivityReference.java)) presents supplementary materials like Hadith and scholarly notes linked to specific verses.

### Which base class should new activities extend to access Quran metadata?

Activities requiring chapter names and verse counts should extend **QuranMetaPossessingActivity** ([`QuranMetaPossessingActivity.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranMetaPossessingActivity.kt)). This base class provides asynchronous loading of Quran metadata, while **BaseActivity** ([`BaseActivity.java`](https://github.com/alfaazplus/quranapp/blob/main/BaseActivity.java)) offers universal functionality like status-bar handling for all activities.

### How are activities launched between screens in the Quran app?

The codebase uses a custom `launchActivity()` method wrapper around standard Android Intents. For example, launching **ActivityChapInfo** requires passing a chapter number via `Intent.putExtra("chapterNo", chapterId)`, while simple navigation uses `launchActivity(ActivityReader.class)`.