DivinityAI – Islamic Grounded RAG: Architecture & Performance Benchmark
- DivinityAI locks all responses to authenticated Quran and Hadith sources, eliminating hallucination risks.
- A five‑path Intent Router classifies queries (Quran, Hadith, Fiqh, Calculation, Off‑Domain) and applies confidence gating.
- Hybrid search combines BM25 sparse matching with BGE‑M3 dense embeddings, enhanced by HyDE and sub‑query decomposition.
- Deterministic 4‑tier citation verification (exact match → normalized → Levenshtein → semantic) ensures source authenticity.
- Built on Django ASGI/DRF, React 19/Vite, ChromaDB, and local Ollama/Groq LLMs for high‑performance, zero‑hallucination Islamic RAG.
Islamic scholarship demands absolute textual fidelity. General‑purpose LLMs often fabricate Quranic verses, misattribute Hadiths, or generate speculative fatwas, risking doctrinal errors. DivinityAI solves this by implementing a strict “corpus‑lock” policy: every response must be verifiable against a curated, authenticated database of the King Fahd Uthmani Quran and six canonical Hadith collections. This article dissects the system’s architectural blueprint, technical stack, data flows, and performance benchmarks, illustrating how DivinityAI achieves deterministic citation verification and zero‑hallucination retrieval‑augmented generation.
The Engineering Challenge: Why DivinityAI – Islamic Grounded RAG Was Architected
Traditional RAG systems retrieve information from open‑domain corpora, leaving room for hallucination when sources are incomplete or ambiguous. In Islamic contexts, even a minor textual deviation can have profound theological implications. DivinityAI was conceived to eliminate this risk through:
- Locked Corpus: Only authentic Quran and Hadith texts are indexed, ensuring every retrieved snippet originates from trusted sources.
- Intent Classification: A five‑path router (Quran verse, Hadith, Fiqh, Calculation, Off‑Domain) directs queries to specialized retrieval pipelines.
- Multi‑Layer Verification: Pre‑generation evidence checks, post‑generation hallucination detectors, and a deterministic 4‑tier citation validation chain guarantee source authenticity.
The result is an AI system that can safely answer scholarly and academic queries while refusing off‑domain or unverifiable requests.
Core Architecture & Technical Stack Deep‑Dive
System Overview & Interface Boundaries
DivinityAI follows a modular, microservice‑friendly design. The React 19/Vite frontend communicates via POST /api/v1/query to a Django DRF backend, which orchestrates retrieval, verification, and generation steps.
React 19 / Vite ──► Django ASGI / DRF ──►
├─ ChromaDB (port 8040) – vector stores (quran_collection, hadith_collection)
├─ rank_bm25 (local disk) – sparse BM25 index for Arabic text
└─ Ollama (port 11434) – local embedding models (Gemma, BGE‑M3)
└─ OpenRouter / Groq – LLMs (Gemini 2.5 Flash, Llama 3.3 70B)
Frontend Architecture
- React 19 with Vite for rapid development and optimized builds.
- Tailwind CSS v4 for responsive, RTL‑aware styling.
- Specialized Arabic typography: Uthmani script rendering, bidirectional text support.
- Source citation popovers for inline references (`[Q surah:ayah]`, `[C collection/number]`).
Backend Architecture
- Django ASGI server with DRF endpoints, custom middleware for query auditing and logging.
- Intent Router middleware classifies incoming queries using confidence scoring.
- Scope Guard blocks off‑domain requests early.
- Query Rewriting pipeline normalizes input for optimal retrieval.
Retrieval Layer
- Hybrid Search: BM25 sparse matching on normalized Arabic text combined with BGE‑M3 dense embeddings stored in ChromaDB.
- HyDE Expansion: Hypothetical Document Embeddings generate richer query representations, especially for jurisprudential (Fiqh) queries.
- Sub‑Query Decomposition: Complex multi‑part queries are broken down into atomic retrieval tasks.
- Reciprocal Rank Fusion (RRF): Merges sparse and dense results, boosting overall precision.
Verification & Generation Layer
- Pre‑Generation Evidence Sufficiency: Checks that retrieved sources cover the user’s intent before invoking an LLM.
- 4‑Tier Citation Verification:
- Exact match against source text.
- Normalized match (Arabic diacritics, ligatures).
- Levenshtein distance tolerance.
- Semantic similarity verification.
- Post‑Generation Fatwa Boundary / Hallucination Detectors: LLM responses are cross‑checked against verified citations.
Key Features Breakdown & Practical Benefits
Strict Corpus‑Lock Policy
Every answer must be traceable to the King Fahd Uthmani Quran or the six canonical Hadith books. If a claim cannot be verified, the system refuses to respond, protecting users from misinformation.
Five‑Path Intent Router with Confidence Gating
| Path | Purpose | Confidence Threshold |
|---|---|---|
| Quran verse | Direct Quran retrieval and citation. | ≥ 0.85 |
| Hadith | Access to authenticated prophetic narrations. | ≥ 0.80 |
| Fiqh | Cross‑source jurisprudential analysis. | ≥ 0.75 |
| Calculation | Mathematical operations (e.g., prayer times, lunar calendar). | N/A (deterministic) |
| Off‑Domain | Non‑Islamic queries are rejected. | ≤ 0.60 |
Hybrid Search & HyDE
BM25 captures lexical nuances in Arabic morphology, while BGE‑M3 provides semantic depth. HyDE enriches queries by generating hypothetical documents, improving recall for abstract Fiqh questions.
Deterministic Citation Verification
The 4‑tier chain ensures that citations are not just close matches but exact, normalized, or semantically equivalent to authentic sources. This eliminates false positives and maintains scholarly rigor.
Real‑World Deployment & Production Topology
DivinityAI is deployed as a self‑hosted solution, with ChromaDB and Ollama running locally for data privacy