HadithDB

HadithDB (Hadith Unlocked) is a website for reading, searching, and citing the Quran and ḥadīth. You can browse it online at https://hadithunlocked.com.

Every record keeps the original Arabic text alongside an English translation where one is available, together with chapter listings and grading information. For ḥadīth, the chain of narrators (isnād) and the report itself (matn) are stored separately so each can be read and searched on its own.

MCP server

HadithDB exposes a read-only, stateless Streamable HTTP MCP transport at POST /mcp. After this version is deployed, the public endpoint will be https://hadithunlocked.com/mcp. It provides Quran and tafsir lookup/search, hadith search, full hadith-detail lookup, and Quran audio tools.

Substantive research is available through research_islamic_topic and research_quran_ayah. The topic tool takes a question, short Arabic/English queries, optional known hadith_references to anchor the evidence, and depth (brief, standard, or deep). It gathers discovery candidates, exact Quran/tafsir and hadith records, commentary from distinct works, and reports linked by verified internal references. Source numbers alone are never treated as cross-collection identities.

For ayah explanations, call research_quran_ayah with surah and ayah. Standard depth requests Tabari, Ibn Kathir and Qurtubi; deep adds Baghawi, Saadi and Ibn Ashur. Missing sources are reported rather than silently replaced. tafsirs overrides this selection. Read the returned texts, then call again with short grounded concepts to research relevant Quran/tafsir, hadith and shuruh. This is an assistant workflow within one turn, not a user follow-up. The tool does not pretend to infer semantic concepts on the server.

Dossiers distinguish direct tafsir, exact reports, source-linked reports, and conceptual search candidates. They return per-call found, searched_no_match, not_searched, or unavailable states, omissions and explicit next steps. Dossiers include selected source fields and bounded excerpts: discovery text is capped at 500 characters per field, retrieved source text at 3500, with truncation flags and exact lookup identifiers. They are not exhaustive surveys or generated rulings. A 25-second total deadline and depth-dependent call/source limits bound work; inspect coverage and retrieve truncated or omitted sources when consequential. Research depth does not dictate answer length.

list_hadith_commentaries, search_hadith_commentary and lookup_hadith_commentary expose the existing shuruh catalog and index. Search supports an exact commentary source alias and/or associated hadith reference; lookup uses an entry id. Compact hadith details now include research_inventory with commentary identities, work counts, and verified related references.

After deploying schema changes, update the published plugin/connection metadata and verify the tools visible in a fresh client session against tools/list. Publishing the JSON schema URL alone does not refresh an installed plugin’s schema snapshot. In particular, lookup_hadith_detail must expose response_profile to clients as it does on the server.

The public tool schema is available at GET /mcp-server/schema.json, linked from /mcp-server. It includes the server and protocol versions and the same tool definitions returned by MCP tools/list, including input/output schemas and annotations. It is generated from the running server’s definitions and requires no MCP initialization or authentication.

get_quran_audio returns a full-surah audio_url, a playback_url with a seconds-based media fragment, passage start_ms / end_ms, and ordered ayah segments with millisecond boundaries. For example, {"surah":2,"ayah_from":255,"ayah_to":257} defaults to Juhani; add reciter to select an alias or exact name from list_quran_reciters. Omit ayah_to for one ayah. Supply the first and last ayah for a whole surah; call once per surah for a passage spanning surahs. Incomplete timing coverage returns an error. These tools supply playback data; the client must play the URL, seek to the start, and stop at the end. Media-fragment support depends on the player.

Quran navigation tools expose the stored Mushaf layout and editorial headings:

• lookup_quran_page: pass page, or surah and ayah, for edition information, ayah ranges and word boundaries, overlapping headings, and stored introductions. Its page overview is assembled from source headings, not a separately authored narrative summary. Ayahs can span pages; word boundaries identify the portion here.
• list_quran_sections: pass surah to discover passage (level 2) and subsection (level 3) identities, bilingual titles, introductions, and exact ayah ranges. Follow next_offset; default limit is 25, maximum 100.
• lookup_quran_passage: pass surah and section (optionally subsection), or surah and ayah to resolve the containing passage. Returns parent/child relationships and Mushaf page links as well as the source heading record.

