# ibrahimsarran/al-arbin40 architecture

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

- Interactive diagram: https://gitdiagram.com/ibrahimsarran/al-arbin40
- Repository: https://github.com/ibrahimsarran/al-arbin40

## Overview

Al-Arba'in is a browser-based reader and study app for the 42 Nawawi hadith, with playback, offline access, personal records, and a source-grounded question assistant. Readers enter through the web app, browse and study a hadith, and can ask the assistant about its meaning or context; the assistant returns a validated answer with references. The graph includes the documented reading, study, audio, records, language, and offline capabilities. Some client wiring and data loading are unsampled, so unsupported links are omitted.

Main entry points: [`public/js/controllers/reader-controller.mjs`](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/reader-controller.mjs) (Reader), [`server/research-service.mjs`](https://github.com/ibrahimsarran/al-arbin40/blob/main/server/research-service.mjs) (Research Service), [`public/js/controllers/audio-controller.mjs`](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/audio-controller.mjs) (Audio Controller), [`app/api/research/route.ts`](https://github.com/ibrahimsarran/al-arbin40/blob/main/app/api/research/route.ts) (Research Route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reader["Reading and Study"]
  node_reader["Reader"]
  node_reader_view["Reader View<br/>[reader-view.mjs]"]
  node_hadith_service["Hadith Search<br/>[hadith-service.mjs]"]
  node_study_service["Study Service<br/>[study-service.mjs]"]
  node_domain["Text Domain<br/>[domain.mjs]"]
  node_language["Language UI"]
  node_app_entry["Browser Entry<br/>[app.mjs]"]
end

subgraph group_audio["Audio and Offline"]
  node_audio_controller["Audio Controller"]
  node_audio_player["Audio Player<br/>[audio-player.mjs]"]
  node_download_service["Verified Downloads"]
  node_audio_repo[("Audio Storage")]
  node_service_worker["Offline Cache<br/>[service-worker.js]"]
end

subgraph group_records["Personal Records"]
  node_study_repo[("Study Storage")]
end

subgraph group_assistant["Research Assistant"]
  node_research_controller["Assistant Panel"]
  node_research_route["Research Route<br/>[route.ts]"]
  node_research_service["Research Service"]
  node_evidence_repo["Evidence Retrieval"]
  node_meaning_search["Meaning Search<br/>[meaning-search.mjs]"]
  node_validator["Answer Validation"]
  node_ai_client["AI Client<br/>[ai-client.mjs]"]
end

subgraph group_content["Bundled Content"]
  node_content_data["Hadith and Study Data<br/>[hadiths.json]"]
  node_audio_catalog["Recording Catalog<br/>[audio-catalog.json]"]
end

node_browser(("Reader"))
node_ai_service["Gemini"]

node_browser -->|"opens"| node_app_entry
node_app_entry -->|"starts"| node_reader
node_reader -->|"renders"| node_reader_view
node_reader -->|"searches with"| node_hadith_service
node_reader -->|"records study via"| node_study_service
node_reader -->|"delegates audio"| node_audio_controller
node_reader -->|"creates assistant"| node_research_controller
node_reader -->|"uses storage"| node_study_repo
node_hadith_service -->|"uses text logic"| node_domain
node_study_service -->|"uses validation"| node_domain
node_reader -->|"supports language UI"| node_language
node_audio_controller -->|"controls playback"| node_audio_player
node_audio_controller -->|"downloads recordings"| node_download_service
node_download_service -->|"saves verified files"| node_audio_repo
node_audio_controller -->|"selects recordings"| node_audio_catalog
node_browser -->|"caches app offline"| node_service_worker
node_research_controller -->|"posts question"| node_research_route
node_research_route -->|"handles request"| node_research_service
node_research_route -->|"provides corpus"| node_evidence_repo
node_research_route -->|"configures client"| node_ai_client
node_research_service -->|"retrieves evidence"| node_evidence_repo
node_research_service -->|"matches meanings"| node_meaning_search
node_research_service -->|"generates answer"| node_ai_client
node_research_service -->|"validates answer"| node_validator
node_evidence_repo -->|"finds matches"| node_meaning_search
node_evidence_repo -->|"retrieves passages"| node_content_data
node_ai_client -->|"requests generation"| node_ai_service

click node_reader "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/reader-controller.mjs"
click node_reader_view "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/views/reader-view.mjs"
click node_hadith_service "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/services/hadith-service.mjs"
click node_study_service "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/services/study-service.mjs"
click node_domain "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/utils/domain.mjs"
click node_language "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/language-controller.mjs"
click node_app_entry "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/app.mjs"
click node_audio_controller "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/audio-controller.mjs"
click node_audio_player "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/audio/audio-player.mjs"
click node_download_service "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/services/audio-download-service.mjs"
click node_audio_repo "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/repositories/audio-repository.mjs"
click node_service_worker "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/service-worker.js"
click node_study_repo "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/repositories/study-repository.mjs"
click node_research_controller "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/research-controller.mjs"
click node_research_route "https://github.com/ibrahimsarran/al-arbin40/blob/main/app/api/research/route.ts"
click node_research_service "https://github.com/ibrahimsarran/al-arbin40/blob/main/server/research-service.mjs"
click node_evidence_repo "https://github.com/ibrahimsarran/al-arbin40/blob/main/server/evidence-repository.mjs"
click node_meaning_search "https://github.com/ibrahimsarran/al-arbin40/blob/main/server/meaning-search.mjs"
click node_validator "https://github.com/ibrahimsarran/al-arbin40/blob/main/server/answer-validator.mjs"
click node_ai_client "https://github.com/ibrahimsarran/al-arbin40/blob/main/server/ai-client.mjs"
click node_content_data "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/hadiths.json"
click node_audio_catalog "https://github.com/ibrahimsarran/al-arbin40/blob/main/public/audio-catalog.json"

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_reader_view,node_hadith_service,node_study_service,node_domain,node_language,node_app_entry toneBlue
class node_audio_controller,node_audio_player,node_download_service,node_audio_repo,node_service_worker toneAmber
class node_study_repo toneMint
class node_research_controller,node_research_route,node_research_service,node_evidence_repo,node_meaning_search,node_validator,node_ai_client toneRose
class node_content_data,node_audio_catalog,node_browser,node_ai_service toneIndigo
```

## Components

### Reading and Study

- [Reader](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/reader-controller.mjs): `public/js/controllers/reader-controller.mjs`
- [Reader View](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/views/reader-view.mjs): `public/js/views/reader-view.mjs`
- [Hadith Search](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/services/hadith-service.mjs): `public/js/services/hadith-service.mjs`
- [Study Service](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/services/study-service.mjs): `public/js/services/study-service.mjs`
- [Text Domain](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/utils/domain.mjs): `public/js/utils/domain.mjs`
- [Language UI](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/language-controller.mjs): `public/js/controllers/language-controller.mjs`
- [Browser Entry](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/app.mjs): `public/app.mjs`

### Audio and Offline

- [Audio Controller](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/audio-controller.mjs): `public/js/controllers/audio-controller.mjs`
- [Audio Player](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/audio/audio-player.mjs): `public/js/audio/audio-player.mjs`
- [Verified Downloads](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/services/audio-download-service.mjs): `public/js/services/audio-download-service.mjs`
- [Audio Storage](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/repositories/audio-repository.mjs): `public/js/repositories/audio-repository.mjs`
- [Offline Cache](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/service-worker.js): `public/service-worker.js`

### Personal Records

- [Study Storage](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/repositories/study-repository.mjs): `public/js/repositories/study-repository.mjs`

### Research Assistant

- [Assistant Panel](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/js/controllers/research-controller.mjs): `public/js/controllers/research-controller.mjs`
- [Research Route](https://github.com/ibrahimsarran/al-arbin40/blob/main/app/api/research/route.ts): `app/api/research/route.ts`
- [Research Service](https://github.com/ibrahimsarran/al-arbin40/blob/main/server/research-service.mjs): `server/research-service.mjs`
- [Evidence Retrieval](https://github.com/ibrahimsarran/al-arbin40/blob/main/server/evidence-repository.mjs): `server/evidence-repository.mjs`
- [Meaning Search](https://github.com/ibrahimsarran/al-arbin40/blob/main/server/meaning-search.mjs): `server/meaning-search.mjs`
- [Answer Validation](https://github.com/ibrahimsarran/al-arbin40/blob/main/server/answer-validator.mjs): `server/answer-validator.mjs`
- [AI Client](https://github.com/ibrahimsarran/al-arbin40/blob/main/server/ai-client.mjs): `server/ai-client.mjs`

### Bundled Content

- [Hadith and Study Data](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/hadiths.json): `public/hadiths.json`
- [Recording Catalog](https://github.com/ibrahimsarran/al-arbin40/blob/main/public/audio-catalog.json): `public/audio-catalog.json`

### Other components

- **Reader**
- **Gemini**

## Connections

- Reader → Browser Entry: opens (evidence: `README.md`)
- Browser Entry → Reader: starts (evidence: `public/app.mjs`)
- Reader → Reader View: renders (evidence: `public/js/controllers/reader-controller.mjs`)
- Reader → Hadith Search: searches with (evidence: `public/js/controllers/reader-controller.mjs`)
- Reader → Study Service: records study via (evidence: `public/js/controllers/reader-controller.mjs`)
- Reader → Audio Controller: delegates audio (evidence: `public/js/controllers/reader-controller.mjs`)
- Reader → Assistant Panel: creates assistant (evidence: `public/js/controllers/reader-controller.mjs`)
- Reader → Study Storage: uses storage (evidence: `public/js/controllers/reader-controller.mjs`)
- Hadith Search → Text Domain: uses text logic (evidence: `public/js/services/hadith-service.mjs`)
- Study Service → Text Domain: uses validation (evidence: `public/js/services/study-service.mjs`)
- Reader → Language UI: supports language UI (evidence: `README.md`)
- Audio Controller → Audio Player: controls playback (evidence: `public/js/controllers/audio-controller.mjs`)
- Audio Controller → Verified Downloads: downloads recordings (evidence: `public/js/controllers/audio-controller.mjs`)
- Verified Downloads → Audio Storage: saves verified files (evidence: `public/js/services/audio-download-service.mjs`)
- Audio Controller → Recording Catalog: selects recordings (evidence: `README.md`)
- Reader → Offline Cache: caches app offline (evidence: `README.md`)
- Assistant Panel → Research Route: posts question (evidence: `README.md`)
- Research Route → Research Service: handles request (evidence: `app/api/research/route.ts`)
- Research Route → Evidence Retrieval: provides corpus (evidence: `app/api/research/route.ts`)
- Research Route → AI Client: configures client (evidence: `app/api/research/route.ts`)
- Research Service → Evidence Retrieval: retrieves evidence (evidence: `README.md`)
- Research Service → Meaning Search: matches meanings (evidence: `server/research-service.mjs`)
- Research Service → AI Client: generates answer (evidence: `README.md`)
- Research Service → Answer Validation: validates answer (evidence: `README.md`)
- Evidence Retrieval → Meaning Search: finds matches (evidence: `server/evidence-repository.mjs`)
- Evidence Retrieval → Hadith and Study Data: retrieves passages (evidence: `app/api/research/route.ts`)
- AI Client → Gemini: requests generation (evidence: `server/ai-client.mjs`)
