# quran/quran.com-frontend-next architecture

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

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

## Overview

Quran.com is a Next.js frontend for reading and studying the Quran, with accounts, saved content, courses, audio, media creation, and an embeddable verse widget. A typical visit starts at a page, then uses its product feature to read or act on Quran content. The graph includes major capabilities visible in the tree, but most page-to-feature wiring is not excerpted; those relationships are omitted or marked unverified. The README identifies the product as the Quran.com frontend, not its backend services.

Main entry points: [`src/components/QuranReader`](https://github.com/quran/quran.com-frontend-next/tree/production/src/components/QuranReader) (Quran reader), [`src/pages/index.tsx`](https://github.com/quran/quran.com-frontend-next/blob/production/src/pages/index.tsx) (Homepage), [`src/utils/auth/api.ts`](https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/api.ts) (Account API), [`src/components/Course`](https://github.com/quran/quran.com-frontend-next/tree/production/src/components/Course) (Courses)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reading["Quran reading"]
  node_reader["Quran reader"]
  node_reading_state["Reading preferences"]
  node_navigation["Quran navigation<br/>[navigation.ts]"]
  node_chapters["Chapter data<br/>[chapter.ts]"]
  node_search["Search<br/>[search.ts]"]
end

subgraph group_learning["Study and learning"]
  node_courses["Courses"]
  node_enrollment["Course enrollment"]
end

subgraph group_personal["Account and saved content"]
  node_collections["Verse collections"]
  node_auth_api["Account API<br/>[api.ts]"]
  node_auth["Authentication<br/>[login.ts]"]
  node_notifications["Notifications<br/>[index.tsx]"]
  node_notes["Notes and reflections<br/>[NoteFormModal.tsx]"]
end

subgraph group_media["Audio and media"]
  node_audio["Audio player<br/>[AudioPlayer.tsx]"]
  node_radio["Radio playback"]
  node_media_maker["Media maker<br/>[Root.tsx]"]
end

subgraph group_platform["Platform features"]
  node_homepage["Homepage<br/>[index.tsx]"]
  node_widget["Verse widget"]
  node_widget_config["Widget configuration<br/>[widget-config.ts]"]
  node_apps["Apps portal<br/>[apps.tsx]"]
  node_api["Public API client<br/>[api.ts]"]
end

node_user(("Reader"))
node_external_services[("Backend services")]

node_user -->|"opens"| node_homepage
node_homepage -.->|"offers reading"| node_reader
node_homepage -.->|"offers learning"| node_courses
node_homepage -.->|"offers playback"| node_audio
node_reader -.->|"uses preferences"| node_reading_state
node_reader -.->|"navigates verses"| node_navigation
node_reader -.->|"uses chapter data"| node_chapters
node_reader -.->|"searches Quran"| node_search
node_user -.->|"saves verses"| node_collections
node_collections -->|"deletes bookmark"| node_auth_api
node_user -.->|"signs in"| node_auth
node_courses -.->|"enrolls user"| node_enrollment
node_enrollment -.->|"requests enrollment"| node_auth_api
node_user -.->|"plays recitation"| node_audio
node_user -.->|"plays radio"| node_radio
node_user -.->|"creates media"| node_media_maker
node_user -.->|"embeds verses"| node_widget
node_widget -->|"uses configuration"| node_widget_config
node_user -->|"browses apps"| node_apps
node_user -.->|"views alerts"| node_notifications
node_user -.->|"writes reflections"| node_notes
node_auth_api -.->|"fetches account data"| node_external_services
node_api -.->|"fetches Quran data"| node_external_services

click node_homepage "https://github.com/quran/quran.com-frontend-next/blob/production/src/pages/index.tsx"
click node_reader "https://github.com/quran/quran.com-frontend-next/tree/production/src/components/QuranReader"
click node_reading_state "https://github.com/quran/quran.com-frontend-next/blob/production/src/redux/slices/QuranReader/readingPreferences.ts"
click node_navigation "https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/navigation.ts"
click node_chapters "https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/chapter.ts"
click node_search "https://github.com/quran/quran.com-frontend-next/blob/production/src/redux/slices/Search/search.ts"
click node_collections "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/MyQuran/CollectionDetailView/hooks/useCollectionDetailViewController.ts"
click node_auth_api "https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/api.ts"
click node_auth "https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/login.ts"
click node_courses "https://github.com/quran/quran.com-frontend-next/tree/production/src/components/Course"
click node_enrollment "https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/useCourseEnrollment.ts"
click node_audio "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/AudioPlayer/AudioPlayer.tsx"
click node_radio "https://github.com/quran/quran.com-frontend-next/blob/production/src/xstate/Radio/useCurrentStationInfo.ts"
click node_media_maker "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/MediaMaker/Root.tsx"
click node_widget "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/AyahWidget/getAyahWidgetData.ts"
click node_widget_config "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/AyahWidget/widget-config.ts"
click node_apps "https://github.com/quran/quran.com-frontend-next/blob/production/src/pages/apps.tsx"
click node_api "https://github.com/quran/quran.com-frontend-next/blob/production/src/api.ts"
click node_notifications "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/Notifications/InAppNotifications/index.tsx"
click node_notes "https://github.com/quran/quran.com-frontend-next/blob/production/src/components/Notes/modal/NoteFormModal.tsx"

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_reading_state,node_navigation,node_chapters,node_search toneBlue
class node_courses,node_enrollment,node_external_services toneAmber
class node_collections,node_auth_api,node_auth,node_notifications,node_notes toneMint
class node_audio,node_radio,node_media_maker toneRose
class node_homepage,node_widget,node_widget_config,node_apps,node_api,node_user toneIndigo
```

## Components

### Quran reading

- [Quran reader](https://github.com/quran/quran.com-frontend-next/tree/production/src/components/QuranReader): `src/components/QuranReader`
- [Reading preferences](https://github.com/quran/quran.com-frontend-next/blob/production/src/redux/slices/QuranReader/readingPreferences.ts): `src/redux/slices/QuranReader/readingPreferences.ts`
- [Quran navigation](https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/navigation.ts): `src/utils/navigation.ts`
- [Chapter data](https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/chapter.ts): `src/utils/chapter.ts`
- [Search](https://github.com/quran/quran.com-frontend-next/blob/production/src/redux/slices/Search/search.ts): `src/redux/slices/Search/search.ts`

### Study and learning

- [Courses](https://github.com/quran/quran.com-frontend-next/tree/production/src/components/Course): `src/components/Course`
- [Course enrollment](https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/useCourseEnrollment.ts): `src/utils/auth/useCourseEnrollment.ts`

### Account and saved content

- [Verse collections](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/MyQuran/CollectionDetailView/hooks/useCollectionDetailViewController.ts): `src/components/MyQuran/CollectionDetailView/hooks/useCollectionDetailViewController.ts`
- [Account API](https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/api.ts): `src/utils/auth/api.ts`
- [Authentication](https://github.com/quran/quran.com-frontend-next/blob/production/src/utils/auth/login.ts): `src/utils/auth/login.ts`
- [Notifications](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/Notifications/InAppNotifications/index.tsx): `src/components/Notifications/InAppNotifications/index.tsx`
- [Notes and reflections](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/Notes/modal/NoteFormModal.tsx): `src/components/Notes/modal/NoteFormModal.tsx`

### Audio and media

- [Audio player](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/AudioPlayer/AudioPlayer.tsx): `src/components/AudioPlayer/AudioPlayer.tsx`
- [Radio playback](https://github.com/quran/quran.com-frontend-next/blob/production/src/xstate/Radio/useCurrentStationInfo.ts): `src/xstate/Radio/useCurrentStationInfo.ts`
- [Media maker](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/MediaMaker/Root.tsx): `src/components/MediaMaker/Root.tsx`

### Platform features

- [Homepage](https://github.com/quran/quran.com-frontend-next/blob/production/src/pages/index.tsx): `src/pages/index.tsx`
- [Verse widget](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/AyahWidget/getAyahWidgetData.ts): `src/components/AyahWidget/getAyahWidgetData.ts`
- [Widget configuration](https://github.com/quran/quran.com-frontend-next/blob/production/src/components/AyahWidget/widget-config.ts): `src/components/AyahWidget/widget-config.ts`
- [Apps portal](https://github.com/quran/quran.com-frontend-next/blob/production/src/pages/apps.tsx): `src/pages/apps.tsx`
- [Public API client](https://github.com/quran/quran.com-frontend-next/blob/production/src/api.ts): `src/api.ts`

### Other components

- **Reader**
- **Backend services**

## Connections

- Reader → Homepage: opens (evidence: `README.md`)
- Homepage → Quran reader: offers reading
- Homepage → Courses: offers learning
- Homepage → Audio player: offers playback
- Quran reader → Reading preferences: uses preferences (evidence: `src/components/QuranReader/ContextMenu/hooks/useContextMenuState.ts`)
- Quran reader → Quran navigation: navigates verses (evidence: `src/components/QuranReader/ReadingView/StudyModeModal/PinnedVersesSection/usePinnedVerseHandlers.ts`)
- Quran reader → Chapter data: uses chapter data (evidence: `src/components/QuranReader/ContextMenu/hooks/useContextMenuState.ts`)
- Quran reader → Search: searches Quran
- Reader → Verse collections: saves verses
- Verse collections → Account API: deletes bookmark (evidence: `src/components/MyQuran/CollectionDetailView/hooks/useCollectionDetailViewController.ts`)
- Reader → Authentication: signs in
- Courses → Course enrollment: enrolls user
- Course enrollment → Account API: requests enrollment (evidence: `src/utils/auth/useCourseEnrollment.ts`)
- Reader → Audio player: plays recitation
- Reader → Radio playback: plays radio
- Reader → Media maker: creates media
- Reader → Verse widget: embeds verses
- Verse widget → Widget configuration: uses configuration (evidence: `src/components/AyahWidget/getAyahWidgetData.ts`)
- Reader → Apps portal: browses apps (evidence: `src/pages/apps.tsx`)
- Reader → Notifications: views alerts
- Reader → Notes and reflections: writes reflections
- Account API → Backend services: fetches account data
- Public API client → Backend services: fetches Quran data