These tools preserve absent language fields as null. response_profile controls per-heading introduction length: compact 1000, default 6000 characters per language, or full without truncation. Introductions describe the entire heading range, which may extend beyond a requested page. Titles and ranges are preserved. An assistant can write a narrative page summary from this source material when asked, clearly distinguishing its synthesis from the stored editorial text.

Arabic and English are exposed separately when the underlying record provides both languages; unavailable language fields are returned as null rather than synthesized. Long tafsir and hadith-detail tools accept compact, default, and full response profiles. Hadith detail defaults to compact; default adds bounded scholarly attribution and commentary, while full is the explicit complete-provenance mode. Search tools return exact-size pages, pagination metadata, and opaque cursors; Quran search merges translation hits under each canonical ayah. Pagination reports whether its total is exact; total_available is null while the backend has only fetched enough data to prove another page exists. Searches reject logical offsets beyond 500, scan at most six underlying pages per call, and enforce a ten-second deadline. list_tafsirs also returns total, has_more, and an opaque query-bound cursor. Quran ayat, Quran search results, hadith search results, and hadith-detail records expose bilingual, text, text_arabic, text_english, and truncated. Full-profile hadith-detail sharh entries retain their existing text and text_en source fields and additionally expose language-explicit fields. The bounded default profile exposes the language-explicit commentary fields without duplicating the original long text fields.

The endpoint accepts JSON-RPC 2.0 requests for initialize, ping, tools/list, tools/call, skills/list, skills/get, and resources/read. It advertises five source-aware research skills through OpenAI's static MCP skill-import extension. It does not create sessions, so clients should not expect an Mcp-Session-Id response header. Browser preflight requests are supported with OPTIONS /mcp; the public edge owns the complete CORS response for this path, while the application validates browser origins and native clients may omit Origin. Other HTTP methods return 405.

curl https://hadithunlocked.com/mcp \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

The endpoint has a 64 KiB request limit and a per-IP rate limit. Override the defaults with MCP_RATE_LIMIT_WINDOW_MS and MCP_RATE_LIMIT_PER_IP. Internal tool requests use the current request host by default; staging deployments can override the backing sites with HADITHDB_MCP_HADITH_BASE_URL and HADITHDB_MCP_QURAN_BASE_URL. Add browser origins with the comma-separated MCP_ALLOWED_ORIGINS setting. See MCP data handling for the redacted audit-log contract and retention setting.

What's New

Recent work has improved the reading, browsing, and search experience across the site:

• Reading the Quran — move naturally between Passage, Ayat, Mushaf, Practice, and Mudhakkir views while the site keeps your place. You can like, comment on, bookmark, and share a passage, move easily between verses and sections, and use the page-faithful Mushaf with database-backed spaced repetition.
• The 15-line Mushaf — read all 604 pages in a responsive, page-faithful Digital Khatt layout with infinite scrolling, Quranic surah headers, interactive words and ayah markers, page bookmarks, passage-aware coloring, and continuous recitation.
• Commentary and translation — full-page commentary and translation views, tabs for switching between works, authored book and surah introductions, hover explanations, dynamic translation selection, and the option to show Arabic and English side by side. You can turn individual works on or off and choose the order they appear in.
• Quran audio — choose a reciter, begin from a selected ayah, continue across page boundaries, repeat a passage or subsection, and control playback speed without losing synchronized ayah highlighting or translation captions.
• Search — a site-wide search panel switches between ḥadīth and Quran + Tafsīr while remembering a separate query for each. It supports canonical Quran ordering, Arabic RTL input, virtual collections, book-group shortcuts, per-work filters, and unified suggestions for surahs, ayat, translations, tafsīr, and ḥadīth.
• Enriched ḥadīth details — individual reports can include multiple scholarly grades, report and chain classification, a linked narrator timeline, uncommon-word definitions, sourced explanations, and references to similar or supplementary transmissions.
• Outline navigation — responsive section menus and sticky desktop rails follow the current chapter, passage, subsection, or metadata section and expose nearby headings for faster movement through long works.
• Sharing — responsive Quran and ḥadīth share cards support editable copy, text-size controls, selectable translations, Copy text, Copy image, and the device share sheet.
• MCP access — a read-only Streamable HTTP endpoint exposes Quran, tafsīr, ḥadīth search, and full ḥadīth-detail tools to compatible clients without creating server-side sessions.
• My Settings — separate starting points for ḥadīth and Quran, remembered commentary, translation, and reciter preferences, and bookmarked passages and Mushaf pages saved for later.

