How kamrulhasan12345/bayyinah works
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: local Local data · remote Remote APIs · BayyinahServerApplication.java Backend app · chapters.ts Content builders
Components 20
Scripts
Build-time ingestion pipeline that generates offline Quran assets.
- Ingestion · Entry point that assembles Quran content and writes generated artifacts.
scripts/src/index.ts - Content builders · Builds chapters, verses, translations, audio metadata, and database payloads.
scripts/src/chapters.ts - SQLite output · Writes the generated Quran database and supporting asset layout.
scripts/src/db.ts
Core
Shared Quran domain models and query contracts.
- Quran models · Shared chapters, verses, translations, and recitation entities.
bayyinah-core/src/main/java/com/ks/bayyinah/core/model - View DTOs · Shared page, search, and view data structures for Quran queries.
bayyinah-core/src/main/java/com/ks/bayyinah/core/dto - Query contracts · 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 · Application entry, context wiring, config, and global exception handling.
bayyinah-client/src/main/java/com/ks/bayyinah/App.java - Screens · Home, chapters, search, bookmarks, progress, settings, auth, and meeting views.
bayyinah-client/src/main/java/com/ks/bayyinah/controller - Local data · Manages local Quran access plus user state persisted in SQLite.
bayyinah-client/src/main/java/com/ks/bayyinah/infra/local - Sync layer · 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 · 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 · Client-side audio management and signaling orchestration for collaborative meetings.
bayyinah-client/src/main/java/com/ks/bayyinah/infra/webrtc - Playback · 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 · Application bootstrap, web, security, and websocket configuration.
bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/BayyinahServerApplication.java - Auth gate · JWT service, authentication filter, and Spring Security integration.
bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/middleware - REST APIs · Authentication, bookmarks, notes, reading progress, user profile, and halaqah REST endpoints.
bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller - Realtime rooms · Room lifecycle, presence, chat, and WebRTC signaling coordination.
bayyinah-server/src/main/java/com/ks/bayyinah/bayyinah_server/controller/HalaqahController.java - PostgreSQL data · 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 · Generated SQLite database consumed by the desktop client.
data/readme.md - audio assets · Generated verse recitation files used for local playback.
data/readme.md
Connections 26
- 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.