# Project export: NoorPath This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: NoorPath is a local-first Quran study app with reading, tafsir, vocab, Hifz, and progress tools—plus source-backed AI answers grounded in retrieved tafsir. - Devpost: https://devpost.com/software/noorpath - GitHub: https://github.com/M-Mahad-Amir/OpenAI__build-week - Demo: https://open-ai-build-week-five.vercel.app/ - Video: https://www.youtube.com/embed/eG9xYv4ZbpY?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 3 GitHub contributor(s) — M-Mahad-Amir (29 commits), Faaiq Ahmed (5 commits), syedmuhammadareeb2007-cyber (1 commits) ## Devpost submission (written by the team) ### Inspiration Quran learning often requires moving between separate tools for reading, tafsir, memorisation, vocabulary, and personal consistency. We wanted to create one calm, focused learning space that helps learners return to the Quran every day without making AI the source of truth. ### What it does NoorPath is a browser-based Quran learning prototype built around a local Quran corpus. Users can: Read the Quran by Surah, Ayah, or global ruku. Switch between English and Urdu translations. View local ayah-level tafsir and word-by-word Arabic vocabulary. Practise Hifz with pause-mark-aware continuation questions. Study a ruku through grouped tafsir lessons and vocabulary quizzes. Track daily habits including salah, reading, Hifz, lessons, vocabulary, charity, and social-media time. Optional AI features can create a short ruku overview, a five-question quiz, and a lesson Q&A response. These features are supplementary: they are grounded in the selected local tafsir context and never replace canonical Quran text or verified tafsir. ### How we built it NoorPath is a static web application built with vanilla JavaScript, HTML, and CSS. The Quran corpus, translations, metadata, tafsir, and vocabulary are stored locally as JSON. We separated data access into focused services: the Quran service handles Surah and ruku lookup, while tafsir and vocabulary services lazy-load and cache data for the active Surah. Browser localStorage keeps progress private to the learner’s device. The interface uses a lightweight state-driven renderer, delegated events, responsive styling, and RTL-aware Arabic presentation. Optional Gemini requests are isolated in their own service and receive only the selected study context. ### Challenges we ran into The main challenge was balancing useful AI assistance with the sensitivity of Quranic study. We kept canonical Quran data and generated content separate, restricted AI context to the selected local tafsir excerpts, and made AI optional. We also worked through Arabic-specific UI details: right-to-left layout, word display, and splitting Hifz practice at meaningful pause marks without breaking a word. Finally, we designed the app to remain useful even when optional AI or supporting local files are unavailable. ### What we learned We learned that trustworthy learning tools need clear source boundaries, not only polished AI features. Local-first data, narrow AI context, graceful fallbacks, and simple service boundaries made NoorPath easier to reason about and safer to extend. We also learned how much product quality depends on small interaction details: progress should be private and reliable, Arabic should render naturally, and memorisation feedback should encourage learners to continue after a wrong answer. ### What's next Next, we would add scholar-reviewed and fully attributed source material, a secure backend for cross-device progress, authentication, citations for generated responses, and a production-safe server-side AI integration. ## README (from the GitHub repository) # NoorPath NoorPath is a vanilla-JavaScript Quran study app. Quran reading, tafsir display, vocabulary, Hifz practice, and progress tracking are local-first browser features. Optional AI study features use a Vercel serverless RAG endpoint backed by Qdrant. ## Run locally Install the Node dependencies first: ```bash npm install ``` For local reading-only work, serve the repository with a static server: ```bash python -m http.server 8000 ``` For the AI study features, use Vercel's local runtime so `/api/ask` is available: ```bash npx vercel dev ``` Do not open `index.html` directly: the app fetches its local data files. ## Features - Read the full Quran by Surah, Ayah, or any of the 556 global rukus, with Arabic plus English or Urdu translation. - View local ayah-level tafsir and word-by-word Arabic vocabulary. - Practise Hifz through pause-mark-aware continuation questions. - Study a ruku through grouped local tafsir, RAG-grounded summaries and quizzes, and source-backed Q&A. - Explore Arabic vocabulary by ruku, surah, or starting letter, including a ruku vocabulary quiz. - Track a private daily journey: salah, wellbeing, reading, Hifz, lesson, vocabulary, charity, and social-media habits. Progress, streaks, and points remain in browser `localStorage`. ## RAG architecture 1. `scripts/ingest.js` reads every `data/tafsir/.json` file and groups adjacent ayahs with exactly identical tafsir text into one chunk. 2. Each chunk stores a stable readable ID, surah, ayah range, Arabic ayahs, English translations, and tafsir. Its tafsir is embedded with `sentence-transformers/all-MiniLM-L6-v2` (384 dimensions). 3. The vectors and payloads are upserted to Qdrant collection `noorpath_tafsir` using cosine distance. The ingestion script also creates the integer payload index on `surah`, which scoped ruku retrieval requires. 4. `api/ask.js` embeds a question with the same model, retrieves the five most relevant chunks, builds Gemini context from ayah text and tafsir, and returns an answer with source references. 5. `src/ragService.js` is the browser boundary for the endpoint. `askRag(question)` posts `{ question }` to `/api/ask` and returns `{ answer, sources }`; the lesson summary and quiz helpers use the same endpoint internally. Run the tafsir ingestion after configuring the environment variables below: ```bash npm run ingest:tafsir ``` The current corpus produces 1,896 grouped tafsir chunks. Rerunning ingestion is safe: deterministic point IDs update the existing Qdrant points. ## Data and AI boundaries - Canonical Quran text, translations, metadata, ruku navigation, Hifz prompts, tafsir display, vocabulary, and progress are local features; they do not rely on AI. - The bundled corpus contains 114 surahs, 6,236 ayahs, and 556 rukus. Tafsir and word data are lazy-loaded per surah; the word index supports full-Quran letter browsing. - AI output is supplementary study material, grounded in retrieved tafsir chunks, and is not a replacement for verified tafsir or primary scholarly sources. - Generated material remains separate from canonical Quran records. ## Project structure | Area | Responsibility | | --- | --- | | `index.html` | Static app shell, navigation, fonts, and stylesheets. | | `src/app.js` | Client-side state, rendering, event handling, study flows, and local progress. | | `src/quranService.js` | Canonical Quran corpus access, Surah/ruku lookup, and study-context construction. | | `src/ragService.js` | Browser client for `/api/ask`; exposes RAG Q&A plus lesson summary and quiz helpers. | | `api/ask.js` | Vercel serverless RAG endpoint: Hugging Face embeddings, Qdrant retrieval, and Gemini generation. | | `src/tafsirService.js` / `src/vocabularyService.js` | Cached, lazy-loaded per-surah tafsir and word-by-word vocabulary. | | `src/wordIndexService.js` | Cached full-Quran word index used by Arabic letter browsing. | | `scripts/ingest.js` | Builds grouped tafsir chunks, embeddings, Qdrant points, and the `surah` payload index. | | `data/` | Local Quran corpus, schema, tafsir, vocabulary, and word-index files. | | `docs/` | Development history and project documentation. | ## Practices and methodology - **Local-first:** the core Quran study experience remains usable without AI services. - **Service boundaries:** the UI uses focused corpus, tafsir, vocabulary, and RAG services rather than accessing data or credentials directly. - **Grounded generation:** server-side prompts receive retrieved ayah text and tafsir only; returned source ranges are displayed under lesson answers. - **Secret isolation:** Hugging Face, Qdrant, and Gemini credentials stay in environment variables on the server. - **Simple frontend:** vanilla ES modules, a single state-driven renderer, delegated events, guarded `localStorage`, and responsive/RTL styling keep the client lightweight. ## Team contributions - **M. Mahad Amir** — led the app’s design and implementation, including the static architecture, normalized Quran corpus, service layer, ruku navigation, Hifz, Arabic vocabulary, lessons, journey tracking, UI refinements, and documentation. - **Syed Muhammad Areeb** — integrated the initial dynamic Gemini reading, quiz, and chat features; later refactored the reading/vocabulary views and helped remove the exposed API key. - **Faaiq Ahmed** — led the local data-layer work, including tafsir and word-vocabulary additions, ruku-navigation and vocabulary enhancements. Contributions above reflect the repository’s Git history. ## Detected evidence (automated analysis) Indexed codebase: 16 recognized source files, 133 KB. - CSS (language) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - Google Gemini (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (120 of 250) ``` .gitignore api/ask.js data/arabic_words_index.json data/arabic_words/1.json data/arabic_words/10.json data/arabic_words/100.json data/arabic_words/101.json data/arabic_words/102.json data/arabic_words/103.json data/arabic_words/104.json data/arabic_words/105.json data/arabic_words/106.json data/arabic_words/107.json data/arabic_words/108.json data/arabic_words/109.json data/arabic_words/11.json data/arabic_words/110.json data/arabic_words/111.json data/arabic_words/112.json data/arabic_words/113.json data/arabic_words/114.json data/arabic_words/12.json data/arabic_words/13.json data/arabic_words/14.json data/arabic_words/15.json data/arabic_words/16.json data/arabic_words/17.json data/arabic_words/18.json data/arabic_words/19.json data/arabic_words/2.json data/arabic_words/20.json data/arabic_words/21.json data/arabic_words/22.json data/arabic_words/23.json data/arabic_words/24.json data/arabic_words/25.json data/arabic_words/26.json data/arabic_words/27.json data/arabic_words/28.json data/arabic_words/29.json data/arabic_words/3.json data/arabic_words/30.json data/arabic_words/31.json data/arabic_words/32.json data/arabic_words/33.json data/arabic_words/34.json data/arabic_words/35.json data/arabic_words/36.json data/arabic_words/37.json data/arabic_words/38.json data/arabic_words/39.json data/arabic_words/4.json data/arabic_words/40.json data/arabic_words/41.json data/arabic_words/42.json data/arabic_words/43.json data/arabic_words/44.json data/arabic_words/45.json data/arabic_words/46.json data/arabic_words/47.json data/arabic_words/48.json data/arabic_words/49.json data/arabic_words/5.json data/arabic_words/50.json data/arabic_words/51.json data/arabic_words/52.json data/arabic_words/53.json data/arabic_words/54.json data/arabic_words/55.json data/arabic_words/56.json data/arabic_words/57.json data/arabic_words/58.json data/arabic_words/59.json data/arabic_words/6.json data/arabic_words/60.json data/arabic_words/61.json data/arabic_words/62.json data/arabic_words/63.json data/arabic_words/64.json data/arabic_words/65.json data/arabic_words/66.json data/arabic_words/67.json data/arabic_words/68.json data/arabic_words/69.json data/arabic_words/7.json data/arabic_words/70.json data/arabic_words/71.json data/arabic_words/72.json data/arabic_words/73.json data/arabic_words/74.json data/arabic_words/75.json data/arabic_words/76.json data/arabic_words/77.json data/arabic_words/78.json data/arabic_words/79.json data/arabic_words/8.json data/arabic_words/80.json data/arabic_words/81.json data/arabic_words/82.json data/arabic_words/83.json data/arabic_words/84.json data/arabic_words/85.json data/arabic_words/86.json data/arabic_words/87.json data/arabic_words/88.json data/arabic_words/89.json data/arabic_words/9.json data/arabic_words/90.json data/arabic_words/91.json data/arabic_words/92.json data/arabic_words/93.json data/arabic_words/94.json data/arabic_words/95.json data/arabic_words/96.json data/arabic_words/97.json data/arabic_words/98.json data/arabic_words/99.json data/quran-normalized.schema.json data/quran.json data/tafsir/1.json [130 more files omitted for size] ``` ### Dependencies - package.json: @qdrant/js-client-rest@^1.15.0, dotenv@^16.6.1 ### Recent commits (newest first) - Updated - Refactor Gemini service to use API for AI requests, update Quran service context, and add RAG functionality - Updated - Updated - feat: implement auto-tracking for ayahs read today and update progress state - updated - enhance waqf segmentation logic for Arabic text processing - Updated - fix tafsir toggle in read quran tab - feat: enhance Arabic vocabulary features with new quiz mode and navigation options - Refactor: remove API key and fix reading/vocab views - . - implement ruku navigation and vocabulary features, update gemini service prompts - feat: add global ruku lookup and word index generation - Loading more & refining existing data layer - . - Adding tafsir and arabic word data - added development log implementation and update details. - Updated Readme - Refactor Quran data handling and integrate new schema ## Key source files (fetched from GitHub, selected and truncated for size) ### docs/DEVELOPMENT_LOG.md ```markdown # NoorPath development log ## Purpose and update rule This is the repository's factual implementation reference. Add an entry after an implementation is completed and verified. Each later entry should identify the date, commit (when one exists), files changed, what now works, technical decisions or data boundaries, and verification performed. Do not record proposed work as if it were implemented. ## Baseline recorded - Recorded: 2026-07-19 - Repository baseline: `0758a309ac895cb66fd1b72c057f902c493b1f9c` (`Updated Readme`) - Working tree at review: clean before this log was added - Available conversation record: no earlier chat transcripts were present in this repository or available workspace context. This entry is therefore based on the checked-in files, Git history, `Initial Prompt.txt`, and `Project Tentative Overview (summarized).txt`. ## Implemented application NoorPath is a browser-based Quran-learning prototype. It has no build system, package manifest, backend, or test suite in the current tree. Serve the repository with a static HTTP server; opening `index.html` directly does not work because the corpus is loaded with `fetch`. ### Runtime layout | Area | Implemented responsibility | | --- | --- | | `index.html` | Defines the shell, sidebar navigation, top bar, app mount point, toast template, font loading, module import map for Gemini, and static asset links. | | `src/app.js` | Client-side state, rendering, event handling, study flows, local progress, notification attempt, and optional Gemini UI actions. | | `src/quranService.js` | Sole client-side access layer for the local Quran corpus; it fetches/caches the data, resolves a surah, maps a selected ruku to UI data, matches the local vocabulary, and creates the bounded AI context. | | `src/data.js` | Nine-term reviewed local Arabic glossary used as an optional word-level gloss layer. | | `src/geminiService.js` | Optional Gemini calls for summaries, contextual explanations, quizzes, and selected-ruku Q&A. The configured API key is empty. | | `src/styles.css` | Responsive visual system for the desktop sidebar/mobile layout, reading cards, study activities, forms, calendar, and feedback states. | ### Local corpus and schema - `data/quran.json` is the canonical local reading corpus used by the app. It is 8,687,103 bytes, has SHA-256 `195B31C5B2CFE1604B078F391DCB7A7AED90A253B661376ED32F8818F45F1C49`, and contains schema version `1.0.0`, 114 surahs, 6,236 ayahs, 556 rukus, and 15 marked sajdahs. - Its source manifest identifies `The Quran Dataset.csv` for Quran text and English translation and `Urdu.csv` for Urdu translation. The imported-at value is currently empty. - `data/quran-normalized.schema.json` specifies the data contract: source attribution, ordered surahs, stable `surah:ayah` IDs, Arabic/English/Urdu text, ruku/juz/manzil/hizb-quarter metadata, sajdah metadata, and tokenized Arabic words. It explicitly keeps generated tafsir, lessons, and quizzes out of canonical ayah re [truncated — 21721 more characters] ``` ### package.json ``` { "name": "noorpath-tafsir-ingest", "private": true, "type": "module", "scripts": { "ingest:tafsir": "node scripts/ingest.js" }, "dependencies": { "@qdrant/js-client-rest": "^1.15.0", "dotenv": "^16.6.1" } } ``` ### index.html ```html NoorPath | Quran learning

