# aparsi0/athan_app architecture

> Architecture diagram of the GitHub repository aparsi0/athan_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aparsi0/athan_app
- Repository: https://github.com/aparsi0/athan_app

## Overview

Athan App is a cross-platform prayer-time and audio application, with a separate browser/PWA version. The desktop workflow detects location, obtains prayer times, schedules prayer and reminder events, then plays audio; the tray and dashboard expose status and controls. The README also documents web Quran, radio, and sky features. Desktop connections are grounded in excerpts or the source index; browser internals were not sampled, so their relationships are shown as unverified dashed edges.

Main entry points: [`main.py`](https://github.com/aparsi0/athan_app/blob/main/main.py) (Desktop Controller), [`docs/js/app.js`](https://github.com/aparsi0/athan_app/blob/main/docs/js/app.js) (Web App), [`gui/main_window.py`](https://github.com/aparsi0/athan_app/blob/main/gui/main_window.py) (Dashboard UI), [`gui/system_tray.py`](https://github.com/aparsi0/athan_app/blob/main/gui/system_tray.py) (System Tray)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Runtime"]
  node_desktop_entry["Desktop Controller<br/>[main.py]"]
  node_headless_entry["Headless Controller<br/>[main_headless.py]"]
  node_tray["System Tray<br/>[system_tray.py]"]
  node_dashboard["Dashboard UI<br/>[main_window.py]"]
  node_settings_ui["Settings UI<br/>[settings_window.py]"]
  node_commands["Dashboard Commands<br/>[app_commands.py]"]
  node_settings["Configuration<br/>[settings.py]"]
  node_paths["Runtime Paths<br/>[app_paths.py]"]
end

subgraph group_prayer["Prayer Services"]
  node_location["Location Detection"]
  node_geo_api["IP Geolocation"]
  node_prayer_times["Prayer Times<br/>[prayer_times.py]"]
  node_aladhan["Aladhan API"]
  node_scheduler["Event Scheduler<br/>[scheduler.py]"]
end

subgraph group_audio["Audio Features"]
  node_audio_manager["Prayer Audio<br/>[audio_player.py]"]
  node_vlc["VLC Playback"]
  node_quran_player["Quran Player<br/>[quran_player.py]"]
  node_quran_library["Reciter Library<br/>[quran_library.py]"]
end

subgraph group_web["Browser App"]
  node_web_app["Web App<br/>[app.js]"]
  node_web_location["Web Location<br/>[location.js]"]
  node_web_prayers["Web Prayer Times<br/>[prayer-times.js]"]
  node_web_scheduler["Web Scheduler<br/>[scheduler.js]"]
  node_web_audio["Web Audio<br/>[audio.js]"]
  node_web_quran["Quran Tab<br/>[reciters.js]"]
  node_web_scene["Living Sky<br/>[scene.js]"]
  node_web_radio["Cairo Radio<br/>[audio-players.js]"]
  node_web_service_worker["PWA Worker<br/>[sw.js]"]
end

node_user(("User"))
node_browser(("Browser User"))

node_user -->|"starts"| node_desktop_entry
node_desktop_entry -->|"detects location"| node_location
node_location -->|"queries providers"| node_geo_api
node_desktop_entry -->|"loads preferences"| node_settings
node_desktop_entry -->|"requests times"| node_prayer_times
node_prayer_times -->|"fetches times"| node_aladhan
node_desktop_entry -->|"configures schedule"| node_scheduler
node_scheduler -->|"refreshes times"| node_prayer_times
node_desktop_entry -->|"sets up playback"| node_audio_manager
node_audio_manager -->|"plays audio"| node_vlc
node_desktop_entry -->|"starts Quran"| node_quran_player
node_quran_player -->|"reads reciters"| node_quran_library
node_desktop_entry -->|"starts tray"| node_tray
node_tray -->|"launches window"| node_dashboard
node_tray -.->|"requests status"| node_desktop_entry
node_dashboard -->|"controls playback"| node_quran_player
node_dashboard -.->|"offers settings"| node_settings_ui
node_dashboard -->|"writes commands"| node_commands
node_commands -->|"consumed by daemon"| node_desktop_entry
node_desktop_entry -.->|"alternative runtime"| node_headless_entry
node_settings -->|"uses config paths"| node_paths
node_browser -->|"opens app"| node_web_app
node_web_app -.->|"uses location"| node_web_location
node_web_app -.->|"shows prayer times"| node_web_prayers
node_web_app -.->|"schedules audio"| node_web_scheduler
node_web_app -.->|"plays reminders"| node_web_audio
node_web_app -.->|"offers Quran"| node_web_quran
node_web_app -.->|"shows sky"| node_web_scene
node_web_app -.->|"offers radio"| node_web_radio
node_web_app -.->|"installs as PWA"| node_web_service_worker

click node_desktop_entry "https://github.com/aparsi0/athan_app/blob/main/main.py"
click node_headless_entry "https://github.com/aparsi0/athan_app/blob/main/main_headless.py"
click node_tray "https://github.com/aparsi0/athan_app/blob/main/gui/system_tray.py"
click node_dashboard "https://github.com/aparsi0/athan_app/blob/main/gui/main_window.py"
click node_settings_ui "https://github.com/aparsi0/athan_app/blob/main/gui/settings_window.py"
click node_commands "https://github.com/aparsi0/athan_app/blob/main/core/app_commands.py"
click node_settings "https://github.com/aparsi0/athan_app/blob/main/config/settings.py"
click node_paths "https://github.com/aparsi0/athan_app/blob/main/utils/app_paths.py"
click node_location "https://github.com/aparsi0/athan_app/blob/main/core/location_service.py"
click node_prayer_times "https://github.com/aparsi0/athan_app/blob/main/core/prayer_times.py"
click node_scheduler "https://github.com/aparsi0/athan_app/blob/main/core/scheduler.py"
click node_audio_manager "https://github.com/aparsi0/athan_app/blob/main/core/audio_player.py"
click node_quran_player "https://github.com/aparsi0/athan_app/blob/main/core/quran_player.py"
click node_quran_library "https://github.com/aparsi0/athan_app/blob/main/core/quran_library.py"
click node_web_app "https://github.com/aparsi0/athan_app/blob/main/docs/js/app.js"
click node_web_location "https://github.com/aparsi0/athan_app/blob/main/docs/js/location.js"
click node_web_prayers "https://github.com/aparsi0/athan_app/blob/main/docs/js/prayer-times.js"
click node_web_scheduler "https://github.com/aparsi0/athan_app/blob/main/docs/js/scheduler.js"
click node_web_audio "https://github.com/aparsi0/athan_app/blob/main/docs/js/audio.js"
click node_web_quran "https://github.com/aparsi0/athan_app/blob/main/docs/js/reciters.js"
click node_web_scene "https://github.com/aparsi0/athan_app/blob/main/docs/js/scene.js"
click node_web_radio "https://github.com/aparsi0/athan_app/blob/main/docs/js/audio-players.js"
click node_web_service_worker "https://github.com/aparsi0/athan_app/blob/main/docs/sw.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop_entry,node_headless_entry,node_tray,node_dashboard,node_settings_ui,node_commands,node_settings,node_paths,node_user,node_browser toneBlue
class node_location,node_geo_api,node_prayer_times,node_aladhan,node_scheduler toneAmber
class node_audio_manager,node_vlc,node_quran_player,node_quran_library toneMint
class node_web_app,node_web_location,node_web_prayers,node_web_scheduler,node_web_audio,node_web_quran,node_web_scene,node_web_radio,node_web_service_worker toneRose
```

## Components

### Desktop Runtime

- [Desktop Controller](https://github.com/aparsi0/athan_app/blob/main/main.py): `main.py`
- [Headless Controller](https://github.com/aparsi0/athan_app/blob/main/main_headless.py): `main_headless.py`
- [System Tray](https://github.com/aparsi0/athan_app/blob/main/gui/system_tray.py): `gui/system_tray.py`
- [Dashboard UI](https://github.com/aparsi0/athan_app/blob/main/gui/main_window.py): `gui/main_window.py`
- [Settings UI](https://github.com/aparsi0/athan_app/blob/main/gui/settings_window.py): `gui/settings_window.py`
- [Dashboard Commands](https://github.com/aparsi0/athan_app/blob/main/core/app_commands.py): `core/app_commands.py`
- [Configuration](https://github.com/aparsi0/athan_app/blob/main/config/settings.py): `config/settings.py`
- [Runtime Paths](https://github.com/aparsi0/athan_app/blob/main/utils/app_paths.py): `utils/app_paths.py`

### Prayer Services

- [Location Detection](https://github.com/aparsi0/athan_app/blob/main/core/location_service.py): `core/location_service.py`
- **IP Geolocation**
- [Prayer Times](https://github.com/aparsi0/athan_app/blob/main/core/prayer_times.py): `core/prayer_times.py`
- **Aladhan API**
- [Event Scheduler](https://github.com/aparsi0/athan_app/blob/main/core/scheduler.py): `core/scheduler.py`

### Audio Features

- [Prayer Audio](https://github.com/aparsi0/athan_app/blob/main/core/audio_player.py): `core/audio_player.py`
- **VLC Playback**
- [Quran Player](https://github.com/aparsi0/athan_app/blob/main/core/quran_player.py): `core/quran_player.py`
- [Reciter Library](https://github.com/aparsi0/athan_app/blob/main/core/quran_library.py): `core/quran_library.py`

### Browser App

- [Web App](https://github.com/aparsi0/athan_app/blob/main/docs/js/app.js): `docs/js/app.js`
- [Web Location](https://github.com/aparsi0/athan_app/blob/main/docs/js/location.js): `docs/js/location.js`
- [Web Prayer Times](https://github.com/aparsi0/athan_app/blob/main/docs/js/prayer-times.js): `docs/js/prayer-times.js`
- [Web Scheduler](https://github.com/aparsi0/athan_app/blob/main/docs/js/scheduler.js): `docs/js/scheduler.js`
- [Web Audio](https://github.com/aparsi0/athan_app/blob/main/docs/js/audio.js): `docs/js/audio.js`
- [Quran Tab](https://github.com/aparsi0/athan_app/blob/main/docs/js/reciters.js): `docs/js/reciters.js`
- [Living Sky](https://github.com/aparsi0/athan_app/blob/main/docs/js/scene.js): `docs/js/scene.js`
- [Cairo Radio](https://github.com/aparsi0/athan_app/blob/main/docs/js/audio-players.js): `docs/js/audio-players.js`
- [PWA Worker](https://github.com/aparsi0/athan_app/blob/main/docs/sw.js): `docs/sw.js`

### Other components

- **User**
- **Browser User**

## Connections

- User → Desktop Controller: starts (evidence: `README.md`)
- Desktop Controller → Location Detection: detects location (evidence: `main.py`)
- Location Detection → IP Geolocation: queries providers (evidence: `core/location_service.py`)
- Desktop Controller → Configuration: loads preferences (evidence: `main.py`)
- Desktop Controller → Prayer Times: requests times (evidence: `main.py`)
- Prayer Times → Aladhan API: fetches times (evidence: `core/prayer_times.py`)
- Desktop Controller → Event Scheduler: configures schedule (evidence: `main.py`)
- Event Scheduler → Prayer Times: refreshes times (evidence: `core/scheduler.py`)
- Desktop Controller → Prayer Audio: sets up playback (evidence: `main.py`)
- Prayer Audio → VLC Playback: plays audio (evidence: `core/audio_player.py`)
- Desktop Controller → Quran Player: starts Quran (evidence: `main.py`)
- Quran Player → Reciter Library: reads reciters (evidence: `core/quran_player.py`)
- Desktop Controller → System Tray: starts tray (evidence: `main.py`)
- System Tray → Dashboard UI: launches window (evidence: `gui/system_tray.py`)
- System Tray → Desktop Controller: requests status (evidence: `main.py`)
- Dashboard UI → Quran Player: controls playback (evidence: `gui/main_window.py`)
- Dashboard UI → Settings UI: offers settings
- Dashboard UI → Dashboard Commands: writes commands (evidence: `core/app_commands.py`)
- Dashboard Commands → Desktop Controller: consumed by daemon (evidence: `core/app_commands.py`)
- Desktop Controller → Headless Controller: alternative runtime
- Configuration → Runtime Paths: uses config paths (evidence: `config/settings.py`)
- Browser User → Web App: opens app (evidence: `README.md`)
- Web App → Web Location: uses location
- Web App → Web Prayer Times: shows prayer times
- Web App → Web Scheduler: schedules audio
- Web App → Web Audio: plays reminders
- Web App → Quran Tab: offers Quran
- Web App → Living Sky: shows sky
- Web App → Cairo Radio: offers radio
- Web App → PWA Worker: installs as PWA