# alfaazplus/quranapp architecture

> Architecture diagram of the GitHub repository alfaazplus/quranapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alfaazplus/quranapp
- Repository: https://github.com/alfaazplus/quranapp

## Overview

##### Project type and purpose
- This is a native Android mobile application (“QuranApp”) with one main Gradle module (`app/`) and a secondary UI library module (`peacedesign/`).
- Purpose: Provide an ad-free, privacy-focused Quran reading and exploration experience.

##### File structure
- Top-level modules:
- `app/` – the main application containing UI, business logic, data, assets and resources.
- `peacedesign/` – a reusable UI component library (dialogs, animations, widgets, utils).
- `app/src/main/java/com/quranapp/android/` subdivides into:
- `activities/`, `frags/`, `views/`, `viewModels/` → presentation layer (Screens + ViewModels).
- `api/` → Retrofit configuration, remote endpoints (QuranApi, GithubApi) and related model classes.
- `db/` → SQLite contracts & helpers for bookmarks, search history, translations, read history.
- `components/` → data models shared across layers.
- `reader_managers/`, `utils/`, `interfaceUtils/`, `services/`, `receivers/` → domain and background services.
- `adapters/`, `vh/` → RecyclerView adapters and view holders.
- `app/src/main/assets/` and `inventory/` store static JSON data for verses, translations, recitations, tafsir, fonts and version manifests.
- Build, CI and deployment files: `build.gradle`, GitHub Actions (`.github/workflows/ci.yml`), Fastlane metadata.

##### README
- Confirms it’s a feature-rich Quran reading app: multiple fonts, translations, recitations, reminders.
- Points to external data sources (QuranEnc, Tanzil, quran.com) and shows distribution targets (Google Play, F-Droid).

a. Main components
- UI Layer
– Activities & Fragments
– Custom Views & Widgets (from `peacedesign/` and `app/src/main/java/.../views`)
- Presentation Layer
– ViewModels (MVVM)
– Adapters & ViewHolders
- Domain & Business Services
– ReaderManagers (navigation, rendering logic)
– Background Services & Broadcast Receivers (downloads, network state, VOTD)
- Data Layer
– Local Data Sources:
· SQLite DB via DBHelpers (bookmarks, history, search, translations)
· SharedPreferences (SPReader, SPAppConfigs, etc.)
· Asset JSON files (verses, translations, tafsir, fonts)
– Remote Data Sources:
· Retrofit APIs (QuranApi, GithubApi)
· Inventory JSON (versions, recitation info)
- External Services
– Google Play / F-Droid (app distribution)
– Third-party data providers (QuranEnc, quran.com)
– CI/CD pipeline (GitHub Actions, Fastlane)

b. Relationships & interactions
- UI → Presentation: user events in Activities/Fragments call ViewModel methods.
- Presentation → Domain: ViewModel invokes ReaderManagers and Business Services to process data.
- Domain → Data: services query local DB/assets first, fall back to remote APIs, then persist updates.
- Background services triggered by Receivers (e.g., network available → start TranslationDownloadService).
- Peacedesign UI library is consumed by `app/` for consistent dialog and widget rendering.

c. Architectural patterns & principles
- MVVM separation: Activities/Fragments (View) ↔ ViewModels ↔ Data layer.
- Repository-style data abstraction: local and remote sources behind helpers and APIs.
- Modularization: separate UI library (`peacedesign/`) from core app.
- SingleResponsibility: each package has a distinct concern (api, db, utils, components).
- Dependency injection patterns (manual or via RetrofitInstance).

d. Key technologies & libraries
- Kotlin & Java on Android SDK
- AndroidX Components (ViewModel, LiveData, RecyclerView, Room-style DB helpers)
- Retrofit + OkHttp for HTTP APIs
- Gradle multi-module build
- Fastlane for release metadata
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        UI_Activities["Activities"]:::ui
        UI_Fragments["Fragments"]:::ui
        UI_CustomViews["Custom Views"]:::ui
        UI_Widgets["PeaceDesign Widgets"]:::ui
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        VM["ViewModels"]:::presentation
        ADP["Adapters"]:::presentation
        VH["ViewHolders"]:::presentation
    end

    %% Domain & Business Services
    subgraph "Domain & Business Services"
        direction TB
        RM["ReaderManagers"]:::domain
        BS["Background Services"]:::domain
        BR["Broadcast Receivers"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["SQLite DB Helpers"]:::storage
        SP["SharedPreferences"]:::storage
        AS["Asset JSON Store"]:::storage
        INV["Inventory JSON"]:::storage
        API["Retrofit APIs"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        TP["Third-Party Data Providers"]:::external
        DIST["App Distribution"]:::external
    end

    %% CI/CD & Build
    subgraph "CI/CD & Build"
        direction TB
        CI["GitHub Actions"]:::ci
        FL["Fastlane Metadata"]:::ci
        GRADLE["Gradle Config"]:::ci
    end

    %% Relationships
    UI_Activities -->|"user events"| VM
    UI_Fragments -->|"user events"| VM
    UI_CustomViews -->|renders| VM
    UI_Widgets -->|renders| VM

    VM -->|"invokes"| RM
    VM -->|"invokes"| BS

    BR -.->|"triggers"| BS
    BS -->|"queries"| DB
    BS -->|"reads/writes"| SP
    BS -->|"loads"| AS
    BS -->|"reads"| INV
    BS -->|"requests"| API

    RM -->|"queries"| DB
    RM -->|"reads"| AS
    RM -->|"fetches"| API

    TP -.-> API
    DIST -.-> UI_Activities

    CI -->|builds/deploys| DIST
    FL -->|manages metadata| DIST
    GRADLE -->|configures| UI_Activities

    %% Click Events
    click UI_Activities "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/activities/"
    click UI_Fragments "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/frags/"
    click UI_CustomViews "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/views/"
    click UI_Widgets "https://github.com/alfaazplus/quranapp/tree/master/peacedesign/src/main/java/com/peacedesign/android/widget/"
    click VM "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/viewModels/"
    click ADP "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/adapters/"
    click VH "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/vh/"
    click RM "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/reader_managers/"
    click BS "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/utils/services/"
    click BR "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/utils/receivers/"
    click API "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/api/"
    click DB "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/db/"
    click SP "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/java/com/quranapp/android/utils/sharedPrefs/"
    click AS "https://github.com/alfaazplus/quranapp/tree/master/app/src/main/assets/"
    click INV "https://github.com/alfaazplus/quranapp/tree/master/inventory/"
    click CI "https://github.com/alfaazplus/quranapp/blob/master/.github/workflows/ci.yml"
    click FL "https://github.com/alfaazplus/quranapp/tree/master/fastlane/metadata/android/"
    click GRADLE "https://github.com/alfaazplus/quranapp/blob/master/build.gradle"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#007bff,stroke-width:2px
    classDef presentation fill:#e6ffe6,stroke:#28a745,stroke-width:2px
    classDef domain fill:#f0f0f0,stroke:#6c757d,stroke-width:2px
    classDef storage fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef api fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef external fill:#ffe5b4,stroke:#e65c00,stroke-width:2px,stroke-dasharray: 5 5
    classDef ci fill:#e2e3e5,stroke:#343a40,stroke-width:2px
```
