# kamrulhasan12345/bayyinah architecture

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

- Interactive diagram: https://gitdiagram.com/kamrulhasan12345/bayyinah
- Repository: https://github.com/kamrulhasan12345/bayyinah

## Overview

1. **The repository is a 4-part system**
   - `scripts/` generates Quran data artifacts.
   - `data/` stores the generated SQLite database and audio assets.
   - `bayyinah-core/` holds shared Quran domain types and query contracts.
   - `bayyinah-client/` is a JavaFX desktop app.
   - `bayyinah-server/` is a Spring Boot backend for auth, sync, and collaborative meetings.

2. **`bayyinah-core` is the shared domain boundary**
   - This module defines Quran-centric models such as chapters, verses, translations, and audio recitations.
   - It also defines query interfaces and page/search DTOs used by the client’s local data access layer.
   - For an architecture diagram, treat this as the shared “domain + query contract” layer that other modules depend on, not as a runtime service.

3. **`scripts/` is a build-time ingestion pipeline**
   - It is TypeScript-based and runs with Node 22.
   - It fetches or assembles Quran content and writes `data/quran.db`, plus optional audio files under `data/audio/`.
   - This is not part of the app runtime; it is the upstream producer of offline assets consumed by the desktop client.

4. **`bayyinah-client` is an offline-first JavaFX desktop application**
   - The UI is assembled from FXML views and JavaFX controllers: home, chapters, search results, bookmarks, reading progress, settings, login/registration, and a meeting view.
   - Controllers map directly to screens and components like chapter sidebar cells and verse cells.
   - The client also has theming and toast notification infrastructure, indicating a self-contained desktop UX layer.

5. **The client has a clear local-data subsystem**
   - `infra/local` contains SQLite/database management, local repositories, and local query services.
   - It reads the generated Quran database and persists user-local state such as bookmarks, notes, reading progress, auth tokens, and preferences.
   - This is the primary offline boundary: Quran content is local-first, while user/account features can sync outward.

6. **The client’s “hybrid” layer bridges local and remote state**
   - `infra/hybrid` contains models and services for syncing bookmarks, notes, reading progress, tokens, preferences, and user data.
   - There is a sync queue and orchestrator, which implies deferred or batched synchronization when connectivity is available.
   - For a diagram, model this as a mediation layer between local repositories and server APIs.

7. **The client’s remote access layer is service-oriented**
   - `infra/remote/client` contains an HTTP API client and a STOMP WebSocket client.
   - `infra/remote/query` groups remote capabilities by concern: AI chat, Quran, sync, user, and halaqah/meeting.
   - Route resolution is centralized, so the client likely resolves endpoint paths from a common API routing abstraction rather than hardcoding URLs throughout controllers.

8. **Audio and reading are part of the client runtime**
   - `infra/media/VerseAudioPlaybackManager` indicates the desktop app can play verse recitations from the generated audio assets.
   - This binds the offline data pipeline to the UI reading experience: chapter/verse views can use local text plus local audio without server dependency.

9. **`bayyinah-server` is the authoritative backend for identity and shared user state**
   - It is a Spring Boot app with controllers for authentication, bookmarks, notes, reading progress, user profile/preferences, and halaqah rooms.
   - It owns persistence for user accounts and syncable user data via Spring Data repositories.
   - This is the server-side counterpart to the client’s hybrid sync layer.

10. **Server security is JWT-based**
   - Authentication flows go through `AuthenticationController`, `JwtService`, and a JWT filter in the middleware layer.
   - The server also has user-details integration for Spring Security.
   - In the architecture diagram, place JWT auth as the gate in front of the REST APIs and as part of WebSocket access control.

11. **Realtime collaborative meetings are a distinct subsystem**
   - The server exposes both REST and WebSocket/STOMP infrastructure for halaqah rooms.
   - Room state, participant presence, chat, candidate/SDP signaling, and verse update messages are modeled explicitly in DTOs.
   - The client has matching WebSocket/STOMP DTOs and a WebRTC orchestration layer, so meeting traffic is a separate realtime path from ordinary REST sync.

12. **WebRTC signaling is server-mediated, media is client-side**
   - The server handles room lifecycle and signaling messages.
   - The client’s `infra/webrtc` package manages audio and the signaling orchestrator.
   - The actual media transport is not in the server; the server coordinates peers while the client owns playback and WebRTC runtime behavior.

