validator/
│
├── 📄 server.py                  FastMCP 2.0 server (port 3001)
├── 📄 validator_mcp.py           Main routing: auto single ↔ multi-verse
├── 📄 normalizer.py              Arabic normalizer pipeline (7 steps)
├── 📄 quran_db.py                O(1) indexed DB (gid / sura / juz / page)
├── 📄 quran_search.py            4-layer verse search engine
├── 📄 multi_verse.py             Forward alignment for multi-verse recitation
├── 📄 tashkeel.py                Per-word harakat validation
│
├── 📂 data/
│   ├── quran.json                6,236 verses — gid, uthmani, standard, standard_full, ...  (5.1 MB)
│   ├── uthmani_standard_map.json 2,017 Uthmani→standard word pairs, corpus-derived  (70 KB) ★
│   ├── word-map.json             Arabic word → root + morphological forms  (877 KB)
│   └── morphology.json           Root index + verb/noun patterns  (2.5 MB)
│
├── 📂 tests/
│   ├── test_all.py               124 tests across 12 categories — 123/124 pass (99.2%)
│   ├── dataset_gen.py            Auto-generates 63 test cases from quran.json
│   └── dataset.json              Generated test cases (gitignored)
│
├── 🖼️  architecture.svg           System architecture diagram (this file)
├── 📄  README.md                  This file
├── 📄  Dockerfile
└── 📄  .env.example

Input Text
    ↓
[Mode Detection] → single (≤8 words) or multi (>8 words)
    ↓
[Normalizer] — 7 steps:
    ① NFC unicode
    ② Word-level map (2017 Uthmani→standard pairs) ← NEW v2.2
    ③ Remove tashkeel / Quranic marks
    ④ U+0670 contextual fallback (ٰ → ا unless ى/ذ/ه/ل)
    ⑤ Alef variants → ا   Hamza variants → ء
    ⑥ word-initial ءا → ا   ى → ي
    ⑦ Remove non-Arabic, collapse whitespace
    ↓
[Search / Alignment]
    Single: 4-layer search (exact AND → linguistic → relaxed → fuzzy)
    Multi:  detect start verse → word-by-word boundary scan → forward align
    ↓
[Word Diff] — SequenceMatcher opcodes → substitutions / deletions / insertions → WER
    ↓
[Tashkeel Check] — if user provided harakat: per-word harakat comparison
    ↓
JSON Result: {is_correct, verse_key, wer, corrections, tashkeel_errors, feedback, ...}

# uthmani_standard_map.json — built by aligning all 6,236 verses
{
  "الرحمٰن":  "الرحمن",    # ← Bismillah fix (was "الرحمان" in v2.1)
  "الكتٰب":   "الكتاب",
  "الخٰسرون": "الخاسرون",
  "أولٰئك":   "أولئك",
  "ذٰلك":     "ذلك",
  "هٰذا":     "هذا",
  "علىٰ":     "على",
  ...  # 2,017 total entries
}

uv run python server.py
# Port 3001 / SSE endpoint at /sse

cd servers/validator
python3 tests/dataset_gen.py   # regenerate 63 test cases
python3 tests/test_all.py      # run all 124 tests

{ "text": "بسم الله الرحمن الرحيم" }

{
  "mode": "single",
  "is_correct": true,
  "verse_key": "1:1",
  "surah_name": "الفاتحة",
  "wer": 0.0,
  "corrections": [],
  "matched_verse": "بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِیمِ",
  "feedback": "ممتاز! تلاوتك صحيحة تماماً.",
  "has_tashkeel": false
}

{
  "mode": "multi",
  "is_correct": true,
  "total_verses": 7,
  "correct_verses": 7,
  "total_wer": 0.0,
  "verses": [ {"verse_key":"1:1","is_correct":true,"wer":0.0}, ... ],
  "range": "من الفاتحة (1:1) إلى (1:7)"
}