DuaVault

A calm, mobile-first library for the Islamic content you screenshot — duas, adhkar, verses, hadith and reminders — so you actually come back to it.

Save it → Understand it → Remember it → Practice it.

• Screenshots are read on your device with Tesseract.js (Arabic + English). No paid AI, no API key, no cloud LLM.
• Content is classified by transparent, rule-based logic you can always correct before saving.
• Arabic is checked against a trusted Quran dataset (Tanzil) and any vetted hadith/dua datasets you import. Nothing is marked verified without a dataset match, and DuaVault never invents references, grades, translations or transliterations.
• Time-of-day reminders: a morning dua reminds you in the morning, evening adhkar in the evening, before-sleep duas at night — on Home, as a notification while the app is open, and via “Add to calendar” for reliable phone alerts.
• A daily dua from your own vault, spaced-repetition memorization, collections, situational search (“I'm feeling overwhelmed”), and a private dua journal.
• Works fully offline-first in on-device mode (IndexedDB) or with Supabase (auth, Postgres + RLS, private storage).

---

Quick start (on-device mode — no accounts)

pnpm install
pnpm fetch:quran      # one-time: downloads the Tanzil Quran text + translation into public/data (gitignored)
pnpm dev              # http://localhost:3000

Skipping fetch:quran is fine — the app works, but Quran verification is disabled and items show as unverified.

The first OCR run downloads the Tesseract engine and Arabic/English language data (a few MB) from jsDelivr. Your images never leave the browser.

Scripts

Command	What it does
pnpm dev / build / start	Next.js dev server / production build / serve
pnpm test	Vitest unit tests for the core logic
pnpm e2e	Playwright end-to-end tests (desktop + mobile; one real-OCR test)
pnpm test:db	Applies the Supabase migrations to a throwaway local Postgres and runs an RLS smoke test (no Docker)
pnpm lint / typecheck	ESLint / tsc --noEmit
pnpm fetch:quran [--translation=en.sahih|none] [--fixture]	Download Quran dataset (and refresh the test fixture)
pnpm import:references <file.json> [--supabase]	Import a vetted hadith/dua/dhikr dataset
pnpm generate:categories	Regenerate the categories migration from src/core/taxonomy.ts

Demo video

demo/ contains a scripted demo film: reels feed → screenshot → saving it in DuaVault → app tour → a morning reminder on a train.

pnpm build && pnpm start -p 3100                         # production build (no dev overlay)
DEMO_APP_URL=http://localhost:3100 pnpm demo:record      # → demo/out/duavault-demo.webm (~100 s, 1080p)
pnpm demo:record --stills                                 # quick key-frame preview
node demo/record.mjs --encode-only                        # re-encode saved frames
pnpm demo:mp4                                             # → demo/out/duavault-demo.mp4 (H.264, plays in QuickTime/VS Code)

The reels feed and the train carriage are illustrations (the feed is deliberately unbranded). Everything shown inside the phone during the save and tour is the real app — real OCR, verification and storage. The dua (Quran 20:25–28) is taken verbatim from the Tanzil dataset. The WebM is encoded with the ffmpeg build bundled with Playwright; the MP4 uses the H.264 encoder in your installed Google Chrome (WebCodecs). No extra installs needed.

Architecture

src/
  core/        Pure TypeScript domain logic — no React, Next or DOM (reusable by a future Expo app)
    types.ts, taxonomy.ts           domain model + category tree
    text/                           Arabic/English normalization (matching keys only), OCR cleanup, segmentation
    classify/                       ClassifierStrategy interface, RuleBasedClassifier, CompositeClassifier, topic lexicon
    verify/                         reference parser, shingle index, QuranMatcher, ReferenceEntryMatcher, verifyContent
    dedupe/, schedule/, search/     duplicate detection, SM-2-style SRS + daily pick, situational search
    pipeline/                       OCR → clean → segment → verify → classify → dedupe → drafts
    data/repository.ts              Repository interface (storage-agnostic)
  lib/
    ocr/                            TesseractOcrEngine (two-pass) + canvas preprocessing
    data/                           IndexedDbRepository, SupabaseRepository, live-query hooks
    references/                     loads datasets from /public/data lazily
    supabase/                       browser/server clients
  components/                       UI (shadcn/ui customised), views/ = one client view per screen
  app/                              routes; each page is a thin server file rendering a client view
  proxy.ts                          Supabase session refresh + auth redirect (supabase mode only)
supabase/migrations                 schema, RLS, storage policies, FTS function, categories
scripts/                            fetch-quran, import-references, generate-categories, test-db.sh
tests/unit, tests/e2e               Vitest, Playwright

Each engine is behind an interface and independently replaceable:

Concern	Interface	Shipped implementation
OCR	OcrEngine	TesseractOcrEngine
Classification	ClassifierStrategy	RuleBasedClassifier inside CompositeClassifier (add a local model as another strategy)
Optional off-device model	ExternalClassifierAdapter	none — contract only; must be opt-in and show what is sent
References	ReferenceProvider	StaticJsonReferenceProvider
Storage	Repository	IndexedDbRepository, SupabaseRepository

This is the beginning of the README. Read the rest at the original. Read the full README ↗