# ammar-elmesaly/prayertimes architecture

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

- Interactive diagram: https://gitdiagram.com/ammar-elmesaly/prayertimes
- Repository: https://github.com/ammar-elmesaly/prayertimes

## Overview

##### Project Type and Purpose
- This is a single-widget Plasma 6 application written in QML and JavaScript.
- Its sole purpose is to fetch daily prayer times from the Aladhan API (via Fahim Shahriar’s AdhanTimes code) and render them inside Plasma.

##### High-Level Components
A. Host Environment
– KDE Plasma 6 Shell
– Widget Engine (loads metadata.json and QML)
B. Widget Package
1. metadata.json
2. contents/
- config/
– config.qml (defines config keys & defaults)
– main.xml (layout of the Settings UI)
- ui/
– main.qml (root UI item, ties everything together)
– CompactRepresentation.qml (small form factor view)
– PrayerTimeBlock.qml (individual prayer time display)
– configGeneral.qml (in-widget settings panel)
C. Data & Logic
– AdhanTimes JavaScript code (embedded in QML)
– QNetworkAccessManager (QML HTTP requests)
– Local Configuration Storage (via KConfig)
D. External Service
– Aladhan.com Prayer Times API

##### Relationships & Data Flow
1. Plasma Shell → loads metadata.json
2. Widget Engine → instantiates QML (main.qml)
3. main.qml → reads user settings via config engine (config.qml XML file)
4. QML/JS Logic → uses AdhanTimes code + QNetworkAccessManager to call Aladhan API
5. API Response → parsed by JS → data model populated
6. UI Components (PrayerTimeBlock.qml, CompactRepresentation.qml) → consume model data → render on screen
7. User Interaction → configGeneral.qml updates settings → writes back via KConfig

##### Architectural Patterns & Design Principles
- Model-View separation: QML files define Views; JS/QNetwork calls supply the Model.
- Configuration Engine: KConfig-backed UI (config.qml + main.xml).
- Reuse & Extensibility: AdhanTimes code is imported, allowing easy swaps or extensions to other prayer-time sources.

##### Final Checklist
– [ ] Host environment (Plasma 6 Shell + Widget Engine)
– [ ] Widget package structure (metadata.json, contents/)
– [ ] UI components (with file-names)
– [ ] Configuration subsystem
– [ ] Data-fetching logic (AdhanTimes + QNetwork)
– [ ] External API endpoint

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Environment"
        PS["KDE Plasma 6 Shell"]:::host
        WE["Widget Engine"]:::host
    end
    PS --> WE

    subgraph "Widget Package"
        MET["metadata.json"]:::doc
        click MET "https://github.com/ammar-elmesaly/prayertimes/blob/main/metadata.json"
        WE --> MET
        subgraph contents/
            click contents "https://github.com/ammar-elmesaly/prayertimes/tree/main/contents/"
            subgraph config
                CQ["config.qml"]:::configDoc
                click CQ "https://github.com/ammar-elmesaly/prayertimes/blob/main/contents/config/config.qml"
                MX["main.xml"]:::configDoc
                click MX "https://github.com/ammar-elmesaly/prayertimes/blob/main/contents/config/main.xml"
            end
            subgraph ui
                MAINQML["main.qml"]:::ui
                click MAINQML "https://github.com/ammar-elmesaly/prayertimes/blob/main/contents/ui/main.qml"
                CR["CompactRepresentation.qml"]:::ui
                click CR "https://github.com/ammar-elmesaly/prayertimes/blob/main/contents/ui/CompactRepresentation.qml"
                PTB["PrayerTimeBlock.qml"]:::ui
                click PTB "https://github.com/ammar-elmesaly/prayertimes/blob/main/contents/ui/PrayerTimeBlock.qml"
                CG["configGeneral.qml"]:::ui
                click CG "https://github.com/ammar-elmesaly/prayertimes/blob/main/contents/ui/configGeneral.qml"
            end
        end
        WE --> MAINQML
    end

    subgraph "Logic & Data"
        ADHAN["AdhanTimes JS"]:::doc
        click ADHAN "https://github.com/ammar-elmesaly/prayertimes/blob/main/sources.md"
        QNAM["QNetworkAccessManager"]:::logic
        KC["KConfig Engine"]:::logic
    end

    subgraph "External Service"
        API["Aladhan.com Prayer Times API"]:::external
    end

    MAINQML --> CQ
    MAINQML --> ADHAN
    ADHAN --> QNAM
    QNAM -->|"HTTP Request"| API
    API -->|"Response"| ADHAN
    ADHAN --> MAINQML
    MAINQML --> PTB
    MAINQML --> CR
    CG -->|"writes settings"| KC
    KC --> MX

    classDef host fill:#f9f,stroke:#333,stroke-width:2px
    classDef widget fill:#bbf,stroke:#333
    classDef doc fill:#ffd,stroke:#333,stroke-dasharray:5 5
    classDef ui fill:#bfb,stroke:#333
    classDef configDoc fill:#ffb,stroke:#333
    classDef logic fill:#fbc,stroke:#333
    classDef external fill:#fcf,stroke:#333,stroke-width:2px,stroke-dasharray:2 2
```
