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 <div id="root">. 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.