# Understanding the Project Structure of alfaazplus/quranapp: Android Multi-Module Architecture

> Explore the alfaazplus/quranapp Android multi-module architecture. Understand its app core functionality, reusable peacedesign UI library, and inventory data structure for efficient development.

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

---

**The alfaazplus/quranapp repository follows a clean Android Gradle multi-module architecture consisting of the main `app` module for core functionality, a reusable `peacedesign` UI library module, and an `inventory` directory for static JSON data assets.**

The alfaazplus/quranapp is an open-source Android Quran application built with modern Android development practices and Jetpack libraries. Understanding its project structure is essential for contributors looking to navigate the codebase, debug issues, or extend functionality. This guide breaks down the multi-module Gradle setup, key source directories, and architectural decisions implemented in the repository.

## Multi-Module Gradle Architecture

The project root contains standard Gradle configuration files that orchestrate the build across modules. The **`build.gradle.kts`** file at the repository root defines the Kotlin version (`2.2.21`) and plugins used across all modules, while **`settings.gradle.kts`** registers the two primary modules: `:app` and `:peacedesign`.

```kotlin
// settings.gradle.kts
include(":app", ":peacedesign")

```

This separation allows the **Peacedesign** UI toolkit to develop independently while being consumed as a library dependency by the main application.

## The `app` Module: Core Application Structure

The `app/` directory contains the primary Android application module where all user-facing functionality resides. This module follows standard Android source set conventions with `src/main/` containing production code and resources.

### Build Configuration and Dependencies

The **`app/build.gradle.kts`** file defines the application's dependency graph, integrating modern Android stack components including the **Compose BOM** for declarative UI, **ExoPlayer** for audio streaming, **WorkManager** for background tasks, **Retrofit** for networking, and **Kotlinx Serialization** for JSON handling.

```kotlin
// app/build.gradle.kts
implementation(libs.compose.material3)
implementation(libs.exoplayerCore)
implementation(libs.workManager)
implementation(libs.retrofit)

```

Additional utilities include Guava, Apache Commons, and SmoothRefreshLayout for enhanced UI interactions.

### Android Manifest and Entry Points

The **[`app/src/main/AndroidManifest.xml`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/AndroidManifest.xml)** declares the complete application structure, including the entry point at `MainActivity`, the reader interface via `ActivityReader`, background services like `RecitationService`, and broadcast receivers for widgets and system events.

Key declarations include:
- `com.quranapp.android.activities.MainActivity` – The launcher activity
- `com.quranapp.android.utils.services.RecitationService` – Foreground service for audio playback
- Various receivers for widget updates, boot events, and crash reporting

### Source Code Organization

The Kotlin source code under `app/src/main/java/com/quranapp/android/` follows package-based separation of concerns:

