# zayeefzahid/islamic-prayer-app architecture

> Architecture diagram of the GitHub repository zayeefzahid/islamic-prayer-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zayeefzahid/islamic-prayer-app
- Repository: https://github.com/zayeefzahid/islamic-prayer-app

## Overview

1. **Overall shape**
   - This is a **single-page React frontend** built with **Vite** and styled with **Tailwind CSS**.
   - There is **no custom backend** in the repo; all prayer-time data comes from external APIs and browser APIs.
   - The app is designed for **mobile-first daily use**, so the architecture is centered on one primary screen with a few supporting panels and states.

2. **Entry points and app shell**
   - `src/main.jsx` boots the React app.
   - `src/App.jsx` is the top-level composition layer that assembles the page from feature components.
   - `src/App.css` and `src/index.css` hold global and app-level styling.
   - `index.html` and `vite.config.js` define the browser entry and build/runtime configuration.

3. **Primary feature composition**
   - The UI is split into clear feature components under `src/components/`:
     - `NextPrayerHero.jsx` for the highlighted upcoming prayer and countdown
     - `PrayerSchedule.jsx` for the full daily prayer timeline
     - `SettingsPanel.jsx` for user preferences
     - `DailyReflection.jsx` for the Quran reflection card
     - `AppHeader.jsx` for top-level navigation/branding
     - `StatusStates.jsx` for loading, error, and fallback screens
   - This makes the architecture mostly **feature-oriented**, not page-router oriented.

4. **Core data flow**
   - The app first determines location, then fetches prayer times, then derives display state.
   - Typical flow:
     1. browser geolocation provides coordinates
     2. reverse geocoding resolves those coordinates to a readable place
     3. prayer times are fetched from the Aladhan API
     4. local helpers compute the next prayer, current context, and formatted times
     5. the feature components render the resulting schedule and countdown
   - The result is a **data-driven UI** with a single source of truth in the top-level app state.

5. **External service boundary**
   - `src/services/prayer-api.js` is the main network boundary.
   - It talks to the **Aladhan Prayer Times API** using the configured `VITE_PRAYER_API_URL`.
   - The README also indicates **BigDataCloud reverse geocoding** is used to convert coordinates into a readable city/country.
   - These services are isolated from presentation logic so the UI components stay mostly declarative.

6. **Location and fallback behavior**
   - The app relies on the **browser Geolocation API** for real device coordinates.
   - If permission is denied or unavailable, it falls back to **New York, United States**.
   - That fallback is an important architectural boundary because the app must remain usable even when location services fail.

7. **Prayer-time logic and derived state**
   - `src/lib/prayer-times.js` likely contains the time math and formatting logic used across the app.
   - `src/lib/utils.js` provides shared helpers for UI/data manipulation.
   - This keeps calendar/time calculations separate from network code and from the React component tree.
   - Important derived states include:
     - next prayer
     - completed/current/upcoming prayer status
     - countdown timer
     - 12-hour vs 24-hour formatting

8. **User preferences and settings**
   - `SettingsPanel.jsx` exposes user-adjustable prayer configuration:
     - calculation convention
     - Asr school
     - time format
     - theme mode
   - These settings influence how API requests and displayed times are produced, so they are part of the app’s core state rather than cosmetic-only options.

9. **UI state management and resilience**
   - `StatusStates.jsx` centralizes the non-happy-path UI: loading skeletons, error notices, and fallback messaging.
   - The README explicitly calls out resilient handling for:
     - loading
     - API failure
     - denied location access
     - fallback location usage
   - That means the app is architected around **progressive disclosure of data readiness**, not just a static render.

10. **Reflection content as a secondary feature**
   - `DailyReflection.jsx` is a lightweight content module separate from prayer-time computation.
   - It adds a Quran reflection and optional audio, but it is not part of the core scheduling pipeline.
   - Architecturally, it behaves like a supportive content block alongside the main prayer dashboard.

11. **UI library layer**
   - `src/components/ui/` contains a large set of reusable primitives, consistent with **shadcn-style component structure**.
   - These components provide the basic interaction and layout building blocks: buttons, dialogs, sheets, tabs, tooltips, forms, etc.
   - They are infrastructure for the app’s visual system, not domain logic.

12. **Mobile-first and static deployment model**
   - The app is intended for **static hosting** such as Vercel, Netlify, or Cloudflare Pages.
   - Because all logic is client-side, deployment is mainly about shipping the built static bundle plus the `VITE_PRAYER_API_URL` environment variable.
   - There is no server rendering, job worker, or database layer in this repository.

13. **What to show in an architecture diagram**
   - A good diagram would show:
     - Browser UI shell
     - React component layer
     - Shared helper/lib layer
     - Service layer for API calls
     - Browser Geolocation API
     - Aladhan Prayer Times API
     - BigDataCloud reverse geocoding
     - Fallback location path
   - The most important arrows are from **location/settings → service calls → derived prayer state → feature components → UI**.