Hadith Features

• Browse source books and thematic virtual collections with bilingual chapter and section navigation, stable book:number citations, and JSON, TSV, EPUB, or Markdown output where available.
• Search the whole ḥadīth library or narrow it to individual books and the Sahihayn, Four Sunan, Six Books, or Nine Books groups. Virtual collections remain searchable alongside their source books.
• Read Arabic isnād and matn separately from the English translation. Report attribution and chain categories identify material such as prophetic, companion, or successor reports and connected or interrupted chains when that metadata is available.
• On enriched detail pages, compare scholarly grading opinions, follow a vocalized narrator-by-narrator isnād with biographical links and reliability notes, open definitions of uncommon Arabic terms, read Arabic or English sharḥ, and follow similar-report references back into the library.
• Supplementary source transmissions are linked to their primary local report instead of being presented as unrelated duplicate records.
• Like, bookmark, comment on, cite, and share reports. The share editor can resize or omit language blocks and copy either formatted text or a generated image on desktop and mobile.
• Administrators can revise text and headings in place, manage scholarly grades and sourced explanations, link similar reports, enrich metadata from configured sources, and refresh the affected search and rendered caches without changing the public citation.

Quran Unlocked

Read the Quran as a book, explore it as a study text, and hear it as a continuous recitation—all in one place. Quran Unlocked combines a responsive 15-line Mushaf with word-level learning, passage structure, trusted translations and tafsīr, personalized audio, and tools for saving and sharing what matters.

Open the Mushaf and begin where you left off. Tap a word for its meaning, select an ayah to read its translation, or let the recitation carry you seamlessly across pages. Switch to Practice to test recall against the same 15-line page layout, or move instantly to a focused ayah or structured passage without losing your place.

Quran Features

Five connected reading modes

• Passage presents the Quran in titled sections and subsections for thematic reading.
• Ayat focuses the reading experience on individual verses and the ayah hero view.
• Mushaf reproduces the familiar 15-line, page-by-page reading experience.
• Practice keeps the Digital Khatt Mushaf font and 15-line page layout while replacing ordinary words with underlined blanks. The basmalah and ayah markers remain visible.
• Mudhakkir tests due ayat using an ayah-level spaced-repetition schedule. Learning ayat enter the queue first and progress through short new-card steps before graduating to Good.
• The mode links, page subtitle, URL, previous/next links, and related passage automatically follow the content currently in view during infinite scrolling.
• Direct navigation is available by surah, ayah, passage, subsection, juz, manzil, Mushaf page, and search result.

A responsive Digital Khatt Mushaf

• All 604 pages use Digital Khatt Quran text in a page-faithful 15-line layout.
• Pages load continuously with vertical infinite scroll; after page 604, reading can continue again from page 1.
• The layout scales for desktop, portrait phones, and landscape phones without changing through the normal text-size controls or bleeding beyond the page.
• Quranic surah headers use the QCF header font. A new surah opens with its header and basmalah kept with the beginning of the surah; Surah 9 correctly omits the basmalah.
• Subtle inner-edge shading distinguishes odd and even pages like an open printed book.
• Alternating black and saddle-brown text reveals h3 subsection boundaries while preserving the Quranic styling of ayah markers.
• Each page identifies its page number, juz, surah number, and Arabic surah name. Page, juz, and surah numbers are directly editable, while the custom surah picker opens at the current surah.
• The page footer links the passage and subsection titles that actually begin on that page, making the Mushaf’s thematic structure visible without repeating earlier headings.
• /quran/page resumes at the bookmarked Mushaf page, or page 1 when no page bookmark exists.

Practice view

