Mahfuz is a Quran companion designed around simplicity. No clutter, no ads. Just the text and the tools you need to read, listen, and search.
- Two reading modes. Verse list for focused reading and a traditional Mushaf page view.
- Audio playback. Verse or surah-level playback with reciter selection and adjustable speed.
- Full-text search. Search across Arabic text and translations with diacritics stripping.
- Bookmarks. Save verses and access them from the home page.
- Reading tracker. Remembers last position and shows a continue-reading card.
- 3 themes. Papyrus, Sea, and Night.
- Tajweed coloring. Optional color-coded tajweed rules on Uthmani text.
- Two text styles. Uthmani (Medina mushaf) and Basic (simple script).
- 7 languages. Turkish, English, Spanish, French, Arabic, German, and Dutch interface with auto-detection.
- Offline first. PWA with Service Worker caching.
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 devDev server runs at http://localhost:3001.
| Command | Description |
|---|---|
npx pnpm@9 dev |
Start development server |
npx pnpm@9 build |
Production build (all packages) |
npx pnpm@9 lint |
Run ESLint |
npx pnpm@9 typecheck |
TypeScript type checking |
npx pnpm@9 format |
Format with Prettier |
| Layer | Technology |
|---|---|
| Framework | React 19 + TanStack Start (SSR) |
| Routing | TanStack Router (file-based) |
| Data | TanStack Query |
| Styling | Tailwind CSS v4 |
| Build | Vite 7 + Turborepo |
| State | Zustand (5 focused stores) |
| Database | Drizzle ORM + LibSQL |
| Auth | Better Auth v1.5 |
| Deploy | Dokploy (Docker, Node.js SSR) |
| Package manager | pnpm 9 |
mahfuz-app/
├── apps/
│ └── web/ Main web application
│ ├── server.mjs Node.js SSR server
│ ├── Dockerfile Multi-stage Docker build
│ ├── drizzle/ Database migrations
│ └── src/
│ ├── components/ UI components (22 files)
│ │ ├── reader/ AyahBlock, MushafPage, SurahView, AudioBar...
│ │ ├── habit/ HabitDashboard, StreakCard, WeeklyChart
│ │ └── icons/ MahfuzLogo
│ ├── hooks/ Custom hooks (5 files)
│ ├── locales/ i18n strings (tr, en, es, fr, ar, de, nl)
│ ├── lib/ Utilities (13 files)
│ ├── routes/ File-based routes (12 files)
│ ├── stores/ Zustand stores (5 files)
│ └── db/ Drizzle schema
├── 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
| Route | Description |
|---|---|
/ |
Home — continue reading, bookmarks, surah list |
/surah/$surahSlug |
Surah reader (verse list with translations) |
/page/$pageNumber |
Mushaf page view |
/juz/$juzId |
Juz reader (redirects to first page) |
/search |
Full-text search |
/bookmarks |
Saved verses |
/auth/login |
Login / register |
/auth/callback |
OAuth callback |
| Store | Purpose |
|---|---|
settings |
Theme, reading mode, font sizes, translation, reciter, text style |
reading |
Last reading position, history |
bookmarks |
Saved verses with timestamps |
audio |
AudioEngine ref, playback state |
locale |
Current UI language |
Quran API (api.quran.com)
↓
Service Worker (stale-while-revalidate)
↓
TanStack Query (in-memory, 24h gcTime)
↓
React Components (Zustand for UI state)
↓
Server DB (LibSQL via Drizzle ORM)
| Translation | Author | Source |
|---|---|---|
| Diyanet İşleri Başkanlığı Meali | Diyanet İşleri Başkanlığı | quran.com API |
| Ömer Çelik Meali | Prof. Dr. Ömer Çelik | kuranvemeali.com |
| Ömer Nasuhi Bilmen Meali | Ömer Nasuhi Bilmen | kuranayetleri.net |
| Ali Fikri Yavuz Meali | Ali Fikri Yavuz | kuranayetleri.net |
- 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, Noto Naskh Arabic.
Contributions are welcome and encouraged. 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