- **`activities/`** – UI screens including [`MainActivity.kt`](https://github.com/alfaazplus/quranapp/blob/main/MainActivity.kt), `ActivityReader`, settings, and reference activities
- **`utils/`** – Helper classes for networking, **WorkManager** workers, background services, and custom broadcast receivers
- **`components/`** – Data models for translations, tafsir, and verse references
- **`widgets/`** – Custom UI widgets built atop the **Peacedesign** library

### Assets and Static Resources

The `app/src/main/assets/` directory houses runtime JSON data including [`quran_meta.json`](https://github.com/alfaazplus/quranapp/blob/main/quran_meta.json) (containing chapter metadata), while `app/src/main/res/` contains Android resources such as layouts, drawables, and [`values/strings.xml`](https://github.com/alfaazplus/quranapp/blob/main/values/strings.xml) with translation placeholders. The [`xml/searchable.xml`](https://github.com/alfaazplus/quranapp/blob/main/xml/searchable.xml) file configures the Android search framework integration.

## The `peacedesign` Library Module

The `peacedesign/` module is an independent **UI component library** providing reusable widgets throughout the application. Located at `peacedesign/src/main/java/com/peacedesign/`, this library abstracts common UI patterns into maintainable components.

Key implementations include:
- **`PeaceBottomSheetDialog`** – Customizable bottom sheet dialogs with theming support
- **`PeaceDialog`** – Alert dialog variations with consistent styling
- Custom radio groups, checkboxes, and spinners using the library's attribute system

The library maintains its own resources under `peacedesign/src/main/res/values/` for styles ([`styles.xml`](https://github.com/alfaazplus/quranapp/blob/main/styles.xml)) and custom attributes ([`attrs.xml`](https://github.com/alfaazplus/quranapp/blob/main/attrs.xml)), ensuring visual consistency across the app.

```kotlin
// Using Peacedesign components
val sheet = PeaceBottomSheetDialog(context).apply {
    setTitle("Choose Translation")
    setAdapter(translationAdapter)
    setOnItemClickListener { position ->
        // handle selection
        dismiss()
    }
}
sheet.show()

```

## Data Management with the `inventory` Directory

The `inventory/` directory at the project root serves as an external data repository shipped with the application. This structure separates volatile data assets from source code:

- **`inventory/translations/`** – JSON language packs for Quranic translations
- **`inventory/versions/`** – Version tracking files including [`app_updates.json`](https://github.com/alfaazplus/quranapp/blob/main/app_updates.json) for in-app update prompts
- **`inventory/tafsir/`** – Tafsir (exegesis) metadata indexes
- **`inventory/fonts/`** – Custom Quranic typography assets

The application loads these resources at runtime via preference helpers like `SPAppConfigs`, allowing offline-first functionality without hardcoding linguistic data.

## Background Processing Architecture

The app implements robust background execution through a combination of deferred work and foreground services.

### WorkManager for Deferred Tasks

**WorkManager** handles on-demand downloads of language packs and tafsir content through dedicated worker classes. The [`TranslationDownloadWorker.kt`](https://github.com/alfaazplus/quranapp/blob/main/TranslationDownloadWorker.kt) and [`TafsirDownloadWorker.kt`](https://github.com/alfaazplus/quranapp/blob/main/TafsirDownloadWorker.kt) files in `app/src/main/java/com/quranapp/android/utils/workers/` encapsulate download logic with retry policies and progress reporting.

```kotlin
// Scheduling a translation download
val downloadRequest = OneTimeWorkRequestBuilder<TranslationDownloadWorker>()
    .setInputData(workDataOf("lang" to "en"))
    .build()

WorkManager.getInstance(context).enqueue(downloadRequest)

```

### Foreground Services for Audio

For continuous audio playback, the app utilizes foreground services declared in the manifest. The **[`RecitationService.kt`](https://github.com/alfaazplus/quranapp/blob/main/RecitationService.kt)** manages streaming of Quranic recitations, while `RecitationChapterDownloadService` handles chapter-by-chapter offline caching without interrupting the user experience.

## CI/CD and Release Infrastructure

The repository includes comprehensive automation for quality assurance and distribution:

- **[`.github/workflows/ci.yml`](https://github.com/alfaazplus/quranapp/blob/main/.github/workflows/ci.yml)** – GitHub Actions workflow running unit tests, linting, and APK builds on every push
- **`fastlane/metadata/android/`** – Play Store assets including localized descriptions, screenshots, and changelogs for automated releases
- **`repo_assets/`** – Widget icons, screenshots, and archived APKs for distribution outside the Play Store

## Summary

- The project uses a **multi-module Gradle structure** with `:app` and `:peacedesign` modules for separation of concerns
- **Modern Android architecture** leverages Jetpack Compose, ExoPlayer, WorkManager, and Retrofit as defined in `app/build.gradle.kts`
- Source code organizes UI, utilities, and data models into distinct packages under `com.quranapp.android`
- The **`inventory/`** directory externalizes translation data, fonts, and version metadata from the main source tree
- Background operations combine **WorkManager** for deferred downloads and foreground services for audio streaming
- **Fastlane** and **GitHub Actions** provide automated CI/CD pipelines for testing and Play Store deployment

## Frequently Asked Questions

### What modules make up the alfaazplus/quranapp project?

The project consists of two Gradle modules: the `:app` module containing the main Android application with all UI and business logic, and the `:peacedesign` module serving as a reusable UI component library. The root `settings.gradle.kts` registers both modules for compilation.

### Where are the Quran translations stored in the project?

Translation files reside in the **`inventory/translations/`** directory as JSON language packs, separate from the application source code. The app loads these at runtime from the assets directory, with metadata indexes helping the `TranslationDownloadWorker` manage on-demand downloads via WorkManager.

### How does the app handle background downloads of recitations and translations?

The app uses **WorkManager** for deferred, reliable downloads of text resources through `TranslationDownloadWorker` and `TafsirDownloadWorker`. For audio recitations, it implements foreground services like `RecitationService` and `RecitationChapterDownloadService` declared in [`AndroidManifest.xml`](https://github.com/alfaazplus/quranapp/blob/main/AndroidManifest.xml) to maintain persistent downloads without interruption.

### What is the purpose of the peacedesign module?

The **`peacedesign`** module is a standalone UI toolkit providing reusable components such as `PeaceBottomSheetDialog` and custom form controls. This library approach ensures consistent theming and behavior across different screens while allowing independent development and testing of UI components.