• Open a Mushaf page with ?memorize, such as /quran/page/1?memorize, select Practice from the Quran reading-mode controls, or use the Practice item after Tafsir in the Quran menu.
• Hidden words retain their exact Digital Khatt width and placement and are individually underlined, preserving the page-faithful 15-line layout. Surah headers, the basmalah, and ayah markers remain visible.
• Clicking a hidden word reveals it; clicking that visible word hides it immediately. When Word auto-hide is enabled, a clicked word fades back to an underlined blank after two seconds.
• The chevron beside each āyah marker includes Play and Reveal in Practice mode. Reveal changes to Hide while that āyah is visible. Play uses the reader's default reciter, automatically reveals the complete āyah, plays only that one āyah, and shows its translation in the audio marquee; neither action changes memorization or FSRS state. Play remains available during Mudhakkir, while the separate Reveal and Hide actions are omitted there.
• Clicking an ayah marker toggles that complete ayah between visible text and blanks without changing the other ayat.
• Alt-clicking, Option-clicking, Command-clicking, or Control-clicking an ayah marker toggles that ayah and all earlier ayat on the Mushaf page between visible text and blanks.
• Icon-only Page and Word auto-hide controls appear at both the top and bottom of each page. The bottom controls replace the passage and subpassage headings in Practice mode.
• The Page control reveals every word on that page or returns the page to blanks. Hiding also clears individual word and ayah reveals.
• The Word auto-hide control determines whether individually clicked words disappear after two seconds or remain visible. Auto-hide is off by default and remains a page-local display control; it is not stored as memorization progress in the browser.
• The plus and minus controls reveal the next hidden ayah or hide the most recently revealed ayah, one ayah at a time.
• Each page keeps its own state as additional pages load through infinite scrolling, and Practice mode remains active through page, surah, juz, URL, and previous/next navigation.
• Audio, reciter and translation controls, the translation marquee, and word-translation tooltips are intentionally omitted so the view remains focused on recall.

Ayah-level memorization and spaced review

Memorization identity is the surah and ayah reference, not a Mushaf page. Page numbers remain useful for navigation, but every ayah has its own lifecycle, schedule, and append-only review history. Untouched ayat behave as Later without creating 6,236 rows for every user.

The six visible memorization states use the same recall language as the review grades. Automatic recovery is stored internally but presented inside Hard:

• Signed-in readers make one initial self-assessment for an untouched Later āyah: Learn, Hard, Good, or Easy. After enrollment, review grades manage Learning, Hard, and Good; individual āyah, page, surah, and progress-group controls expose Easy, Paused, and Later. A complete page or surah can receive another initial bulk assessment only while all of its āyāt are Later. Signed-out readers are not shown a control that could imply local persistence.
• A new account with no Quran memorization rows starts with all 18 āyāt of Surahs 1, 113, and 114 in Learning. Initialization is idempotent and never adds these starter āyāt to an account that already has any memorization state recorded.
• An initial Learning assessment creates a New FSRS 6 card, admits it gradually within the Learning and overall session caps, and gives admitted Learning cards the highest queue priority. Again resets learning progress, Hard keeps it Learning, two successful Good reviews graduate it, and Easy graduates it immediately. The first intervals are approximately 10 minutes to 1 day for Again, 1 to 2 days for Hard, 3 to 4 days for Good, and 6 to 7 days for Easy before FSRS adapts them from review history. The Learning summary tile on Memorization Progress filters to groups containing Learning ayat and links each group directly to its first Learning ayah in Practice mode.
• An initial Hard assessment initializes the ayah like a Hard review result, with lower stability, higher difficulty, and a short first interval. Hard āyāt remain eligible for regular review. One Easy or two consecutive Good reviews can promote Hard to Good once its FSRS difficulty is 6 or lower; difficulty greater than 6 keeps it Hard.
• An initial Good assessment confirms that the complete ayah can be recited independently. FSRS initializes it like a Good result, records the memorization date, and schedules its first recall from that strength. Good is not a terminal archive: the scheduler continues adapting the interval after each review.
• An initial Easy assessment initializes the FSRS estimate like an Easy result, records a memorization date, clears the next review date, and keeps the āyah out of regular review. It can still be included deliberately in a custom Surah review session.
• A scheduled Good or Hard āyah also graduates automatically to Easy after a Good or Easy review when its FSRS stability is greater than 730 days and difficulty is below 2. Graduation clears its next review date. Existing cards that already satisfy both thresholds are migrated to Easy. A user may also mark an individual enrolled āyah as Easy directly.
• Hard combines deliberately fragile memorization, any scheduled āyah with an FSRS recall-difficulty score greater than 6, and scheduler-driven recovery after Again on a Good āyah. Recovery remains distinct internally for scheduling, but it uses the Hard label, red color, count, and progress filter. Successful reviews return it to Good only after calculated difficulty reaches 6 or lower.
• Later, Easy, and Paused āyāt never enter regular Learning or Mudhakkir queues. Regular review for a surah follows that same rule. An all-āyāt review deliberately enrolls Later āyāt in the selected surah as Learning and can include Easy and Paused āyāt in the session. After enrollment, the only manual changes are Easy, Paused, or Later, and all preserve review history. Internal recovery remains distinct from Later and is presented as Hard because it represents previously memorized recall that now needs strengthening.
• Practice and Mudhakkir use consistent accents for Learning, Hard, Good, Easy, and Paused. Hard is red, Good is blue, and Easy is green, matching the review-grade buttons. Internal recovery uses the Hard presentation. The regular Mushaf does not show memorization-state highlights. Where accents are shown, the full ayah is treated without reducing Arabic-text contrast, and the marker also exposes a textual state so color is not the only cue.