14. **Boundary summary**
   - **Presentation boundary:** `src/components/*`
   - **Logic boundary:** `src/lib/*`
   - **Network boundary:** `src/services/*`
   - **Platform boundary:** browser geolocation and theme/local preference behavior
   - The app is therefore a compact, client-side, API-driven dashboard with strong separation between data acquisition, derived prayer logic, and UI rendering.

Main entry points: [`src/App.jsx`](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/App.jsx) (App.jsx), [`src/components/ui`](https://github.com/zayeefzahid/islamic-prayer-app/tree/main/src/components/ui) (UI Primitives), [`src/lib/prayer-times.js`](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/lib/prayer-times.js) (prayer-times.js), [`src/services/prayer-api.js`](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/services/prayer-api.js) (prayer-api.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_shell["App Shell"]
  node_node_main["main.jsx<br/>entry<br/>[main.jsx]"]
  node_node_app["App.jsx<br/>composition<br/>[App.jsx]"]
  node_node_appcss["App.css<br/>styles<br/>[App.css]"]
  node_node_globalcss["index.css<br/>styles<br/>[index.css]"]
end

subgraph group_grp_features["Feature UI"]
  node_node_header["App Header<br/>feature component<br/>[AppHeader.jsx]"]
  node_node_hero["Next Prayer<br/>feature component<br/>[NextPrayerHero.jsx]"]
  node_node_schedule["Prayer Schedule<br/>feature component<br/>[PrayerSchedule.jsx]"]
  node_node_settings["Settings Panel<br/>feature component<br/>[SettingsPanel.jsx]"]
  node_node_reflection["Daily Reflection<br/>content block"]
  node_node_status["Status States<br/>state ui<br/>[StatusStates.jsx]"]
end

subgraph group_grp_logic["Domain Logic"]
  node_node_times["prayer-times.js<br/>time logic<br/>[prayer-times.js]"]
  node_node_utils["utils.js<br/>helpers<br/>[utils.js]"]
end

subgraph group_grp_service["Service Boundary"]
  node_node_api["prayer-api.js<br/>api client<br/>[prayer-api.js]"]
end

subgraph group_grp_ui["UI Primitives"]
  node_node_ui["UI Primitives<br/>component library"]
end

subgraph group_grp_platform["Platform"]
  node_node_geo(("Geolocation API<br/>browser api"))
  node_node_bdc(("BigDataCloud<br/>external api"))
  node_node_aladhan(("Aladhan API<br/>external api"))
  node_node_fallback(("Fallback Location"))
end

node_node_main -->|"mounts"| node_node_app
node_node_app -->|"renders"| node_node_header
node_node_app -->|"renders"| node_node_hero
node_node_app -->|"renders"| node_node_schedule
node_node_app -->|"renders"| node_node_settings
node_node_app -->|"renders"| node_node_reflection
node_node_app -->|"handles"| node_node_status
node_node_app -->|"derives"| node_node_times
node_node_app -->|"requests"| node_node_api
node_node_app -->|"formats"| node_node_utils
node_node_header -->|"uses"| node_node_ui
node_node_hero -->|"uses"| node_node_ui
node_node_schedule -->|"uses"| node_node_ui
node_node_settings -->|"uses"| node_node_ui
node_node_reflection -->|"uses"| node_node_ui
node_node_status -->|"uses"| node_node_ui
node_node_api -->|"reads"| node_node_geo
node_node_api -->|"reverse geocodes"| node_node_bdc
node_node_api -->|"fetches"| node_node_aladhan
node_node_api -->|"falls back to"| node_node_fallback
node_node_times -->|"applies"| node_node_settings
node_node_times -->|"feeds"| node_node_hero
node_node_times -->|"feeds"| node_node_schedule
node_node_times -->|"supports"| node_node_status

click node_node_main "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/main.jsx"
click node_node_app "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/App.jsx"
click node_node_appcss "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/App.css"
click node_node_globalcss "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/index.css"
click node_node_header "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/AppHeader.jsx"
click node_node_hero "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/NextPrayerHero.jsx"
click node_node_schedule "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/PrayerSchedule.jsx"
click node_node_settings "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/SettingsPanel.jsx"
click node_node_reflection "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/DailyReflection.jsx"
click node_node_status "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/StatusStates.jsx"
click node_node_times "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/lib/prayer-times.js"
click node_node_utils "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/lib/utils.js"
click node_node_api "https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/services/prayer-api.js"
click node_node_ui "https://github.com/zayeefzahid/islamic-prayer-app/tree/main/src/components/ui"

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_node_main,node_node_app,node_node_appcss,node_node_globalcss toneBlue
class node_node_header,node_node_hero,node_node_schedule,node_node_settings,node_node_reflection,node_node_status toneAmber
class node_node_times,node_node_utils toneMint
class node_node_api toneRose
class node_node_ui toneIndigo
class node_node_geo,node_node_bdc,node_node_aladhan,node_node_fallback toneTeal
```

## Components

### App Shell

Browser entry, root composition, and global styling.

- [main.jsx](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/main.jsx): entry · Bootstraps the React app. · `src/main.jsx`
- [App.jsx](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/App.jsx): composition · Top-level composition and state wiring. · `src/App.jsx`
- [App.css](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/App.css): styles · App-level styling. · `src/App.css`
- [index.css](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/index.css): styles · Global styles and theme baseline. · `src/index.css`

### Feature UI

Primary screen components and state-driven panels.

- [App Header](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/AppHeader.jsx): feature component · Branding and top-level navigation. · `src/components/AppHeader.jsx`
- [Next Prayer](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/NextPrayerHero.jsx): feature component · Highlights the upcoming prayer and countdown. · `src/components/NextPrayerHero.jsx`
- [Prayer Schedule](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/PrayerSchedule.jsx): feature component · Renders the full daily prayer timeline. · `src/components/PrayerSchedule.jsx`
- [Settings Panel](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/SettingsPanel.jsx): feature component · Prayer calculation and display preferences. · `src/components/SettingsPanel.jsx`
- [Daily Reflection](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/DailyReflection.jsx): content block · Quran reflection and optional audio content. · `src/components/DailyReflection.jsx`
- [Status States](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/components/StatusStates.jsx): state ui · Loading, error, and fallback screens. · `src/components/StatusStates.jsx`

### Domain Logic

Shared calculation and utility layer for prayer timing and formatting.

- [prayer-times.js](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/lib/prayer-times.js): time logic · Prayer-time math and derived state helpers. · `src/lib/prayer-times.js`
- [utils.js](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/lib/utils.js): helpers · Shared formatting and data helpers. · `src/lib/utils.js`

### Service Boundary

Network access and location resolution coordination.

- [prayer-api.js](https://github.com/zayeefzahid/islamic-prayer-app/blob/main/src/services/prayer-api.js): api client · Prayer times and geocoding network access. · `src/services/prayer-api.js`

### UI Primitives

Reusable component library used by feature components.

- [UI Primitives](https://github.com/zayeefzahid/islamic-prayer-app/tree/main/src/components/ui): component library · Reusable shadcn-style building blocks. · `src/components/ui`

### Platform

Browser APIs and external services used by the app.

- **Geolocation API**: browser api · Provides device coordinates when permitted.
- **BigDataCloud**: external api · Reverse geocoding to readable place names.
- **Aladhan API**: external api · Prayer time data source.
- **Fallback Location**: fallback · Default location used when geolocation fails.

## Connections

- main.jsx → App.jsx: mounts · React entry mounts the app shell.
- App.jsx → App Header: renders · Top-level composition includes the app header.
- App.jsx → Next Prayer: renders · Primary dashboard hero is assembled here.
- App.jsx → Prayer Schedule: renders · Daily timetable is composed in the app shell.
- App.jsx → Settings Panel: renders · User preferences panel is part of the main screen.
- App.jsx → Daily Reflection: renders · Secondary content block is included alongside the dashboard.
- App.jsx → Status States: handles · Loading and error states are routed through the app shell.
- App.jsx → prayer-times.js: derives · App state uses prayer-time calculations and derived context.
- App.jsx → prayer-api.js: requests · App-level flow triggers service calls for location and prayer data.
- App.jsx → utils.js: formats · Shared helpers support display and state shaping.
- App Header → UI Primitives: uses · Header is built from shared UI primitives.
- Next Prayer → UI Primitives: uses · Hero uses reusable visual primitives.
- Prayer Schedule → UI Primitives: uses · Schedule rows and cards use shared primitives.
- Settings Panel → UI Primitives: uses · Form controls and toggles come from the UI library.
- Daily Reflection → UI Primitives: uses · Content block is assembled from shared components.
- Status States → UI Primitives: uses · Fallback notices and loading states use shared primitives.
- prayer-api.js → Geolocation API: reads · Coordinates are obtained from the browser when available.
- prayer-api.js → BigDataCloud: reverse geocodes · Coordinates are converted into a human-readable location.
- prayer-api.js → Aladhan API: fetches · Prayer times are retrieved from the external API.
- prayer-api.js → Fallback Location: falls back to · Default location is used when geolocation is denied or unavailable.
- prayer-times.js → Settings Panel: applies · Selected convention, Asr school, and time format influence derivations.
- prayer-times.js → Next Prayer: feeds · Next prayer and countdown are computed for the hero.
- prayer-times.js → Prayer Schedule: feeds · Formatted prayer timeline powers the schedule view.
- prayer-times.js → Status States: supports · Derived readiness and current status inform state screens.