If you ask most software engineers to build a school management system, they will start with students, teachers, classes, and exams. The database schema for that is well-trodden territory. You can sketch it out on a whiteboard in an afternoon.
When I started architecting Al-Maktab, I assumed the Hifz tracking module would take roughly two weeks: a table for student logs, a field for current Juz, and a completion percentage. That assumption was completely wrong. Hifz tracking took over three months of intense schema redesigns, discard pile iterations, and theological consultations.
It was, without question, the hardest subsystem in the entire platform to get right.
The Non-Linear Reality of Quranic Memorization
In standard academic curricula, progress is strictly linear. You read chapter 1, pass the quiz, move to chapter 2, and by the time you finish chapter 10, the school year is complete. You rarely test a tenth grader on whether they still remember page 14 of their first-grade spelling book.
Hifz is the exact opposite. It is an art of perpetual retention. A student memorizing the Quran has to hold 30 Juz, 114 surahs, and 6,236 ayahs in active, instantaneous memory. In classical madrasas, this is managed across three simultaneous learning streams every single day:
- সবক (Sabak): The daily new portion. Typically half a page to two pages of new text memorized that morning.
- সবকি (Sabki / Amokhta): Recent revision. The last quarter or half Juz that was memorized over the past two weeks. Because recent memory is fragile, this must be recited daily to solidify.
- মঞ্জিল / দাওর (Manzil / Daur): Long-term retention review. Reciting one or two complete previously memorized Juz from earlier months or years. Over a 30-day cycle, a Hafiz must review the entire Quran from memory.
A student might be brilliant at today's Sabak (getting a perfect score on Juz 18), but struggling severely with their Manzil on Juz 4 because retention decayed over the monsoon break. If your database flattens that student into "60% complete," you are providing zero actionable insight to either the teacher or the guardian.
How Our First Database Schema Broke in Production
Our initial design assumed students would memorize sequentially: Juz 1, then Juz 2, then Juz 3, up to Juz 30. We created an integer column current_juz and an incrementing progress bar.
On our third day of field testing at a pilot madrasa in Sylhet, an Ustad sat down and started logging a six-year-old boy. The Ustad immediately tapped Juz 30 (Amma Para), followed by Juz 29 (Tabarak Para). When I asked why he was starting from the end, he smiled warmly: "Almost every child in our region begins with the short surahs in Amma Para to build their rhythm before attempting the long narrative passages of Surah Al-Baqarah."
Our linear counter was instantly useless. Other Ustads explained that some students memorize specific high-priority surahs (like Yasin, Al-Mulk, or Ar-Rahman) before diving into full Juz blocks. We had to completely tear down our progress model and replace it with a Juz-agnostic, block-state architecture.
The Production Architecture: Logs vs. Progress Projections
We split the system into two distinct layers: an immutable session log table (hifz_session_logs) and a materialized progress projection table (hifz_student_progress).
// Database Schema Conceptual Representation
Schema::create('hifz_session_logs', function (Blueprint $table) {
$table->id();
$table->foreignId('tenant_id')->constrained();
$table->foreignId('student_id')->constrained();
$table->foreignId('teacher_id')->constrained('users');
$table->date('session_date');
$table->enum('stream_type', ['sabak', 'sabki', 'manzil']);
$table->unsignedTinyInteger('juz_number'); // 1 to 30
$table->unsignedSmallInteger('surah_start');
$table->unsignedSmallInteger('ayah_start');
$table->unsignedSmallInteger('surah_end');
$table->unsignedSmallInteger('ayah_end');
$table->enum('performance_rating', ['mumtaz', 'jayyid_jiddan', 'jayyid', 'maqbool', 'daif']);
$table->json('errors_payload'); // Type, ayah, specific notes
$table->timestamps();
});Whenever a session is recorded, a background event updates the hifz_student_progress projection. This projection powers the visual Juz Wheel in both the admin portal and the parent app.
The Visual Juz Wheel
Parents do not want to parse tabular database columns. They want to see where their child stands with a single glance. We designed an interactive SVG Juz Wheel consisting of 30 radial arc segments representing each Juz of the Quran:
- Solid Emerald Green: Memorized and successfully reviewed in Manzil with high retention scores.
- Vibrant Amber: Currently under active memorization or recent Sabki revision.
- Muted Gray: Portions not yet started.
- Ruby Red Outline: Portions flagged by the teacher as having retention decay requiring targeted revision.
When a mother opens the portal on her smartphone, the wheel gives her an immediate, beautiful, and emotionally resonant understanding of her child's sacred journey.
The Core Philosophy: Never Automate Pedagogy
During development, one junior engineer asked: "Can we automatically promote the student to the next Juz once their error count falls below three?"
The answer was an emphatic no. Software must never usurp the teacher's role. Quranic memorization is spiritual, psychological, and deeply personal. An Ustad knows if a boy is tired, if he had a family bereavement, or if he needs an extra week on Juz 15 to build confidence before facing Juz 16. The software surfaces the telemetry, the error frequencies, and the historical trends. But the human teacher—and only the human teacher—makes the decision to advance.
Mustafa Kamal Hossain
Founder & Principal Engineer at Manfi. Passionate about Laravel, SaaS architecture, and high-performance engineering.