Select Mudhakkir to open /quran/review, which combines Memorization Progress with the session launcher. Progress reports Due now, Learning, Hard, Good, Easy, Paused, and Later against the canonical 6,236 ayat rather than counting stored rows alone. Due now includes initialized FSRS cards whose scheduled timestamp has arrived. Learning includes both ungraded FSRS New cards and Learning cards with review history, since New is an internal FSRS phase rather than a separate memorization state. Automatic recovery remains internal and is included in the Hard count, filter, color, and page summaries. Hard, Good, and Easy are initialized immediately from the user's stated memory strength. The active-progress table groups Mushaf pages beneath each surah and shows a shared page under every surah it contains; each row counts only that surah's ayat on the page and shows its per-stage totals and Arabic opening words without a translation.

The top of the signed-in Mudhakkir page shows a one-year review activity heatmap, today's reviewed āyāt and elapsed review time, daily average, percentage of days learned, longest streak, and current streak. Scheduler, review, and session timestamps are stored as UTC. Due checks compare UTC instants, while displayed dates, heatmap days, streaks, and the set of āyāt revealed as reviewed today use the current browser's timezone. This keeps late-evening reviews on the user's local day while progress remains consistent across devices.

Signed-out visitors see a concise Quran memorization introduction with a sign-in invitation, a plain-language explanation of how adaptive spaced review keeps Quran hifz fresh, progress-tracking benefits, and a link to explore the Mushaf. Memorization Progress and review-session controls are shown only after authentication.

During a recall attempt, the sticky controls record a result rather than changing a permanent status directly:

Mudhakkir pages after page 1 show the final Arabic line of the preceding Mushaf page in a compact, always-visible continuity strip above the current page. The strip is non-interactive and excluded from concealment, grading, memorization-state controls, and audio selection.

The help text reserves Again for an attempt that required reading the ayah or receiving its missing continuation; Hard still means the complete ayah was recalled independently. The first Again queues the same āyah once near the end of the session. A second Again records the lapse without another retry, so the same āyah can receive Again at most twice per session and cannot create an unlimited loop.

Regular review sessions are persisted and bounded. They admit eligible Learning, Hard, and Good āyāt, including automatic Hard recovery, allocate the overall limit fairly across nonempty categories, and present Learning first. Fragile Hard āyāt and previously Good āyāt in Hard recovery share one combined Hard cap. Newly enrolled, ungraded Learning cards are immediately included in Due now, but enter each session gradually under the Learning cap. Any one-time Again retries follow the original queue; Easy āyāt are not admitted to regular sessions. An āyah cannot reappear after a grade or Skip unless it entered that retry slot. My Settings → Quran Memorization and the Mudhakkir settings modal configure the maximum total āyāt per session (default 10), optional time budget, and a collapsed Advanced session limits group containing Learning, Hard, and Good caps plus queue order.

