Building for a faith-based audience is the same as building for any other audience.
Just ship fast, iterate, repeat.
That’s what I thought before I started MyTazki an AI-powered Islamic
companion PWA with Quran audio, Duas, prayer times, a Qibla compass, AI dhikr
sessions, and push notifications for Adhan. Six months and 35+ features later,
here are the technical decisions that genuinely surprised me for better
and worse.
1. Contract-First API Changed Everything (and I Almost Skipped It)
The most impactful DX decision in the project wasn’t the AI stack or the database
choice. It was writing the OpenAPI spec first and generating everything from it.
Here’s the flow:
lib/api-spec/openapi.yaml
↓ (pnpm –filter @workspace/api-spec run codegen)
lib/api-client-react/src/generated/api.ts ← React Query hooks
lib/api-zod/src/generated/api.ts ← Zod validators
Orval reads the spec and generates type-safe React Query hooks and Zod schemas
in one command. The server validates inputs with the generated Zod schemas. The
frontend calls the generated hooks. If the contract changes, a single codegen run
propagates it everywhere TypeScript screams at every inconsistency before a
single test runs.
Before this, I was hand-writing fetch() calls, manually keeping types in sync,
and debugging a mismatch between what the server sent and what the client expected.
After? I haven’t written a raw fetch() on the frontend in four months.
The lesson: **the five hours you spend writing the OpenAPI spec saves you fifty
hours of type drift.**
2. I Used a Key-Value Store Instead of PostgreSQL — No Regrets
MyTazki runs on @replit/database, a simple key-value store. No schema migrations.
No SQL. No connection pooling. Just get, set, and list.
That sounds naive for a production app, but here’s the reality: every entity that
would live in a relational table maps cleanly to a key pattern:
user:{userId} → profile object
streak:{userId} → { currentStreak, totalDays, lastCheckin }
push:{userId} → subscription object
aiUsage:{userId}:{date} → number (daily AI call count)
duas:{duaId} → dua object
sessions:{sessionId} → session object
The gotcha is the return type. db.get() returns OkResult | ErrResult — not the
value directly. Every single read needs:
typescript
const result = await db.get(`user:${userId}`);
const user = result.ok ? result.value : null;
Forget that check and you're silently working with an error object that looks truthy.
I forgot it exactly twice. Both times were memorable.
The real limitation is joins. When you need "all duas favorited by user X," you
either store an index (favs:{userId} → [duaId, duaId, ...]) or do a full scan.
For a prayer app at this scale, that trade-off is acceptable. For anything with
complex relational queries, it's a pain.
3. The iOS Safari Audio Hack No One Writes About
The Quran reader plays 114 surahs with per-ayah audio from everyayah.com. Each
ayah is a separate .mp3 file in the format SSSAAA.mp3 (surah + ayah, zero-padded).
On desktop Chrome: trivial. Create an Audio element, update src on each ayah,
call play(). Works perfectly.
On iOS Safari: the moment you update audio.src and call play(), Safari
treats it as a new user-initiated play event — and blocks it, because iOS requires
audio to be triggered directly by a user gesture. Autoplay restrictions apply to
every new src assignment.
The fix: one persistent Audio element, never replaced — only src swapped.
// Created once, at component mount never recreated
const audioRef = useRef(new Audio());
function playAyah(surah: number, ayah: number) {
const src = `https://everyayah.com/data/Alafasy_128kbps/
${String(surah).padStart(3,'0')}
${String(ayah).padStart(3,'0')}.mp3`;
audioRef.current.src = src;
void audioRef.current.play(); // Works — iOS sees this as continuation
}
The first play() call must happen inside a user gesture handler (a tap). After
that, swapping src and calling play() on the same element inherits that
gesture permission for the session. Destroying and recreating the Audio element
resets the permission.
This took me a day and a half to figure out. Saving you the half.
4. AI Rate Limiting in a KV Store Simpler Than You Think
The AI companion routes through Anthropic's Claude. Without rate limiting, one
motivated user could burn through significant API credits in an afternoon. The
solution is 20 AI requests per user per day, tracked with a single KV key:
const dateKey = new Date().toISOString().split('T')[0]; // "2026-05-14"
const usageKey = `aiUsage:${userId}:${dateKey}`;
const result = await db.get(usageKey);
const count = result.ok ? Number(result.value) : 0;
if (count >= 20) {
return res.status(429).json({ error: "Daily AI limit reached. Resets at midnight." });
}
await db.set(usageKey, count + 1);
// ... call Claude
Keys naturally expire with the date — no cron job needed to clean up. Today's key
is aiUsage:user123:2026-05-14. Tomorrow it's aiUsage:user123:2026-05-15. The
old key just sits there taking up negligible space until you decide to clean it.
5. Qibla Compass: Web APIs Are Wilder Than I Expected
The Qibla page shows a compass needle pointing toward Mecca. The math is
straightforward — a great-circle bearing from the user's coordinates to
(21.4225° N, 39.8262° E). The Web part is where it gets interesting.
The Web Magnetometer API (DeviceOrientationEvent + webkitCompassHeading on
iOS) gives you the device's heading relative to magnetic north. Android exposes
DeviceOrientationEvent.alpha (rotation around Z-axis). But:
iOS requires HTTPS and explicit permission (DeviceOrientationEvent.requestPermission())
only available in a user gesture handler.
Android Chrome exposes the API but many mid-range devices have poor magnetometer
calibration the needle drifts.
Desktop browsers mostly return null for magnetometer data.
The fallback chain I settled on:
GPS bearing (always available) → show Qibla direction on map
+ Magnetometer (when available) → animate live compass needle
+ Calibration prompt when accuracy is low → "Wave your phone in a figure-8"
The figure-8 calibration prompt was the most-commented feature in user feedback.
Turns out most people have never calibrated their phone compass and find it
genuinely surprising that this is a thing.
6. Push Notification Scheduling Is a Scheduler Problem
Prayer times differ by location. Fajr in London in January is 7:14 AM. In Karachi
in June, it's 4:02 AM. You can't pre-schedule notifications — you have to compute
them fresh for each user, each day, from their stored coordinates.
The approach: a scheduler loop running every 60 seconds on the API server, checking
whether any prayer time falls within the next minute for any subscribed user:
setInterval(async () => {
const subscribers = await getAllPushSubscribers(); // list prefix scan
for (const { userId, subscription, preferences } of subscribers) {
const user = await getUser(userId);
const times = await getPrayerTimes(user.lat, user.lon);
for (const prayer of PRAYERS) {
if (!preferences[prayer]) continue;
const prayerTime = times[prayer]; // e.g. "05:23"
if (isWithinOneMinute(prayerTime)) {
await sendPushNotification(subscription, {
title: `${prayer} time`,
body: `It's ${prayerTime} — time for ${prayer} prayer`,
});
}
}
}
}, 60_000);
The cold-start problem: if the server restarts at 5:22 and Fajr is at 5:23, the
first tick runs at 5:22:00 and sends the notification. If the restart takes more
than 60 seconds, you miss the window. For a prayer app, missing Fajr is bad UX.
The mitigation: start the interval with an immediate first tick (setImmediate +
setInterval), and log all misses for monitoring.
7. The Cultural UX Layer Is a Real Engineering Problem
Every technical decision in an Islamic app has a cultural dimension that isn't
obvious until you're building it.
Arabic RTL: React renders fine with dir="rtl", but flexbox reverses
direction in unintuitive ways. Every flex container near Arabic text needs explicit
direction management. I standardized on Amiri (font-family: "Amiri, serif") for
all Arabic text — it renders Quranic Arabic with correct diacritics and ligatures.
Using a generic serif font for Quranic text is visually wrong in a way that users
notice immediately.
Hijri calendar: The Hijri date doesn't map 1:1 to Gregorian — it's a lunar
calendar that shifts by ~11 days per year. I use aladhan.com for both prayer
times and Hijri date conversion. Trying to calculate this locally is a rabbit hole
I'm glad I didn't go down.
Tasbih counter: A simple counter with a haptic feedback tap. Sounds trivial.
The UX constraint: it must work with one hand while sitting in prayer. No accidental
resets. Every interaction must be deliberate. The reset button is hidden behind a
long-press, not a tap. Users asked for this explicitly.
Gender-neutral Duas: Some duas in classical Arabic are grammatically gendered.
For a library of 110+ duas, deciding which to include, how to present gender
variants, and whether to show transliteration by default required real product
thinking — not just copy-paste from an API.
What I'd Do Differently
Start with SSR or a static shell. The SPA approach means search crawlers that
don't execute JavaScript see an empty . I added a pre-render
trick (H1 inside #root that React replaces on mount) but proper SSR or
prerendering would have been cleaner from day one.
Use Postgres earlier. The KV store got me to v1 fast, but the index management
complexity starts compounding around feature #15. A lightweight Postgres setup
from the start would have been worth the initial overhead.
Design the push notification UX before the infrastructure. The scheduler was
fun to build. Designing the permission request flow — when to ask, what to say,
how to handle denial gracefully — took longer than the scheduler itself.
The Stack, For Reference
Frontend: React + Vite, TypeScript 5.9, Tailwind CSS, pnpm workspaces
Backend: Express 5, @replit/database (KV), JWT auth, bcryptjs
AI: Anthropic Claude via API proxy
Push: web-push, VAPID, 60s scheduler loop
API Design: OpenAPI spec → Orval → React Query hooks + Zod schemas
Build: esbuild (CJS bundle for the server)
MyTazki is live at mytazki.com — free, no credit card,
works on any device as a PWA. If you're building for underrepresented communities
or faith-based audiences, I'm happy to answer questions in the comments.
