Quranic Linguistics Observatory

Interactive exploration of Quranic linguistic structure, morphology, search, and study workflows.

Live Demo | Report Bug | Request Feature

---

Quranic Linguistics Observatory is a Next.js application for exploring the Quran through normalized corpus data, D3-based visualizations, search tools, study workflows, and authenticated progress tracking. The app is built around four main product surfaces:

• Explore: interactive visualizations and inspectors
• Search: dedicated search workspace with recovery-friendly states
• Study: tracked roots, notes, migration, and resume flows
• Quiz: experimental daily and adaptive review quizzes backed by local progress and optional Supabase sync

Key Capabilities

Visual exploration

Radial Surah Map — verse structure with root connections	Corpus Architecture — global structure across all 114 surahs
Root Network — shared roots as a force-directed graph	Knowledge Graph — entities and their relations
Surah Distribution — Makki/Madani split and root frequency	Root Flow Sankey — how roots flow across surahs
Arc Flow — linear ayah sequence with connecting arcs	Ayah Dependency Graph — syntactic dependencies within an ayah

• Radial Surah Map, Root Network, Collocation Network, Knowledge Graph, Surah Distribution, Arc Flow, Ayah Dependency Graph, Root Flow Sankey, and Corpus Architecture views
• Shared inspectors, breadcrumbs, explainer content, export options, and embed support
• Shell-ready and deep-data-ready loading states so the app remains usable before the full corpus finishes loading

Search and analysis

• Fast global search across Arabic text, roots, lemmas, glosses, and translations
• Dedicated Search workspace with grouped results, explicit fallback messaging, and recovery paths
• Morphological filters by root, lemma, part of speech, and ayah
• Semantic and collocation queries through Supabase/PostgreSQL functions
• Optional image-assisted root extraction and OCR-assisted utilities for search entry

Study and learning

• Tracked roots with learning and learned states, notes, import/export, and migration flows
• Auth-backed sync for tracked roots through Supabase Row Level Security
• Experimental quiz route with a daily puzzle, adaptive review sessions, local history, and per-user quiz_attempts sync
• Study hub and profile flows designed to complement exploration instead of replacing it

Product UX

• English, Arabic, and pseudo-localized message sets
• Responsive shell with desktop and mobile navigation patterns
• First-run mission chooser and contextual guidance for new users
• Theme, display, and export controls shared across the app shell
• Vercel Analytics instrumentation for readiness, recovery, performance, and core engagement events

Getting Started

Prerequisites

• Node.js 20+ recommended
• npm
• A Supabase project
• Supabase CLI for local migration workflows

Installation

1. Clone the repository.

   git clone https://github.com/lAvArt/Quran-corpus-visualizer.git
   cd Quran-corpus-visualizer

2. Install dependencies.

   npm install

3. Copy the environment template.

   cp .env.example .env.local

4. Fill in at minimum:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY

5. Apply the database migrations.

   supabase db push

   The current migration set is 001 through 007, including the quiz_attempts table used for synced quiz history.

6. Optional setup:

• Seed normalized corpus data:

  npm run db:seed

• Fetch the local morphology file for offline development:

  npm run fetch:morphology

• Generate embeddings if you are working on semantic search infrastructure:

  npx tsx scripts/generate-embeddings.ts

7. Start the development server.

   npm run dev

Common Commands

Command	Purpose
npm run dev	Start the local Next.js dev server
npm run lint	Run ESLint across app sources
npm run typecheck	Run TypeScript without emitting
npm test	Run Vitest
npm run test:e2e	Run Playwright end-to-end tests
npm run test:a11y-smoke	Run the accessibility smoke suite
npm run verify	Lint, typecheck, unit test, and build
npm run verify:release	Full release verification including Playwright suites
npm run i18n:check	Check translation coverage
npm run i18n:pseudo	Regenerate pseudo-localized messages
npm run docs:generate	Regenerate screenshot-backed docs assets

Tech Stack

• Next.js 16 App Router
• React 19
• TypeScript
• Supabase / PostgreSQL 17
• D3.js
• Framer Motion
• next-intl
• Vercel Analytics

Project Structure

app/                 App Router pages, metadata routes, API routes, and localized workspaces
components/
  auth/              Auth forms and flows
  onboarding/        First-run mission and onboarding UI
  quiz/              Quiz cards, daily puzzle, and review quiz surfaces
  search/            Search workspace and command/search UI
  shell/             Shared app shell, journey rail, and shell navigation
  study/             Study hub and related dashboard components
  ui/                Shared UI building blocks
  visualisations/    D3-based graph and visualization components
lib/
  analytics/         Product telemetry helpers
  cache/             IndexedDB-backed local persistence
  context/           Auth and knowledge providers
  corpus/            Corpus loading, readiness, and overview data
  quiz/              Quiz generation, progress, and personalization logic
  search/            Search parsing, indexes, ranking, and recovery helpers
  supabase/          Supabase clients, generated types, and data services
messages/            Translation files
public/              Static assets and bundled morphology source data
scripts/             Seed, docs, i18n, and data utility scripts
supabase/            SQL migrations and local Supabase metadata
docs/                Product, schema, roadmap, and release documentation

Architecture Notes

• Localized layouts own the shared shell, providers, metadata, and route-level workspaces.
• Supabase is the primary structured corpus and user-state backend; local caches keep the product resilient during cold starts and offline-ish flows.
• Search is split between fast client-side affordances and database-backed semantic or relational queries.
• Study state is hybrid: local persistence is available without auth, then migrates to Supabase when a user signs in.
• Quiz progress follows the same pattern: local history first, optional Supabase sync second.

Release Workflow

• Run npm run verify during normal development.
• Run npm run verify:release before a release candidate.
• Use docs/RELEASE_CHECKLIST.md for manual release checks.
• Use docs/OBSERVABILITY.md for telemetry review.
• Use docs/ROADMAP_STATUS.md for current delivery status.

Additional Documentation

• CONTRIBUTING.md
• DEPLOYMENT.md
• SECURITY.md
• docs/SCHEMA.md
• docs/DATA_SOURCES.md
• docs/EMBEDDING.md
• docs/ROADMAP.md

Attribution

This project uses source data and metadata derived from the Quranic Arabic Corpus and Quran.com APIs.

• Quranic Arabic Corpus: https://corpus.quran.com
• Source repository: https://github.com/kaisdukes/quranic-corpus
• Quran.com API docs: https://api-docs.quran.com

Please see docs/DATA_SOURCES.md for source handling and attribution details.

Security

Please report vulnerabilities according to SECURITY.md.

License

This project is licensed under the GNU General Public License v3.0. See LICENSE.