Page and surah review

The Start Review menu offers a custom Surah Review session. Its autocomplete accepts English names, Arabic names, Arabic or Latin surah numbers, and alternate names. Suggestions use the Quran search result style and show the surah number, English name, Arabic name, and total āyāt.

Practice mode also places a Mudhakkir button beneath each Mushaf page. Its contextual dialog offers Just this page or A surah. Just this page creates a persisted page-review session containing the āyāt on that exact Mushaf page, including pages shared by multiple surahs. A surah opens the same searchable Surah Review workflow without requiring the user to return to Memorization Progress first.

After choosing a surah, the user chooses one of two review types. Regular review uses only that surah's eligible Learning, Hard, and Good āyāt, follows their existing due schedules and regular session limits, and does not enroll or change untouched āyāt. All-āyāt review enrolls every missing or Later āyah in the surah as Learning and adds the complete surah to a persisted Quran-order session. Already-enrolled Learning, Hard, Good, Easy, and Paused āyāt receive no enrollment write: their existing state, schedule, and history are preserved when the session is created, and they are simply added to its queue. The user can review āyah by āyah or passage by passage. Passage review uses the most specific Study range containing the current āyah—an h3 range when available, otherwise its h2 range. The passage is only an āyah batch: the chosen result is recorded as a separate review event for every included āyah, and each āyah receives its own FSRS calculation, state, and next-review schedule.

Page-review and all-āyāt sessions are not constrained by Due now, regular category caps, or the optional time budget. They continue until every included āyah has been graded or skipped. Regular review for a surah uses the normal scheduler and its limits. Again, Hard, Good, and Easy are recorded as real FSRS assessments, so grading an Easy or Paused āyah in an all-āyāt session can return it to scheduled memorization according to the result. Skip advances without changing the āyah's state, schedule, or review history.

The Mushaf review footer can pause a page or surah review session without losing its current āyah or queue position, or end it while preserving completed review history. Memorization Progress lists the active session together with paused sessions. Continuing the active session or switching to a paused session is explicit; switching atomically pauses the current session before resuming the selected one. Any active or paused session can be ended. Ending closes its remaining queue while retaining completed FSRS review history.

FSRS 6 settings are available in My Settings and in a modal on /quran/review:

• Target Memory Goal ranges from 80% to 95% and defaults to the recommended 90%. Raising it increases review frequency.
• Initial Memory Strength adjusts the first intervals for new ayat.
• Mudhakkir Interval Multiplier offers conservative, standard, and aggressive stability growth.
• Lapse Recovery Speed offers mild, standard, and strict stability penalties after Again.
• Personalize Algorithm uses the official FSRS optimizer after at least 100 graded reviews. It trains all 21 FSRS 6 parameters from the user's append-only history and is intended to be rerun about monthly.

Difficulty damping, mean reversion, and same-day review smoothing are handled automatically. The simplified controls transform the default or personalized parameter vector and do not expose the underlying mathematical weights.

Mudhakkir deliberately uses one focused ayah workflow rather than separate Individual Ayah and Connected Recitation modes. A grade applies only to the scheduled ayah. The current target, preceding ayat, and ayat already completed during review remain fully visible for Quran context, while future unreviewed ayat stay muted. Mudhakkir sessions and API responses no longer store or return a display mode or fetch separate adjacent-ayah context. Legacy review-mode URL parameters are redirected to the canonical ?review=surah:ayah form.

Mudhakkir initially shows Reveal instead of the recall grades. Selecting Reveal displays the scheduled āyah or Study passage and then exposes Again, Hard, Good, and Easy. Saving a grade and selecting the next persisted review unit happen in one API request, so the interface advances as soon as the transaction commits instead of waiting on a second queue request or an artificial display delay. The footer's Undo action reverses the most recent single-āyah grade atomically, restoring the prior FSRS state, review event, session counters, and queue item even after the next āyah has loaded. Every āyah that precedes the current Mudhakkir target on its Mushaf page is always revealed so the passage remains in Quran order. Āyāt already graded during the current day's review work also remain revealed whenever they are visible on a later Mudhakkir page, even if Start Review created a replacement session; unreviewed āyāt after the current target and Again-retry answers remain concealed until their turn is completed. The active session, current attempt, review history, and revealed-review list are restored from authenticated server data after navigation, reload, or switching devices; memorization state is never managed in browser storage. The icon-only Skip action remains available before and after Reveal and advances immediately without revealing, grading, or permanently revealing the answer.

