A quiet app for reflecting on the Qur'an. Read verses with translation and commentary, sit with a short guided reflection, count your dhikr, and keep a private journal.
It works in the browser, needs no sign up, and works offline. This is an early version. It is free.
Live at mindfulverse.vercel.app
- Daily check-in. A verse for today, a gentle mood picker, and a place to journal.
- Tadabbur sessions. 20 short guided reflections. Each one has a theme, a few verses, and a prompt.
- Dhikr and breath. A breathing circle paced to remembrance, with tap counting.
- Read. All 114 surahs with Arabic, English translation, and Ibn Kathir's commentary.
- Search and topics. Search the translation, or find verses by topic and jump into the reader.
- Journal. Your reflections, saved on your device, with the verse they were written about.
- Accounts & sync. Optional sign-in (email or Google) backs up your journal and progress across devices.
- Daily reminder. A push notification with the verse of the day, at a time you choose.
All Qur'an text, translation, and commentary are shown exactly as they are. The app never rewrites or generates religious content.
| Home | Reader | Daily check-in |
|---|---|---|
 |
 |
 |
| Tadabbur sessions | Browse by theme | Dhikr and breath |
|---|---|---|
 |
 |
 |
The repo is an npm workspaces monorepo. Run everything from the root:
npm install
npm run build:data # writes apps/web/public/data
npm run dev # web app dev server| Command | What it does |
|---|---|
npm test |
The whole vitest suite: packages/core, apps/web, and functions/ |
npm run build |
Typechecks packages/core (no DOM), then builds the web app to apps/web/dist |
npm run preview |
Serves the production build |
npm run typecheck |
Typechecks packages/core only |
npm run test:e2e |
Playwright smoke test in apps/web/e2e (skips without E2E_EMAIL/E2E_PASSWORD) |
.env / .env.local stay at the repo root; the web app reads them from there.
React, TypeScript, and Vite, with a service worker for offline use. All Qur'an data is bundled and the journal lives in your browser first; the only server component is an optional InsForge backend for account sync and reminders (see "Accounts & sync" below).
packages/core/ shared logic, no DOM: data loaders, journal, progress,
analytics, divisions, sync engine + merge, InsForge
client, account context (@mindfulverse/core)
apps/web/ the Vite PWA: pages, components, service worker, and the
web side of the core's platform seams (src/setup.ts)
apps/web/public/data/ generated Qur'an, tafsir, themes, sessions, emotions
functions/ InsForge edge functions (daily reminder)
migrations/ InsForge SQL migrations
scripts/ build-data.mjs, which turns raw datasets into app data
raw-data/ source datasets, not committed
The core never touches browser APIs directly. A host app wires it up once at startup — configureInsforge, configureData, configureSyncTriggers, and configureAnalytics — and provides localStorage and crypto.randomUUID. See docs/superpowers/plans/2026-10-06-rn-phase1-extraction.md.
To change the data, update the files in raw-data/ and run npm run build:data again.
The Qur'anic datasets come from the Quranic Universal Library by Tarteel. This app would not exist without their work.
The English translation is ClearQuran by Talal Itani, used under the CC BY-NC-ND 4.0 license. The Arabic typeface is the KFGQPC Uthmanic Hafs script from the King Fahd Glorious Qur'an Printing Complex in Madinah.
Signing in is optional — the whole app works signed-out, offline, on-device. An account only backs up your journal and progress so they follow you to another device. Auth, storage, and Postgres are provided by InsForge; there is no other server.
Set these in .env (or .env.local) for local development — see .env.example. On Vercel, add all three under Project → Settings → Environment Variables for both Production and Preview, then redeploy; they are VITE_* so Vite inlines them at build time, not at runtime.
Backend setup — SQL migrations live in migrations/, and the reminder/push edge functions live in functions/; both are applied to the InsForge project directly (see the InsForge CLI), not run from this repo.
The merge story, in three sentences: everything is written to localStorage first, so the app never blocks on the network; signing in, reconnecting, or returning to the tab triggers a sync that pulls the account's remote journal and progress and merges them with what's on this device — journal entries by union-by-id with soft-delete tombstones, progress by per-key max / earliest-completion / latest-read / set-union — then pushes back only the resulting diff. Every merge is deliberately commutative and idempotent — running it twice, or on two devices at once, converges to the same state rather than duplicating or clobbering entries.
- The translation renders the divine name as "God". It is shown word for word, as the license requires.
- Ibn Kathir wrote commentary on passages, so some verses share a note with a neighboring verse.
- Recitation audio, payments, and more languages are planned for later. See
ROADMAP.md.