Mahfuz / محفوظ

A quiet companion for reading, listening to, learning, and memorizing the Quran, together.

mahfuz.ilg.az

Mahfuz started as a simple Quran reader and grew into a full learning companion. No ads, no distractions. It is open source and free to use.

Whether you are reading for the first time or working on your hifz, Mahfuz gives you the tools without getting in the way.

• Two reading modes, Ayet and Mushaf: swipe horizontally to flip the sub-view (Ayet ⇄ word-by-word, Mushaf ⇄ meal-only)
• Mushaf page view (604 pages) with the traditional scalloped verse-end medallion, keyboard and swipe navigation
• 6 Turkish translations including Diyanet, Elmalılı, Ömer Çelik, Ömer Nasuhi Bilmen, and Ali Fikri Yavuz, plus 18 more across 19 languages
• Two text styles: Uthmani (Medina mushaf script) and simplified Arabic, with optional tajweed coloring
• Bookmarks and reading position tracking across sessions

• Verse-level and surah-level audio playback with word-by-word highlighting
• Multiple reciters with adjustable speed and volume
• Continuous playback across verses

• Alifba: learn the 28 Arabic letters with forms, pronunciation, and finger tracing
• Qaida: 10-stage structured reading curriculum from letters through Al-Fatiha to tajweed
• Tajweed rules: 16 interactive rules with examples (Madd, Idgham, Ikhfa, Izhar, Iqlab, Qalqala, and more)
• Verse analysis: side-by-side translations, morphology, themes, similar verses, and contextual explanations

Eight Quran games to test your knowledge:

• Fill in the blank: complete the missing word in a verse
• Verse chain: connect verses in the correct order
• Surah guess: identify the surah from a verse
• Word meaning: match Arabic words to their meanings
• Hexagon: form words from scattered letters
• Word prediction: guess the next word (daily and free modes)
• Verse 2048: merge matching verse tiles
• Word match: pair Arabic words with translations

Plus seven Alifba mini-games for letter recognition, memory, and speed. Global leaderboards and achievements.

• Meclis (party mode): real-time multiplayer rooms — vote on the next game, play three rounds together with live scoreboards, public and password-protected lobbies
• Khatm groups: create or join a group to complete the Quran together, track each member's progress
• Personal notes on verses
• Hifz tracker: mark memorized verses and see your progress per surah

• 3 themes (Light, Sepia, Dark) with a 5-color burgundy/stone/petrol/green/indigo accent palette
• 7 UI languages (Turkish, English, Spanish, French, Arabic, German, Dutch) and 49 translations across 19+ languages
• 55 reciters including Yasser Al-Dossari, Badr Al-Turki, Al-Husary, Al-Banna, Maher al-Muaiqly, and more
• Offline support: PWA with Service Worker caching
• Auth: email, Google, and Apple sign-in

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:3001.

mahfuz-app/
├── apps/
│   ├── web/                    Main web app (React + TanStack Start)
│   └── mobile/                 Expo / React Native app
├── packages/
│   ├── shared/                 Types, constants, curriculum data
│   ├── audio-engine/           HTML5 audio with word-level sync
│   ├── audio-engine-mobile/    Expo / React Native audio engine
│   ├── recitation-engine/      ONNX Runtime Web verse recognition
│   ├── db/                     Dexie IndexedDB schemas
│   ├── api/                    Server-side API helpers
│   ├── api-client/             HTTP client
│   ├── gamification/           Scoring and achievements
│   ├── memorization/           Hifz tracking and spaced repetition
│   └── sdk/                    Public SDK (CJS + ESM)
└── tooling/                    Shared ESLint, TypeScript, Tailwind configs

• Tanzil.net - Quran verse texts in Uthmani and Simple scripts. CC BY 3.0.
• Quran.com API - Word-by-word data, transliteration, and translations.
• Açık Kuran API - Additional Turkish translations and root word analysis.
• Kuran Meali Ebook Oluşturucu by alialparslan - Ali Fikri Yavuz and Ömer Nasuhi Bilmen translations.

• KFGQPC Uthmani Hafs - King Fahd Glorious Quran Printing Complex.
• Scheherazade New and Noto Naskh Arabic from Google Fonts.

Contributions are welcome. Whether you work with React, care about accessibility, or want to improve translations, there is room for you here.

Open an issue first so we can talk about it, then send a pull request.

MIT