# How to Contribute to the alfaazplus/quranapp Project: A Complete Developer’s Guide

> Learn how to contribute to the alfaazplus/quranapp project. Set up Android Studio, understand modular architecture, and submit pull requests following Kotlin conventions.

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

---

**Contributing to the alfaazplus/quranapp project requires setting up Android Studio with Kotlin support, understanding the six-layer modular architecture, and submitting pull requests that follow the Kotlin coding conventions defined in [`kotlin_code_style.xml`](https://github.com/alfaazplus/quranapp/blob/main/kotlin_code_style.xml).**

The alfaazplus/quranapp repository is an open-source Android application built with Kotlin and Jetpack Compose that enables users to read, explore, and interact with the Qur’an. Whether you aim to fix bugs, add new translations, or implement UI improvements, understanding how to contribute to the alfaazplus/quranapp project begins with mastering its layered architecture and established contribution workflows.

## Understanding the QuranApp Architecture

The codebase is organized into six specialized layers that enforce separation of concerns. Each layer has distinct responsibilities, reference implementations, and specific file locations within the repository.

### App Core Layer

The **App Core** handles Android UI components, activities, fragments, and Jetpack Compose themes. The entry point resides in [`app/src/main/java/com/quranapp/android/QukanApp.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/QukanApp.kt), which initializes Dagger/Hilt, DataStore, and sets the application theme. Reader functionality is managed by [`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), while theme definitions and color schemes are defined in [`app/src/main/java/com/quranapp/android/compose/theme/Theme.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/compose/theme/Theme.kt).

### Data and Persistence Layer

This layer manages local storage using **Room** database helpers and **Jetpack DataStore** for caching user preferences and content. Translation database operations are handled by [`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), while persistent app settings are managed through [`app/src/main/java/com/quranapp/android/compose/utils/shared_preference/DataStoreManager.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/compose/utils/shared_preference/DataStoreManager.kt).

### Network Layer

**Retrofit-based API clients** handle remote resource fetching for translations, recitations, and app updates. The [`app/src/main/java/com/quranapp/android/api/RetrofitInstance.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/api/RetrofitInstance.kt) file configures the base URL and JSON converter, while [`app/src/main/java/com/quranapp/android/api/AlfaazPlusApi.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/api/AlfaazPlusApi.kt) defines the service interfaces. API response models, such as [`app/src/main/java/com/quranapp/android/api/models/translation/TranslationBookInfoModel.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/api/models/translation/TranslationBookInfoModel.kt), provide type-safe data structures for network responses.

### Parsers and Utilities

Kotlin parsers convert raw JSON assets into in-memory domain models. The [`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) processes the main verses JSON, while specialized parsers like [`QuranProphetParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranProphetParser.kt) and [`MajorSinVersesParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/MajorSinVersesParser.kt) handle prophet biographies and religious guideline content respectively.

### Background Workers

**WorkManager** implementations manage asynchronous downloads and storage cleanup. The [`app/src/main/java/com/quranapp/android/utils/workers/TranslationDownloadWorker.kt`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/java/com/quranapp/android/utils/workers/TranslationDownloadWorker.kt) handles translation file fetching with proper error handling for network states, while [`TafsirDownloadWorker.kt`](https://github.com/alfaazplus/quranapp/blob/main/TafsirDownloadWorker.kt) manages commentary downloads. These workers implement `CoroutineWorker` and must catch `NoInternetException` for retry logic.

### Resources and Assets

Static content resides in `app/src/main/assets/`, including prebuilt translations (`prebuilt_translations/`), verse structures (`verses/type2/*.json`), and science topic HTML files (`science/topics/*.html`).

## Setting Up Your Development Environment

Before you contribute to the alfaazplus/quranapp project, configure your local environment:

1. Install **Android Studio Arctic Fox** or newer with the Android SDK and Kotlin plugins.
2. Clone the repository and open the project—the Gradle wrapper is preconfigured in `build.gradle.kts` at the repository root.
3. Execute `./gradlew assembleDebug` from the terminal to build the debug APK and verify the configuration.
4. Launch the application using Android Studio’s Run button on either an emulator or physical device running Android API level 21 or higher.

## Contribution Pathways

The repository accepts multiple contribution types, each following specific technical patterns and file locations.

### Code Contributions

Submit bug fixes, UI improvements, or architectural refactoring by forking the repository, creating a descriptive feature branch, and opening a pull request. The [`CONTRIBUTING.md`](https://github.com/alfaazplus/quranapp/blob/main/CONTRIBUTING.md) file at the repository root outlines branch naming conventions, commit message standards, and the complete pull request workflow.

### Translation Contributions

Add or improve Qur’an translations by contributing JSON files to `inventory/translations/`. Each translation requires a manifest file and data files placed in `app/src/main/assets/prebuilt_translations/[translation_id]/`. The files must follow the JSON schema used by [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt) for proper ingestion.

### Recitation Additions

Submit new free API URLs to [`inventory/recitations/available_recitations_info.json`](https://github.com/alfaazplus/quranapp/blob/main/inventory/recitations/available_recitations_info.json) to expand the audio recitation options available to users. Ensure the URLs point to publicly accessible, properly licensed content.

### UI Localization

Translate the application interface by modifying string resources in `app/src/main/res/values-<lang>/strings.xml`, or join the Weblate project for collaborative translation management of UI elements, menus, and user prompts.

## Implementing New Features

When adding functionality to the alfaazplus/quranapp source code, follow these implementation patterns derived from the existing architecture.

### Adding a Quran Translation

Create a data class structure matching your JSON schema, then register the translation in the repository layer:

```kotlin
data class MyNewTranslation(val suras: List<Sura>)
data class Sura(val index: Int, val ayas: List<Aya>)
data class Aya(val id: Int, val index: Int, val translation: String)

// Registration in the repository
val translationInfo = TranslationInfo(
    id = "en_mynewtranslation",
    name = "My New English Translation",
    language = "en",
    path = "prebuilt_translations/en_mynewtranslation/en_mynewtranslation.json"
)
TranslationRepository.addTranslation(translationInfo)

```

Place manifest files in `app/src/main/assets/prebuilt_translations/[id]/manifest.json` and data files alongside them, following the asset management pattern established in [`TranslationDownloadWorker.kt`](https://github.com/alfaazplus/quranapp/blob/main/TranslationDownloadWorker.kt).

### Creating Background Workers

Extend `CoroutineWorker` for any network operations that must survive configuration changes:

```kotlin
class MyFeatureDownloadWorker(
    ctx: Context,
    params: WorkerParameters
) : CoroutineWorker(ctx, params) {

    override suspend fun doWork(): Result = try {
        val url = inputData.getString("download_url")!!
        val json = NetworkHelper.get(url) // Uses RetrofitInstance
        FileHelper.saveJson(applicationContext, "my_feature.json", json)
        Result.success()
    } catch (e: NoInternetException) {
        Result.retry()
    } catch (e: HttpNotFoundException) {
        Result.failure()
    } catch (e: Exception) {
        Result.failure()
    }
}

```

Enqueue workers through `WorkManager.getInstance(context)` when users trigger downloads or toggle settings in the UI.

### Building New Activities

Create new activities by extending `AppCompatActivity` and utilizing ViewBinding for view access:

```kotlin
class ActivityMyFeature : AppCompatActivity() {

    private val binding: ActivityMyFeatureBinding by lazy {
        ActivityMyFeatureBinding.inflate(layoutInflater)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(binding.root)
        
        binding.btnDownload.setOnClickListener {
            val workRequest = OneTimeWorkRequestBuilder<MyFeatureDownloadWorker>()
                .setInputData(workDataOf("download_url" to "https://example.com/data.json"))
                .build()
            WorkManager.getInstance(this).enqueue(workRequest)
        }
    }
}

```

Declare all new activities in [`app/src/main/AndroidManifest.xml`](https://github.com/alfaazplus/quranapp/blob/main/app/src/main/AndroidManifest.xml) and create corresponding layout XML files in `app/src/main/res/layout/`.

## Architectural Guidelines for Contributors

Follow these strict conventions when modifying the alfaazplus/quranapp codebase:

- **Kotlin Coding Style**: Adhere to the conventions defined in [`kotlin_code_style.xml`](https://github.com/alfaazplus/quranapp/blob/main/kotlin_code_style.xml) at the repository root. The CI workflow enforces these standards automatically.
- **Parser Patterns**: Use existing parsers like [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt) as templates. Each JSON asset requires a matching parser class implementing `ParserUtils` conventions for consistency.
- **Error Handling**: Workers must distinguish between `NoInternetException` (triggering `Result.retry()`) and `HttpNotFoundException` (triggering `Result.failure()`).
- **Testing Strategy**: Place instrumentation tests for UI changes in `app/src/androidTest/` and unit tests for core logic in `app/src/test/`.
- **Documentation Updates**: Modify [`README.md`](https://github.com/alfaazplus/quranapp/blob/main/README.md), [`FEATURES.md`](https://github.com/alfaazplus/quranapp/blob/main/FEATURES.md), and DeepWiki entries when adding public-facing features or changing user workflows.

## Summary

Contributing to the alfaazplus/quranapp project requires understanding these critical technical elements:

- The architecture separates UI, data persistence, network communication, JSON parsing, and background processing into six distinct layers.
- **TranslationDownloadWorker.kt** and similar `CoroutineWorker` implementations handle all background downloads using WorkManager with specific exception handling.
- Translation contributions involve validated JSON files in `inventory/translations/` and proper asset registration in the prebuilt translations directory.
- New activities must be declared in [`AndroidManifest.xml`](https://github.com/alfaazplus/quranapp/blob/main/AndroidManifest.xml), use ViewBinding for view access, and follow the activity patterns established in [`ActivityReaderIndexPage.kt`](https://github.com/alfaazplus/quranapp/blob/main/ActivityReaderIndexPage.kt).
- The project maintains strict Kotlin coding conventions verified through the CI workflow defined in [`.github/workflows/ci.yml`](https://github.com/alfaazplus/quranapp/blob/main/.github/workflows/ci.yml).

## Frequently Asked Questions

### What programming languages and frameworks power the alfaazplus/quranapp project?

The application is built exclusively with **Kotlin** for Android, utilizing **Jetpack Compose** for UI theming as implemented in [`Theme.kt`](https://github.com/alfaazplus/quranapp/blob/main/Theme.kt), **Room** for local SQLite database persistence, **Retrofit** for REST API communication via [`RetrofitInstance.kt`](https://github.com/alfaazplus/quranapp/blob/main/RetrofitInstance.kt), and **WorkManager** for background processing. The project requires Android Studio Arctic Fox or newer to build successfully.

### How do I add a new Quran translation to the application?

Create a JSON file containing the translation data formatted according to the schema used in [`QuranParser.kt`](https://github.com/alfaazplus/quranapp/blob/main/QuranParser.kt), then place it in `app/src/main/assets/prebuilt_translations/[unique_id]/`. Define Kotlin data classes matching your JSON structure, then register the translation using `TranslationRepository.addTranslation()` with a `TranslationInfo` object specifying the ISO language code, display name, and relative file path.

### Where should I implement background download logic in the codebase?

All background network operations belong in the **Workers** layer under `app/src/main/java/com/quranapp/android/utils/workers/`. Extend `CoroutineWorker` and implement `doWork()` with specific exception handling: catch `NoInternetException` to return `Result.retry()` and `HttpNotFoundException` for permanent failures. Register your worker with `WorkManager` and enqueue it from UI components after user action or setting changes.

### How are pull requests reviewed and merged into the main branch?

Pull requests trigger the **CI workflow** defined in [`.github/workflows/ci.yml`](https://github.com/alfaazplus/quranapp/blob/main/.github/workflows/ci.yml), which executes automated tests and validates Kotlin code style against [`kotlin_code_style.xml`](https://github.com/alfaazplus/quranapp/blob/main/kotlin_code_style.xml). Maintainers review for architectural consistency, proper error handling in worker classes, and adherence to parser utility patterns. Contributors must provide clear descriptions referencing related issues and ensure branches follow the fork-and-branch workflow outlined in [`CONTRIBUTING.md`](https://github.com/alfaazplus/quranapp/blob/main/CONTRIBUTING.md) before merge approval.