Istiqama
Quran Center Management System
A local Quran teaching center — 26 teachers, roughly 300 students, run across dozens of weekly halaqa classes — tracked every student's memorization progress, attendance, and revision cycle on paper. There was no way to see center-wide trends, flag a student falling behind, or generate a parent update without manually flipping through logbooks, and many classes are held in rooms with poor or no internet connectivity.
Istiqama replaces that with a single daily-entry workflow: hifz (memorization) tracking rated on a 4-point scale for new memorization, recent revision (سبقي), and older revision (منزل); attendance in the same save; a color-coded monthly calendar as the primary navigation and coverage view; and a server-enforced role hierarchy of principal, supervisor, and teacher. On top of that sit center-wide reporting, AI-assisted Arabic parent messages (Groq, with a silent template fallback), on-demand Arabic/RTL PDF report cards, and an installable PWA.
The most technically interesting part is the offline path. Real classrooms often have zero connectivity, and a sync-queue PWA approach was tried first and abandoned — it never synced reliably and has no iOS support. The second architecture instead generates a fully static, personalized HTML page per teacher with the roster baked in and zero network calls; teachers fill it out offline and paste a compact structured payload into a Telegram bot chat, letting Telegram's own infrastructure absorb the unreliable-network problem instead of custom retry/conflict-resolution logic.
Engineering highlights
- Telegram as an offline transport, not a chat feature — a static per-teacher HTML page generates a structured payload that's pasted into a bot chat, so Telegram's infrastructure absorbs the unreliable-network problem entirely.
- Raw-storage-first ingestion — every inbound Telegram message is persisted verbatim before parsing, so a malformed payload never loses data and one bad row never discards the rest of a class submission.
- One shared save path for both channels — the Telegram flow and the web UI's daily-session form funnel into the exact same server-side validation/save function, with no parallel offline code path to drift out of sync.
- Server-side RBAC with a real supervision hierarchy — a teacher can be granted supervisor rights over every class at a given level, enforced consistently through one access-check module reused by every route and server action.
- A guided, zero-login product tour built specifically for sharing the project — a persona picker (principal / supervisor / teacher) walks through the real app UI, not mockups, against fully synthetic data. A floating "دليل الشاشة" (screen guide) panel follows the visitor from page to page, explaining what each screen is for and suggesting what to try next. It's provably isolated from real data: a demo-mode guard re-checks for a real session on every call, and the demo code is barred from importing Prisma or auth at all, enforced by a dedicated isolation script.