# hamzaelmanzari/quran architecture

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

- Interactive diagram: https://gitdiagram.com/hamzaelmanzari/quran
- Repository: https://github.com/hamzaelmanzari/quran

## Overview

Quran Sound is a responsive Quran browsing and recitation app. The main workflow loads validated surah metadata from Itqan, shares it across the app, and presents an index, search, and surah details; audio playback uses the returned audio URLs. Routing and providers form the application shell, while search and theme are separate capabilities. README documents multi-riwayat selection and accessibility; some feature wiring is not shown in the excerpts, so uncertain links are omitted or marked optional.

Main entry points: [`src/app/AppRouter.jsx`](https://github.com/hamzaelmanzari/quran/blob/main/src/app/AppRouter.jsx) (App router), [`main.jsx`](https://github.com/hamzaelmanzari/quran/blob/main/main.jsx) (React entry), [`src/app/App.jsx`](https://github.com/hamzaelmanzari/quran/blob/main/src/app/App.jsx) (Page shell), [`src/features/quran/QuranDataProvider.jsx`](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/QuranDataProvider.jsx) (Quran provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application shell"]
  node_entry["React entry<br/>[main.jsx]"]
  node_router["App router<br/>[AppRouter.jsx]"]
  node_shell["Page shell<br/>[App.jsx]"]
  node_errors["Error boundary<br/>[ErrorBoundary.jsx]"]
  node_query["Query client<br/>[queryClient.js]"]
  node_header["Site header<br/>[Header.jsx]"]
  node_footer["Site footer<br/>[Footer.jsx]"]
end

subgraph group_quran["Quran data and pages"]
  node_data_provider["Quran provider"]
  node_data_context["Quran context"]
  node_queries["Quran queries<br/>[quranQueries.js]"]
  node_itqan["Itqan API client<br/>[itqanApi.js]"]
  node_index_page["Surah index<br/>[IndexPage.jsx]"]
  node_surah_page["Surah detail<br/>[SurahPage.jsx]"]
  node_surah_loader["Detail loader<br/>[surahPageLoader.js]"]
  node_surah_hook["Surah navigation<br/>[useSurah.js]"]
  node_quran_utils["Surah utilities<br/>[quranData.js]"]
end

subgraph group_search["Search"]
  node_search_provider["Search provider<br/>[SearchProvider.jsx]"]
  node_search_context["Search context<br/>[searchContext.js]"]
  node_search_page["Search page<br/>[SearchPage.jsx]"]
  node_search_hook["Search hook<br/>[useSearch.js]"]
end

subgraph group_experience["Playback and appearance"]
  node_audio["Audio playback<br/>[useAudio.js]"]
  node_theme["Dark mode<br/>[useDarkMode.js]"]
end

node_visitor(("Listener"))
node_cms[("Itqan CMS")]

node_visitor -->|"opens"| node_entry
node_entry -->|"wraps"| node_errors
node_entry -->|"renders"| node_router
node_router -->|"provides"| node_query
node_router -->|"provides"| node_data_provider
node_router -->|"provides"| node_search_provider
node_router -->|"renders"| node_shell
node_shell -->|"renders"| node_header
node_shell -->|"renders"| node_footer
node_router -->|"routes to"| node_index_page
node_router -->|"routes to"| node_search_page
node_router -->|"routes to"| node_surah_page
node_router -->|"lazy loads"| node_surah_loader
node_data_provider -->|"loads through"| node_queries
node_data_provider -->|"publishes"| node_data_context
node_queries -->|"calls"| node_itqan
node_itqan -->|"fetches metadata"| node_cms
node_search_provider -->|"uses"| node_search_context
node_search_hook -->|"filters with"| node_quran_utils
node_search_hook -->|"reads via hook"| node_data_context
node_surah_hook -->|"resolves with"| node_quran_utils
node_surah_hook -->|"reads via hook"| node_data_context
node_surah_page -.->|"may play audio"| node_audio
node_visitor -.->|"chooses theme"| node_theme

click node_entry "https://github.com/hamzaelmanzari/quran/blob/main/main.jsx"
click node_router "https://github.com/hamzaelmanzari/quran/blob/main/src/app/AppRouter.jsx"
click node_shell "https://github.com/hamzaelmanzari/quran/blob/main/src/app/App.jsx"
click node_errors "https://github.com/hamzaelmanzari/quran/blob/main/src/app/ErrorBoundary.jsx"
click node_query "https://github.com/hamzaelmanzari/quran/blob/main/src/app/queryClient.js"
click node_header "https://github.com/hamzaelmanzari/quran/blob/main/src/shared/components/Header.jsx"
click node_footer "https://github.com/hamzaelmanzari/quran/blob/main/src/shared/components/Footer.jsx"
click node_data_provider "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/QuranDataProvider.jsx"
click node_data_context "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/quranDataContext.js"
click node_queries "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/api/quranQueries.js"
click node_itqan "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/api/itqanApi.js"
click node_index_page "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/pages/IndexPage.jsx"
click node_surah_page "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/pages/SurahPage.jsx"
click node_surah_loader "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/pages/surahPageLoader.js"
click node_surah_hook "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/hooks/useSurah.js"
click node_quran_utils "https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/utils/quranData.js"
click node_search_provider "https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/SearchProvider.jsx"
click node_search_context "https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/searchContext.js"
click node_search_page "https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/SearchPage.jsx"
click node_search_hook "https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/useSearch.js"
click node_audio "https://github.com/hamzaelmanzari/quran/blob/main/src/features/audio/useAudio.js"
click node_theme "https://github.com/hamzaelmanzari/quran/blob/main/src/features/theme/useDarkMode.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_entry,node_router,node_shell,node_errors,node_query,node_header,node_footer toneBlue
class node_data_provider,node_data_context,node_queries,node_itqan,node_index_page,node_surah_page,node_surah_loader,node_surah_hook,node_quran_utils,node_cms toneAmber
class node_search_provider,node_search_context,node_search_page,node_search_hook toneMint
class node_audio,node_theme toneRose
class node_visitor toneIndigo
```

## Components

### Application shell

- [React entry](https://github.com/hamzaelmanzari/quran/blob/main/main.jsx): `main.jsx`
- [App router](https://github.com/hamzaelmanzari/quran/blob/main/src/app/AppRouter.jsx): `src/app/AppRouter.jsx`
- [Page shell](https://github.com/hamzaelmanzari/quran/blob/main/src/app/App.jsx): `src/app/App.jsx`
- [Error boundary](https://github.com/hamzaelmanzari/quran/blob/main/src/app/ErrorBoundary.jsx): `src/app/ErrorBoundary.jsx`
- [Query client](https://github.com/hamzaelmanzari/quran/blob/main/src/app/queryClient.js): `src/app/queryClient.js`
- [Site header](https://github.com/hamzaelmanzari/quran/blob/main/src/shared/components/Header.jsx): `src/shared/components/Header.jsx`
- [Site footer](https://github.com/hamzaelmanzari/quran/blob/main/src/shared/components/Footer.jsx): `src/shared/components/Footer.jsx`

### Quran data and pages

- [Quran provider](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/QuranDataProvider.jsx): `src/features/quran/QuranDataProvider.jsx`
- [Quran context](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/quranDataContext.js): `src/features/quran/quranDataContext.js`
- [Quran queries](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/api/quranQueries.js): `src/features/quran/api/quranQueries.js`
- [Itqan API client](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/api/itqanApi.js): `src/features/quran/api/itqanApi.js`
- [Surah index](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/pages/IndexPage.jsx): `src/features/quran/pages/IndexPage.jsx`
- [Surah detail](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/pages/SurahPage.jsx): `src/features/quran/pages/SurahPage.jsx`
- [Detail loader](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/pages/surahPageLoader.js): `src/features/quran/pages/surahPageLoader.js`
- [Surah navigation](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/hooks/useSurah.js): `src/features/quran/hooks/useSurah.js`
- [Surah utilities](https://github.com/hamzaelmanzari/quran/blob/main/src/features/quran/utils/quranData.js): `src/features/quran/utils/quranData.js`

### Search

- [Search provider](https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/SearchProvider.jsx): `src/features/search/SearchProvider.jsx`
- [Search context](https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/searchContext.js): `src/features/search/searchContext.js`
- [Search page](https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/SearchPage.jsx): `src/features/search/SearchPage.jsx`
- [Search hook](https://github.com/hamzaelmanzari/quran/blob/main/src/features/search/useSearch.js): `src/features/search/useSearch.js`

### Playback and appearance

- [Audio playback](https://github.com/hamzaelmanzari/quran/blob/main/src/features/audio/useAudio.js): `src/features/audio/useAudio.js`
- [Dark mode](https://github.com/hamzaelmanzari/quran/blob/main/src/features/theme/useDarkMode.js): `src/features/theme/useDarkMode.js`

### Other components

- **Listener**
- **Itqan CMS**

## Connections

- Listener → React entry: opens (evidence: `main.jsx`)
- React entry → Error boundary: wraps (evidence: `main.jsx`)
- React entry → App router: renders (evidence: `main.jsx`)
- App router → Query client: provides (evidence: `src/app/AppRouter.jsx`)
- App router → Quran provider: provides (evidence: `src/app/AppRouter.jsx`)
- App router → Search provider: provides (evidence: `src/app/AppRouter.jsx`)
- App router → Page shell: renders (evidence: `src/app/AppRouter.jsx`)
- Page shell → Site header: renders (evidence: `src/app/App.jsx`)
- Page shell → Site footer: renders (evidence: `src/app/App.jsx`)
- App router → Surah index: routes to (evidence: `src/app/AppRouter.jsx`)
- App router → Search page: routes to (evidence: `src/app/AppRouter.jsx`)
- App router → Surah detail: routes to (evidence: `src/app/AppRouter.jsx`)
- App router → Detail loader: lazy loads (evidence: `src/app/AppRouter.jsx`)
- Quran provider → Quran queries: loads through (evidence: `src/features/quran/QuranDataProvider.jsx`)
- Quran provider → Quran context: publishes (evidence: `src/features/quran/QuranDataProvider.jsx`)
- Quran queries → Itqan API client: calls (evidence: `src/features/quran/api/quranQueries.js`)
- Itqan API client → Itqan CMS: fetches metadata (evidence: `src/features/quran/api/itqanApi.js`)
- Search provider → Search context: uses (evidence: `src/features/search/SearchProvider.jsx`)
- Search hook → Surah utilities: filters with (evidence: `src/features/search/useSearch.js`)
- Search hook → Quran context: reads via hook (evidence: `src/features/search/useSearch.js`)
- Surah navigation → Surah utilities: resolves with (evidence: `src/features/quran/hooks/useSurah.js`)
- Surah navigation → Quran context: reads via hook (evidence: `src/features/quran/hooks/useSurah.js`)
- Surah detail → Audio playback: may play audio
- Listener → Dark mode: chooses theme