# diyanet-bid/kuran architecture

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

- Interactive diagram: https://gitdiagram.com/diyanet-bid/kuran
- Repository: https://github.com/diyanet-bid/kuran

## Overview

This is a frontend Qur’an reading application. The principal workflow is browsing surahs or opening a page/surah, loading content through the API client and rendering verses; readers and bookmark management also use client-side Quran state. The README additionally describes audio, search, multiple translations/tafsir, personalization, and accessibility, but the supplied tree and excerpts do not establish implementations for several of these. Those capabilities are shown as documented but unverified. Evidence for unsampled route behavior is limited to the README and API client endpoint names.

Main entry points: [`components/quran/quran-reader.tsx`](https://github.com/diyanet-bid/kuran/blob/main/components/quran/quran-reader.tsx) (Page reader), [`services/quran-api.ts`](https://github.com/diyanet-bid/kuran/blob/main/services/quran-api.ts) (Quran data service), [`components/quran/surah-list.tsx`](https://github.com/diyanet-bid/kuran/blob/main/components/quran/surah-list.tsx) (Surah browser), [`services/api-client.ts`](https://github.com/diyanet-bid/kuran/blob/main/services/api-client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Reading experience"]
  node_reader["Page reader<br/>[quran-reader.tsx]"]
  node_surahreader["Surah reader<br/>[surah-reader.tsx]"]
  node_surahlist["Surah browser<br/>[surah-list.tsx]"]
  node_navigation["Reader navigation"]
  node_verse["Verse display"]
  node_pageentry["Page route<br/>[page.tsx]"]
  node_surahentry["Surah route<br/>[page.tsx]"]
  node_listentry["Surah list route<br/>[page.tsx]"]
  node_featureclaims["Documented Quran capabilities"]
end

subgraph group_content["Quran content"]
  node_api["Quran data service<br/>[quran-api.ts]"]
  node_client["API client<br/>[api-client.ts]"]
  node_routes["Quran API routes"]
end

subgraph group_state["User state"]
  node_bookmarks["Bookmarks and notes<br/>[page.tsx]"]
  node_store["Quran state<br/>[quran-store.ts]"]
end

subgraph group_platform["Application shell"]
  node_language["Language provider"]
  node_header["Site navigation<br/>[header.tsx]"]
  node_landing["Landing page<br/>[page.tsx]"]
end

node_diyanet{{"Diyanet Quran API"}}

node_pageentry -->|"renders"| node_reader
node_surahentry -->|"renders"| node_surahreader
node_listentry -->|"renders"| node_surahlist
node_reader -->|"loads content"| node_api
node_reader -->|"uses state"| node_store
node_reader -->|"renders verses"| node_verse
node_surahlist -->|"loads surahs"| node_api
node_bookmarks -->|"reads and updates"| node_store
node_api -->|"requests data"| node_client
node_client -->|"fetches endpoints"| node_routes
node_routes -.->|"gets Quran data"| node_diyanet
node_featureclaims -.->|"documents audio and texts"| node_diyanet
node_landing -->|"renders"| node_header

click node_reader "https://github.com/diyanet-bid/kuran/blob/main/components/quran/quran-reader.tsx"
click node_surahreader "https://github.com/diyanet-bid/kuran/blob/main/components/quran/surah-reader.tsx"
click node_surahlist "https://github.com/diyanet-bid/kuran/blob/main/components/quran/surah-list.tsx"
click node_navigation "https://github.com/diyanet-bid/kuran/blob/main/components/quran/quran-navigation.tsx"
click node_verse "https://github.com/diyanet-bid/kuran/blob/main/components/quran/verse-component.tsx"
click node_bookmarks "https://github.com/diyanet-bid/kuran/blob/main/app/quran/bookmarks/page.tsx"
click node_store "https://github.com/diyanet-bid/kuran/blob/main/stores/quran-store.ts"
click node_api "https://github.com/diyanet-bid/kuran/blob/main/services/quran-api.ts"
click node_client "https://github.com/diyanet-bid/kuran/blob/main/services/api-client.ts"
click node_routes "https://github.com/diyanet-bid/kuran/tree/main/app/api/quran"
click node_pageentry "https://github.com/diyanet-bid/kuran/blob/main/app/quran/page/%5Bnumber%5D/page.tsx"
click node_surahentry "https://github.com/diyanet-bid/kuran/blob/main/app/quran/surah/%5Bid%5D/page.tsx"
click node_listentry "https://github.com/diyanet-bid/kuran/blob/main/app/quran/surahs/page.tsx"
click node_language "https://github.com/diyanet-bid/kuran/blob/main/components/language-provider.tsx"
click node_header "https://github.com/diyanet-bid/kuran/blob/main/components/layout/header.tsx"
click node_landing "https://github.com/diyanet-bid/kuran/blob/main/app/page.tsx"
click node_featureclaims "https://github.com/diyanet-bid/kuran/tree/main/components/quran"

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_reader,node_surahreader,node_surahlist,node_navigation,node_verse,node_pageentry,node_surahentry,node_listentry,node_featureclaims toneBlue
class node_api,node_client,node_routes toneAmber
class node_bookmarks,node_store,node_diyanet toneMint
class node_language,node_header,node_landing toneRose
```

## Components

### Reading experience

- [Page reader](https://github.com/diyanet-bid/kuran/blob/main/components/quran/quran-reader.tsx): `components/quran/quran-reader.tsx`
- [Surah reader](https://github.com/diyanet-bid/kuran/blob/main/components/quran/surah-reader.tsx): `components/quran/surah-reader.tsx`
- [Surah browser](https://github.com/diyanet-bid/kuran/blob/main/components/quran/surah-list.tsx): `components/quran/surah-list.tsx`
- [Reader navigation](https://github.com/diyanet-bid/kuran/blob/main/components/quran/quran-navigation.tsx): `components/quran/quran-navigation.tsx`
- [Verse display](https://github.com/diyanet-bid/kuran/blob/main/components/quran/verse-component.tsx): `components/quran/verse-component.tsx`
- [Page route](https://github.com/diyanet-bid/kuran/blob/main/app/quran/page/%5Bnumber%5D/page.tsx): `app/quran/page/[number]/page.tsx`
- [Surah route](https://github.com/diyanet-bid/kuran/blob/main/app/quran/surah/%5Bid%5D/page.tsx): `app/quran/surah/[id]/page.tsx`
- [Surah list route](https://github.com/diyanet-bid/kuran/blob/main/app/quran/surahs/page.tsx): `app/quran/surahs/page.tsx`
- [Documented Quran capabilities](https://github.com/diyanet-bid/kuran/tree/main/components/quran): `components/quran`

### Quran content

- [Quran data service](https://github.com/diyanet-bid/kuran/blob/main/services/quran-api.ts): `services/quran-api.ts`
- [API client](https://github.com/diyanet-bid/kuran/blob/main/services/api-client.ts): `services/api-client.ts`
- [Quran API routes](https://github.com/diyanet-bid/kuran/tree/main/app/api/quran): `app/api/quran`

### User state

- [Bookmarks and notes](https://github.com/diyanet-bid/kuran/blob/main/app/quran/bookmarks/page.tsx): `app/quran/bookmarks/page.tsx`
- [Quran state](https://github.com/diyanet-bid/kuran/blob/main/stores/quran-store.ts): `stores/quran-store.ts`

### Application shell

- [Language provider](https://github.com/diyanet-bid/kuran/blob/main/components/language-provider.tsx): `components/language-provider.tsx`
- [Site navigation](https://github.com/diyanet-bid/kuran/blob/main/components/layout/header.tsx): `components/layout/header.tsx`
- [Landing page](https://github.com/diyanet-bid/kuran/blob/main/app/page.tsx): `app/page.tsx`

### Other components

- **Diyanet Quran API**

## Connections

- Page route → Page reader: renders (evidence: `app/quran/page/[number]/page.tsx`)
- Surah route → Surah reader: renders (evidence: `app/quran/surah/[id]/page.tsx`)
- Surah list route → Surah browser: renders (evidence: `app/quran/surahs/page.tsx`)
- Page reader → Quran data service: loads content (evidence: `components/quran/quran-reader.tsx`)
- Page reader → Quran state: uses state (evidence: `components/quran/quran-reader.tsx`)
- Page reader → Verse display: renders verses (evidence: `components/quran/quran-reader.tsx`)
- Surah browser → Quran data service: loads surahs (evidence: `components/quran/surah-list.tsx`)
- Bookmarks and notes → Quran state: reads and updates (evidence: `app/quran/bookmarks/page.tsx`)
- Quran data service → API client: requests data (evidence: `services/quran-api.ts`)
- API client → Quran API routes: fetches endpoints (evidence: `services/api-client.ts`)
- Quran API routes → Diyanet Quran API: gets Quran data (evidence: `README.md`)
- Documented Quran capabilities → Diyanet Quran API: documents audio and texts (evidence: `README.md`)
- Landing page → Site navigation: renders (evidence: `app/page.tsx`)
