Source files
Everything on the reference page — the mapping files, the per-surah counts, the totals — is derived. This page documents what it is derived from: two hand-edited files, and the transcriptions that back them.
Read this if you are auditing a claim, contributing a correction, or building on the source layer rather than on the generated output. If you only need to translate a reference, the reference page is the whole story.
Two layers, and why they are separate
data/book-boundary-primitives.json records claims: where a disputed boundary falls and which
counting systems treat it as a head of ayah. data/book-boundary-evidence.json records witnesses:
which classical work attests each claim, at which locator, in which edition.
They mirror each other position for position and never merge, because they answer different questions and change for different reasons. Evidence can support or qualify a claim; it never silently edits one. A change to the claim itself belongs in the primitives file.
An ordinary, undisputed Kufan ayah end is not in either file. It needs no supporting text, so listing it would be recording the absence of a dispute. The whole source layer is 246 positions.
book-boundary-primitives
Keyed by surah, then by the Kufan ayah the position falls in, then by kind. Al-Fātiḥa in full:
"surahs": {
"1": {
"1": { "end": { "word": "الرحيم", "counted_by": ["makki", "kufi"] } },
"7": { "internal": [ { "word": "عليهم",
"counted_by": ["madani-first", "madani-last",
"basri", "dimashqi"] } ] }
}
}
| Field | What it holds |
|---|---|
| end | A disputed position at the end of that Kufan ayah. An object, not an array — there can only be one. |
| internal | Disputed positions inside that Kufan ayah. An array, in reading order. |
| word | The fāṣilah wording, which anchors the position to the text. |
| counted_by | The systems that count this position as a head of ayah. Anything not listed does not count it. |
| _reference_system | The axis the ayah keys are expressed in. Always kufi. |
It is a bare orthographic word for identification — not the muṣḥaf’s spelling, and it carries no word index. String-matching on it against rendered text will miss. To locate a boundary in text you render, use the ayah numbers from the mapping files against Quran Text.
No generated totals live here. Surah counts are derived from these claims; writing them alongside would create two sources of truth that can drift.
book-boundary-evidence
The same keys, carrying the witnesses behind each claim and its documentation state.
"7": {
"internal": [ {
"word": "عليهم",
"verification_status": "primary_cited",
"evidence": [ {
"tier": "primary",
"work": "البيان في عدّ آي القرآن",
"locator": "ص 139",
"supports": ["madani-first", "basri"],
"strength": "direct",
"edition": "…"
} ]
} ]
}
| Field | What it holds |
|---|---|
| tier | primary, commentary, secondary, modern-reference or api-check — see method and evidence |
| work | The counting work cited |
| locator | The place within it |
| edition | The edition relied on, so the locator can actually be checked |
| supports | The systems this witness speaks for. Need not be all of counted_by — one witness rarely attests every system at a position. |
| strength | direct for an explicit statement, derived where it follows by inference |
| verification_status | How well attested the claim is, as a whole — the six values are listed under method and evidence |
Transcribed witnesses
sources/ holds structured transcriptions from the counting works themselves, checked in so any
entry in the evidence layer can be traced back to something readable. Each witness identifies the
work and edition, the location within it, the positions it speaks to, and the systems it supports.
It is kept apart from generated output for two reasons: it has to stay auditable on its own, and regenerating must never overwrite a transcription. Primary works and later ones are recorded independently, so a reviewer can see what each source does and does not establish.
Importing a supplied bundle is a contributor workflow with its own rules — an import may add or enrich evidence but may not rewrite a claim, and a disagreement between a bundle and the recorded claim is surfaced for review rather than reshaped to fit. That process lives with the repository that runs it: see CONTRIBUTING.md.
Which paths you can fetch
| Path | In the git tree? |
|---|---|
| data/*.json | Yes — the hand-edited source layer |
| sources/ | Yes — the transcriptions |
| dist/site-data.json | Yes — every disputed position with its evidence, in one file |
| dist/mushaf/surah-NNN.json | Yes — muṣḥaf tokens with the token offset of each boundary |
| dist/mappings/, dist/surah-counts/, dist/rawis/ | No — generated, and dist/ is gitignored. Clone and run npm run generate. |
dist/ is listed in the repository’s .gitignore, yet site-data.json and the 114 muṣḥaf files
under it are committed anyway — they were moved there when the project’s standalone website was
retired, and this site reads them from the git tree. The mapping and count files in the same
directory are not committed. Until that is tidied upstream, treat the table above as the answer
rather than the .gitignore.
Search all 246 positions, and open any one of them to see the witnesses recorded against it — the work, the locator and the edition, exactly as this file holds them.