Mahfuz / محفوظ

A minimal, distraction-free Quran companion for the web.

mahfuz.ilg.az

Mahfuz is a Quran companion designed around simplicity. No clutter, no ads. Just the text and the tools you need to read, listen, learn, and memorize.

• Three reading modes. Line-by-line for focused reading, word-by-word with inline translation and transliteration, and a traditional Mushaf page with Karahisari-style illuminated borders.
• Two page layouts. Standard Medina Mushaf (604 pages) and Berkenar layout (600 pages, 20 per juz) — switchable in settings.
• Focus mode. Distraction-free reading with annotation canvas (pen, highlighter, text notes), gesture navigation, and wake lock.
• Audio playback. Verse or surah-level playback with real-time word highlighting, auto-continue to next surah, reciter selection, adjustable speed, and lock screen controls via MediaSession.
• Memorization. Five study modes — Learn (word-by-word), Listen (audio tracking), Test (fill-in-the-blank), Type (transliteration), and Immersive (fullscreen) — all powered by SM-2 spaced repetition with per-verse word accuracy tracking.
• Discover. Linguistic exploration with an Arabic root dictionary, 36 Quranic concepts across 8 categories, i'rab (syntax analysis) with interactive syntax trees, and word-by-word grammar popovers.
• Learn to Read. A 14-stage curriculum from letters to tajweed, with adaptive practice and Quranic word quests.
• Library. Unified hub for courses, learning tracks, and memorization in one place.
• 7 themes. Light, Crystal, Sepia, Teal, Dimmed, Dark, and Black — plus 4 reading presets (night, study, mushaf, default).
• Offline first. Three-layer caching with TanStack Query, Dexie IndexedDB, and Service Worker.
• Sync. Cross-device progress sync with LWW merge for preferences, union merge for bookmarks, and append-only for reviews and badges.
• Trilingual. Turkish, English, and Spanish interface with auto-detection.

git clone https://github.com/theilgaz/mahfuz.git
cd mahfuz/mahfuz-app
npx pnpm@9 install
cp apps/web/.env.example apps/web/.env
npx pnpm@9 dev

Dev server runs at http://localhost:3000.

mahfuz-app/
├── apps/
│   └── web/                      Main web application
│       ├── server.mjs            Node.js SSR server
│       ├── Dockerfile            Multi-stage Docker build
│       ├── drizzle/              Database migrations (5 files)
│       └── src/
│           ├── components/       UI components (141 files)
│           │   ├── audio/        AudioBar, AudioProvider, playlists
│           │   ├── browse/       Surah list, chapter cards, reading list
│           │   ├── discover/     Dictionary, concepts, i'rab, grammar
│           │   ├── focus/        Focus mode layout, annotations, gestures
│           │   ├── memorization/ 5 study modes, surah selector, results
│           │   ├── quran/        AyahText, VerseList, MushafPage, WBW
│           │   ├── settings/     7 extracted setting sections
│           │   └── ui/           Dialog, Popover, Skeleton, Loading...
│           ├── hooks/            Custom hooks, query and mutation hooks
│           ├── locales/          i18n strings (tr, en, es)
│           ├── lib/              Utilities, constants, store helpers
│           ├── routes/           File-based routes (37 files)
│           └── stores/           Zustand stores (18 focused stores)
├── packages/
│   ├── api/                      Quran.com API client with IndexedDB cache
│   ├── audio-engine/             Playback engine with word-level sync
│   ├── db/                       Dexie IndexedDB schemas and Drizzle ORM
│   ├── gamification/             Badge and achievement system
│   ├── memorization/             SM-2 spaced repetition algorithm
│   ├── sdk/                      Public SDK (planned)
│   └── shared/                   Types, constants, curriculum data
└── tooling/                      Shared ESLint, TypeScript, Tailwind configs

Quran API (api.quran.com)
    ↓
Service Worker (stale-while-revalidate)
    ↓
@mahfuz/api (IndexedDB cache, 30-day TTL)
    ↓
TanStack Query (in-memory, 24h gcTime)
    ↓
React Components (Zustand for UI state)
    ↓
Sync Engine (push/pull with LWW + union merge)
    ↓
Server DB (LibSQL via Drizzle ORM)

• Virtualized verse list. Only ~15 DOM nodes for a 286-verse surah via TanStack Virtual.
• Per-verse audio isolation. During playback, only the active verse re-renders.
• Consolidated Zustand selectors. Single useShallow subscription per component.
• React.memo on all verse, card, and translation components.
• Dynamic imports. Topic index, morphology data, and heavy assets lazy-loaded on demand.
• Service Worker caching. API responses served instantly from cache.

• Tanzil.net. Quran verse texts in Uthmani and Simple scripts. Licensed under Creative Commons BY 3.0.
• Quran.com API. Word-by-word data, transliteration, and Diyanet translation.
• Kuran Meali Ebook Oluşturucu by alialparslan. Ali Fikri Yavuz and Ömer Nasuhi Bilmen translations in JSON format.

• KFGQPC Uthmani Hafs. King Fahd Glorious Quran Printing Complex.
• Google Fonts. Scheherazade New, Amiri, Noto Naskh Arabic, Rubik, Zain, Reem Kufi, Playpen Sans Arabic.

Contributions are welcome. Whether you work with React, mobile development, or are passionate about building tools for the Quran, there is a place for you here.

Start by opening an issue to discuss your idea, then send a pull request.

MIT