Scheduling uses FSRS 6 with its 21-parameter model and trainable forgetting-curve decay. The per-user, per-ayah card stores FSRS state, stability, difficulty, scheduled interval, learning-step position, review and lapse counts, the latest grade, and last and next review times. Recall attempts are appended to a separate history table for statistics and parameter optimization; moving an ayah to Later, Easy, or Paused never deletes those events.

Changing Target Memory Goal bulk-reschedules every initialized Learning, Hard, Good, and automatic-recovery card from its existing stability and last review time. The update changes stored review dates and Due now immediately without fabricating grades or review-history entries. Easy, Paused, Later, and ungraded new Learning cards are not rewritten.

Google Analytics records privacy-safe Quran memorization events without account identifiers: quran_review_session_start, quran_review_session_resume, quran_review_item_presented, and quran_review_grade measure review participation and Mushaf pages reviewed. quran_memorization_enroll records successful first-time enrollment conversions with an enrollment_scope of ayah, page, or surah and the number of newly enrolled āyāt. Mark quran_memorization_enroll as a key event in Google Analytics to report it as a conversion.

The quran_script_default event and quran_script_default user property measure unique users by their resolved Quran script preference: uthmani, indo-pak, or warsh. The event is emitted once per page for the resolved default and again only when the preference changes on that page; no account identifier is included.

This is an initial ayah-level FSRS deployment, not an upgrade from an earlier ayah scheduler. Initialize the tables and replace every existing user's Quran memorization settings with the canonical FSRS 6 defaults by running npm run init:quran-fsrs6. The initializer preserves unrelated user settings. Use npm run init:quran-fsrs6 -- --dry-run to preview how many user rows will be updated without creating tables or writing settings.

The memorization tables use case-sensitive ASCII user identifiers and composite indexes for exact ayah lookup, due-review selection, recently reviewed ayat, active sessions, and persisted session queues. Existing installations can preview and apply the schema optimization with:

npm run quran-memorization-optimize
npm run quran-memorization-optimize -- --apply

Interactive Arabic and ayah tools

• Hovering over a word highlights it using the same interaction language in Passage and Mushaf views.
• Clicking a Quran word reveals corpus information and its word-level translation. In the standard Mushaf it also toggles selection of the complete ayah; Practice mode instead performs its temporary reveal without translations.
• Selected and audio-playing ayat use a full-ayah highlight and the established Quran passage colors rather than disconnected word boxes.
• Clicking elsewhere clears the selected ayah.
• Ayah markers offer the same compact View and Play actions in Passage and Mushaf modes. View opens the focused ayah; Play begins recitation from that marker.
• Clicking an ayah, word, or marker displays its selected translation in the footer marquee, even when audio is not playing.
• Juz starts are marked with ۞, and Quran metadata such as sajdah markers can be rendered alongside the standard ayah marker.

Continuous, passage-aware audio

• Recitation uses continuous surah recordings with ayah timing segments, avoiding the audible breaks caused by stitching together separate per-ayah files.
• Playback continues across lazy-loaded Mushaf pages and passage boundaries while the current ayah remains highlighted.
• Audio begins at the selected ayah; without a selection it begins at the top of the current page or passage.
• Repeat is a true toggle. It repeats the current h3 subsection, falling back to its h2 passage, even when that range crosses a page boundary.
• The active reciter can be changed during playback. Available reciters are alphabetized, can be enabled or disabled in My Settings, and the preferred reciter is remembered.
• The sticky audio footer provides previous, repeat, play/pause, stop, speed, and next controls in one non-wrapping row.
• Playback speeds are x1, x1.25, x1.5, x2.0, x2.5, and x3. The selected rate is retained for the browser session and reapplied after stop, resume, source changes, and page transitions.
• A translation marquee appears above the sticky footer during playback. It identifies the reciter and translation once, uses unobtrusive superscript ayah references, honors LTR and RTL translations, and streams consecutive translations separated by a spaced dot—starting each entry from the center as its audio segment begins.