QURAN · SAMPLE LIBRARY

Read with presence

✦0points
``` ### src/overrides.css ```css .word-list { direction: rtl; justify-content: flex-start; } .word { direction: rtl; } .word b { margin-right: 0; margin-left: 4px; } ``` ### src/wordIndexService.js ```javascript // Loads the full-Quran deduplicated word index once, caches it. // Schema: [{ar, tr, s, n}] (s = surahId, n = ayahNumber of first occurrence) let indexPromise = null; export async function getWordIndex() { if (!indexPromise) { const url = new URL("../data/arabic_words_index.json", import.meta.url); indexPromise = fetch(url, { cache: "force-cache" }) .then(r => { if (!r.ok) throw new Error(`Full-Quran word index could not be loaded (${r.status}).`); return r.json(); }) .catch(e => { indexPromise = null; throw e; }); } return indexPromise; } ``` ### src/tafsirService.js ```javascript // Lazy-loads per-surah tafsir from data/tafsir/.json. // Schema: { "": { ruku: , tafsir: "" }, ... } const cache = new Map(); async function loadSurahTafsir(surahId) { if (cache.has(surahId)) return cache.get(surahId); const url = new URL(`../data/tafsir/${surahId}.json`, import.meta.url); const promise = fetch(url, { cache: "force-cache" }) .then(response => { if (!response.ok) throw new Error(`Tafsir for surah ${surahId} could not be loaded (${response.status}).`); return response.json(); }) .catch(error => { cache.delete(surahId); throw error; }); cache.set(surahId, promise); return promise; } export async function getSurahTafsir(surahId) { return loadSurahTafsir(surahId); } ``` ### src/vocabularyService.js ```javascript // Lazy-loads per-surah word-by-word data from data/arabic_words/.json. // Schema: { "": [{ position, arabic, translation }, ...], ... } const cache = new Map(); async function loadSurahWords(surahId) { if (cache.has(surahId)) return cache.get(surahId); const url = new URL(`../data/arabic_words/${surahId}.json`, import.meta.url); const promise = fetch(url, { cache: "force-cache" }) .then(response => { if (!response.ok) throw new Error(`Arabic words for surah ${surahId} could not be loaded (${response.status}).`); return response.json(); }) .catch(error => { cache.delete(surahId); throw error; }); cache.set(surahId, promise); return promise; } export async function getSurahWords(surahId) { return loadSurahWords(surahId); } ``` ### src/ragService.js ```javascript async function postAsk(question, options) { const response = await fetch("/api/ask", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(options ? { question, ...options } : { question }) }); const body = await response.json().catch(() => ({})); if (!response.ok) throw new Error(body.error || "The AI study service is unavailable."); return { answer: body.answer, sources: body.sources || [] }; } // Public RAG Q&A contract: POST { question } and return { answer, sources }. export function askRag(question) { return postAsk(question); } function scopeFor(context) { return { surahId: context.surahId, ayahs: context.verses.map(verse => verse.ayah) }; } export async function generateRagSummary(context) { const { answer, sources } = await postAsk( `Summarize the key themes of ${context.surah}, ruku ${context.ruku}.`, { mode: "summary", scope: scopeFor(context) } ); return { ...answer, sources }; } export async function generateRagQuiz(context) { const { answer } = await postAsk( `Create a quiz for ${context.surah}, ruku ${context.ruku}.`, { mode: "quiz", scope: scopeFor(context) } ); return answer; } ``` ### src/geminiService.js ```javascript // AI credentials live only in /api/ask. This browser service only calls it. async function askApi(mode, question, context) { const response = await fetch("/api/ask", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ mode, question, scope: { surahId: context.surahId, ayahs: context.verses.map(verse => verse.ayah) } }) }); const body = await response.json().catch(() => ({})); if (!response.ok) throw new Error(body.error || "The AI study service is unavailable."); return body; } export async function generateStudySummary(context) { const response = await askApi( "summary", `Summarize the key themes of ${context.surah}, ruku ${context.ruku}.`, context ); return { ...response.answer, sources: response.sources }; } export async function generateDynamicQuiz(context) { const response = await askApi( "quiz", `Create a quiz for ${context.surah}, ruku ${context.ruku}.`, context ); return response.answer; } export async function askGeminiAboutLesson(question, context) { const response = await askApi("question", question, context); return { answer: response.answer, sources: response.sources }; } ``` ### src/data.js ```javascript // DEPRECATED — no longer imported. Word-by-word glosses are now sourced from // data/arabic_words/.json via src/vocabularyService.js. // Retained for reference only; safe to delete in a future cleanup pass. export const LOCAL_VOCABULARY = [ { forms: ["الله"], ar: "اللَّه", translit: "Allah", meaning: "God", frequency: "Core Quran word" }, { forms: ["رب"], ar: "رَبّ", translit: "Rabb", meaning: "Lord / Sustainer", frequency: "Core Quran word" }, { forms: ["الرحمن", "رحمن"], ar: "رَحْمَٰن", translit: "Ar-Rahman", meaning: "The Most Compassionate", frequency: "Core Quran word" }, { forms: ["الرحيم", "رحيم"], ar: "رَحِيم", translit: "Ar-Rahim", meaning: "The Most Merciful", frequency: "Core Quran word" }, { forms: ["نعبد", "عبد"], ar: "عَبَدَ", translit: "ʿAbada", meaning: "to worship", frequency: "Core Quran word" }, { forms: ["اهدي", "هدى"], ar: "هُدًى", translit: "Huda", meaning: "guidance", frequency: "Core Quran word" }, { forms: ["يوم"], ar: "يَوْم", translit: "Yawm", meaning: "day", frequency: "Core Quran word" }, { forms: ["الصراط", "صراط"], ar: "صِرَاط", translit: "Sirat", meaning: "path", frequency: "Core Quran word" }, { forms: ["الدين", "دين"], ar: "دِين", translit: "Din", meaning: "judgment / way of life", frequency: "Core Quran word" } ]; ``` [5 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]