How zayeefzahid/islamic-prayer-app works
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: App.jsx App.jsx · ui UI Primitives · prayer-times.js prayer-times.js · prayer-api.js prayer-api.js
Components 18
App Shell
Browser entry, root composition, and global styling.
Feature UI
Primary screen components and state-driven panels.
- App Header · Branding and top-level navigation.
src/components/AppHeader.jsx - Next Prayer · Highlights the upcoming prayer and countdown.
src/components/NextPrayerHero.jsx - Prayer Schedule · Renders the full daily prayer timeline.
src/components/PrayerSchedule.jsx - Settings Panel · Prayer calculation and display preferences.
src/components/SettingsPanel.jsx - Daily Reflection · Quran reflection and optional audio content.
src/components/DailyReflection.jsx - Status States · Loading, error, and fallback screens.
src/components/StatusStates.jsx
Domain Logic
Shared calculation and utility layer for prayer timing and formatting.
- prayer-times.js · Prayer-time math and derived state helpers.
src/lib/prayer-times.js - utils.js · Shared formatting and data helpers.
src/lib/utils.js
Service Boundary
Network access and location resolution coordination.
- prayer-api.js · Prayer times and geocoding network access.
src/services/prayer-api.js
UI Primitives
Reusable component library used by feature components.
- UI Primitives · Reusable shadcn-style building blocks.
src/components/ui
Platform
Browser APIs and external services used by the app.
- Geolocation API · Provides device coordinates when permitted.
- BigDataCloud · Reverse geocoding to readable place names.
- Aladhan API · Prayer time data source.
- Fallback Location · Default location used when geolocation fails.
Connections 24
- 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.