Translations, tafsīr, and study

• Change the active translation directly from Passage or Mushaf controls.
• Show or hide Arabic and translation text independently on passage pages.
• Open available translations, bilingual tafsīr, Arabic tafsīr, and English tafsīr for an ayah without leaving the reading workflow.
• Tafsīr tabs, translation disclosures, footnote popups, hover explanations, and side-by-side Arabic/English layouts support both quick reading and deeper study.
• Tafsīr and translation works can include collapsible book introductions and surah introductions with direct links and previous/next navigation into the Quran text.
• The books catalog can be filtered across ḥadīth, Arabic and English tafsīr, and translations; tafsīr entries identify their relative size and can be ordered by author or publication chronology.
• A work may be exposed in both the translation and tafsīr catalogs when its content serves both roles, while each route keeps the appropriate reading and navigation experience.
• My Settings controls the preferred translation and reciter, enabled translations, tafsīrs and reciters, and the display order of translation and tafsīr works.
• Translation choices are synchronized across passage text, the ayah hero, Mushaf controls, share cards, and the audio/selection marquee.

Navigation, saving, and sharing

• Infinite Passage and Mushaf readers update their canonical reading context as the user scrolls.
• A responsive heading outline shows the current Quran passage or subsection and nearby previous and next headings on Passage, Mushaf, tafsīr, and translation pages.
• The compact sticky footer provides back, Quran home, text controls, and context-aware previous/next navigation; in Mushaf mode those links move by page.
• A single Mushaf page bookmark is maintained at a time, appears on the Bookmarks page, and determines the default /quran/page destination.
• Quran passages and ayat support bookmarks, likes, comments, reflections, and shareable image cards with selectable translations.
• Keyboard navigation and accessible labels complement touch, mouse, and mobile controls.

Search, downloads, and integration

• Unified search covers Arabic and translated Quran text, translations, and tafsīr, with autocomplete, filters, highlighting, and direct verse navigation.
• Quran content is addressable through stable ayah, range, passage, subsection, juz, manzil, translation, tafsīr, and Mushaf-page URLs.
• Machine-readable JSON and Markdown responses support individual ayat and ranges, while translation and Quran downloads are available in JSON or EPUB where provided.
• Quran passages, commentary pages, translations, and all Mushaf pages are included in the sitemap.

Editorial and performance support

• Passage and subsection ranges can be edited and reindexed while maintaining their Passage-to-Mushaf mapping.
• Heading, range, and title changes invalidate the related Passage and Mushaf caches so stale section references are not retained.
• Mushaf page data and section mappings use in-memory and search caches where appropriate, with disk-cache versioning and explicit flush support for updated content.

Quran Reciters

The site includes the continuous, ayah-synchronized recitations listed below. Each one has a short alias used internally for audio selection and saved preferences.

Quran Commentaries and Translations

The site includes the commentary (tafsīr) and translation works listed below. Each one has a short alias used in links and an English title.

Bilingual tafsīr

Arabic tafsīr and Quran companions

English translations

English tafsīr

Books and Collections

The catalog currently exposes 29 books and collections: 26 source books (including the Quran) and 3 themed collections drawn from them. The source books together hold 273,324 records, and the collections link to another 4,754.

In the table below, Records is the number of entries in each work, English is how many of those have an English translation, and Graded is how many carry a primary or enriched authenticity grading. Graders summarizes the compact primary-grade field; enriched detail pages may contain additional scholarly opinions. The counts were refreshed from the local catalog on 2026-09-05.

Admin-only content translations

Set payments.content.adminOnly to true in ~/.hadithdb/settings.json and restart the app to disable payments and restrict new translations/revisions to authenticated admins. Admin translations cost zero points and do not require Stripe. The Payments section in My Settings is hidden, and payment endpoints are disabled. Existing translations remain readable by everyone. The separate Tafsir translation switch still applies.

Set the flag to false (the default) to restore the existing paid translation flow, subject to payments.enabled and Stripe configuration.