13. **Persistence boundaries are split by concern**
   - The server uses PostgreSQL at runtime, with Flyway migrations in `src/main/resources/db/migration`.
   - The client uses local SQLite generated by `scripts/` and configured via a first-run YAML file in the user home directory.
   - This makes the system hybrid by design: curated Quran content stays local, while mutable user/account data is server-backed and synchronized.

14. **Error handling and configuration are centralized in both runtimes**
   - The client has app context, config management, and global exception mapping.
   - The server has global exception handlers and security/websocket exception handling.
   - Both apps therefore have explicit boundary layers for configuration, failure translation, and startup wiring, which are worth showing as cross-cutting infrastructure in the diagram.

15. **Key dependency direction**
   - `scripts` produces assets used by the client.
   - `bayyinah-core` is depended on by runtime modules as the shared domain contract.
   - `bayyinah-client` consumes local assets and optionally syncs to `bayyinah-server`.
   - `bayyinah-server` is the authority for authentication, synced user data, and realtime meeting coordination.

Main entry points: [`bayyinah-client/src/main/java/com/ks/bayyinah/infra/local`](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/local) (Local data), [`bayyinah-client/src/main/java/com/ks/bayyinah/infra/remote`](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/remote) (Remote APIs), [`bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/BayyinahServerApplication.java`](https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/BayyinahServerApplication.java) (Backend app), [`scripts/src/chapters.ts`](https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/chapters.ts) (Content builders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_scripts["Scripts"]
  node_n_scripts_entry["Ingestion<br/>Node 22 TS pipeline<br/>[index.ts]"]
  node_n_scripts_content["Content builders<br/>TS generators<br/>[chapters.ts]"]
  node_n_scripts_db[("SQLite output<br/>artifact writer<br/>[db.ts]")]
end

subgraph group_grp_core["Core"]
  node_n_core_models["Quran models<br/>domain models"]
  node_n_core_dto["View DTOs<br/>query/page DTOs"]
  node_n_core_query["Query contracts<br/>repository interfaces"]
end

subgraph group_grp_client["Client"]
  node_n_client_startup["Desktop app<br/>JavaFX shell<br/>[App.java]"]
  node_n_client_ui["Screens<br/>FXML+controllers"]
  node_n_client_local[("Local data<br/>SQLite repos")]
  node_n_client_hybrid["Sync layer<br/>hybrid services"]
  node_n_client_remote["Remote APIs<br/>HTTP+STOMP client"]
  node_n_client_webrtc["WebRTC runtime<br/>meeting runtime"]
  node_n_client_media(("Playback<br/>audio manager"))
end

subgraph group_grp_server["Server"]
  node_n_server_startup["Backend app<br/>Spring Boot"]
  node_n_server_auth["Auth gate<br/>JWT security"]
  node_n_server_rest["REST APIs<br/>controllers"]
  node_n_server_realtime{{"Realtime rooms<br/>STOMP+WebSocket"}}
  node_n_server_persistence[("PostgreSQL data<br/>repositories")]
end

subgraph group_grp_data["Data"]
  node_n_data_db[("quran.db<br/>offline asset<br/>[readme.md]")]
  node_n_data_audio["audio assets<br/>offline media<br/>[readme.md]"]
end

node_n_scripts_entry -->|"builds"| node_n_scripts_content
node_n_scripts_content -->|"writes"| node_n_scripts_db
node_n_scripts_db -->|"produces"| node_n_data_db
node_n_scripts_content -->|"emits"| node_n_data_audio
node_n_core_models -->|"used by"| node_n_client_local
node_n_core_dto -->|"used by"| node_n_client_local
node_n_core_query -->|"contracts"| node_n_client_local
node_n_core_models -.->|"shared types"| node_n_server_persistence
node_n_client_startup -->|"hosts"| node_n_client_ui
node_n_client_startup -->|"configures"| node_n_client_local
node_n_client_ui -->|"reads"| node_n_client_local
node_n_client_ui -->|"syncs"| node_n_client_hybrid
node_n_client_local -->|"opens"| node_n_data_db
node_n_client_local -->|"loads"| node_n_data_audio
node_n_client_hybrid -->|"delegates"| node_n_client_remote
node_n_client_hybrid -->|"persists"| node_n_client_local
node_n_client_remote -->|"calls"| node_n_server_auth
node_n_client_remote -->|"calls"| node_n_server_rest
node_n_client_remote -->|"signals"| node_n_server_realtime
node_n_client_webrtc -->|"signaled by"| node_n_client_remote
node_n_client_webrtc -->|"manages"| node_n_client_media
node_n_server_startup -->|"enables"| node_n_server_auth
node_n_server_startup -->|"hosts"| node_n_server_rest
node_n_server_startup -->|"hosts"| node_n_server_realtime
node_n_server_rest -->|"stores"| node_n_server_persistence
node_n_server_realtime -.->|"coordinates"| node_n_server_persistence

click node_n_scripts_entry "https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/index.ts"
click node_n_scripts_content "https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/chapters.ts"
click node_n_scripts_db "https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/db.ts"
click node_n_data_db "https://github.com/kamrulhasan12345/bayyinah/blob/main/data/readme.md"
click node_n_data_audio "https://github.com/kamrulhasan12345/bayyinah/blob/main/data/readme.md"
click node_n_core_models "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-core/src/main/java/com/ks/bayyinah/core/model"
click node_n_core_dto "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-core/src/main/java/com/ks/bayyinah/core/dto"
click node_n_core_query "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-core/src/main/java/com/ks/bayyinah/core/query"
click node_n_client_startup "https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-client/src/main/java/com/ks/bayyinah/App.java"
click node_n_client_ui "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/controller"
click node_n_client_local "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/local"
click node_n_client_hybrid "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/hybrid"
click node_n_client_remote "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/remote"
click node_n_client_webrtc "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/webrtc"
click node_n_client_media "https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/media/VerseAudioPlaybackManager.java"
click node_n_server_startup "https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/BayyinahServerApplication.java"
click node_n_server_auth "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/middleware"
click node_n_server_rest "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller"
click node_n_server_realtime "https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller/HalaqahController.java"
click node_n_server_persistence "https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/repository"

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_n_scripts_entry,node_n_scripts_content,node_n_scripts_db toneBlue
class node_n_core_models,node_n_core_dto,node_n_core_query toneAmber
class node_n_client_startup,node_n_client_ui,node_n_client_local,node_n_client_hybrid,node_n_client_remote,node_n_client_webrtc,node_n_client_media toneMint
class node_n_server_startup,node_n_server_auth,node_n_server_rest,node_n_server_realtime,node_n_server_persistence toneRose
class node_n_data_db,node_n_data_audio toneIndigo
```

## Components

### Scripts

Build-time ingestion pipeline that generates offline Quran assets.

- [Ingestion](https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/index.ts): Node 22 TS pipeline · Entry point that assembles Quran content and writes generated artifacts. · `scripts/src/index.ts`
- [Content builders](https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/chapters.ts): TS generators · Builds chapters, verses, translations, audio metadata, and database payloads. · `scripts/src/chapters.ts`
- [SQLite output](https://github.com/kamrulhasan12345/bayyinah/blob/main/scripts/src/db.ts): artifact writer · Writes the generated Quran database and supporting asset layout. · `scripts/src/db.ts`

### Core

Shared Quran domain models and query contracts.

- [Quran models](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-core/src/main/java/com/ks/bayyinah/core/model): domain models · Shared chapters, verses, translations, and recitation entities. · `bayyinah-core/src/main/java/com/ks/bayyinah/core/model`
- [View DTOs](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-core/src/main/java/com/ks/bayyinah/core/dto): query/page DTOs · Shared page, search, and view data structures for Quran queries. · `bayyinah-core/src/main/java/com/ks/bayyinah/core/dto`
- [Query contracts](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-core/src/main/java/com/ks/bayyinah/core/query): repository interfaces · Shared query interfaces and repository contracts for Quran data access. · `bayyinah-core/src/main/java/com/ks/bayyinah/core/query`

### Client

Offline-first JavaFX desktop application.

- [Desktop app](https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-client/src/main/java/com/ks/bayyinah/App.java): JavaFX shell · Application entry, context wiring, config, and global exception handling. · `bayyinah-client/src/main/java/com/ks/bayyinah/App.java`
- [Screens](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/controller): FXML+controllers · Home, chapters, search, bookmarks, progress, settings, auth, and meeting views. · `bayyinah-client/src/main/java/com/ks/bayyinah/controller`
- [Local data](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/local): SQLite repos · Manages local Quran access plus user state persisted in SQLite. · `bayyinah-client/src/main/java/com/ks/bayyinah/infra/local`
- [Sync layer](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/hybrid): hybrid services · Bridges local state with remote sync for tokens, bookmarks, notes, progress, and preferences. · `bayyinah-client/src/main/java/com/ks/bayyinah/infra/hybrid`
- [Remote APIs](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/remote): HTTP+STOMP client · API client, route resolver, and remote query services for auth, Quran, sync, user, AI, and halaqah. · `bayyinah-client/src/main/java/com/ks/bayyinah/infra/remote`
- [WebRTC runtime](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/webrtc): meeting runtime · Client-side audio management and signaling orchestration for collaborative meetings. · `bayyinah-client/src/main/java/com/ks/bayyinah/infra/webrtc`
- [Playback](https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-client/src/main/java/com/ks/bayyinah/infra/media/VerseAudioPlaybackManager.java): audio manager · Plays local verse recitations during reading experience. · `bayyinah-client/src/main/java/com/ks/bayyinah/infra/media/VerseAudioPlaybackManager.java`

### Server

Spring Boot backend for identity, sync, and meetings.

- [Backend app](https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/BayyinahServerApplication.java): Spring Boot · Application bootstrap, web, security, and websocket configuration. · `bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/BayyinahServerApplication.java`
- [Auth gate](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/middleware): JWT security · JWT service, authentication filter, and Spring Security integration. · `bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/middleware`
- [REST APIs](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller): controllers · Authentication, bookmarks, notes, reading progress, user profile, and halaqah REST endpoints. · `bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller`
- [Realtime rooms](https://github.com/kamrulhasan12345/bayyinah/blob/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller/HalaqahController.java): STOMP+WebSocket · Room lifecycle, presence, chat, and WebRTC signaling coordination. · `bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller/HalaqahController.java`
- [PostgreSQL data](https://github.com/kamrulhasan12345/bayyinah/tree/main/bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/repository): repositories · Persistent user accounts and syncable state backed by Spring Data repositories and Flyway migrations. · `bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/repository`

### Data

Generated SQLite database and audio assets consumed by the client.

- [quran.db](https://github.com/kamrulhasan12345/bayyinah/blob/main/data/readme.md): offline asset · Generated SQLite database consumed by the desktop client. · `data/readme.md`
- [audio assets](https://github.com/kamrulhasan12345/bayyinah/blob/main/data/readme.md): offline media · Generated verse recitation files used for local playback. · `data/readme.md`

## Connections

- Ingestion → Content builders: builds · Main pipeline invokes content generation stages.
- Content builders → SQLite output: writes · Generated Quran content is materialized into SQLite artifacts.
- SQLite output → quran.db: produces · Outputs the offline database used by the client.
- Content builders → audio assets: emits · Optional audio generation populates local recitation assets.
- Quran models → Local data: used by · Client local repositories depend on shared Quran entities.
- View DTOs → Local data: used by · Shared page and search DTOs shape local queries and results.
- Query contracts → Local data: contracts · Client implements or consumes the shared Quran query abstractions.
- Quran models → PostgreSQL data: shared types · Server uses the same Quran-centric domain vocabulary where relevant.
- Desktop app → Screens: hosts · Startup wiring opens and coordinates UI screens.
- Desktop app → Local data: configures · App context and config wire local persistence.
- Screens → Local data: reads · Screens query local Quran content and saved user state.
- Screens → Sync layer: syncs · UI actions can trigger sync-backed updates for account data.
- Local data → quran.db: opens · Local repositories read the generated SQLite database.
- Local data → audio assets: loads · Local audio repository and playback use generated recitation files.
- Sync layer → Remote APIs: delegates · Hybrid services push/pull through remote APIs when connectivity exists.
- Sync layer → Local data: persists · Sync queue and local stores hold deferred user changes.
- Remote APIs → Auth gate: calls · Remote auth and token flows are protected by JWT-based access control.
- Remote APIs → REST APIs: calls · Client sync, profile, and content requests go through REST APIs.
- Remote APIs → Realtime rooms: signals · Meeting and collaboration traffic uses STOMP/WebSocket channels.
- WebRTC runtime → Remote APIs: signaled by · Client WebRTC orchestration exchanges signaling through the remote realtime layer.
- WebRTC runtime → Playback: manages · Meeting runtime and playback coordinate local audio behavior.
- Backend app → Auth gate: enables · Security configuration sits in front of server APIs.
- Backend app → REST APIs: hosts · Spring Boot application serves REST endpoints.
- Backend app → Realtime rooms: hosts · WebSocket broker configuration supports realtime rooms.
- REST APIs → PostgreSQL data: stores · REST services use repositories for identity and syncable user data.
- Realtime rooms → PostgreSQL data: coordinates · Room state and participation are persisted or managed alongside backend storage.