← QuranFlow — the redesign

QuranFlow iOS App — Product Specification

Screen-by-screen functional specification for the redesigned QuranFlow app, derived from the finalized Sakīna mockup (../mockup/). This document describes behavior — purpose, data, states, actions, navigation, and role gating — not implementation. It is the handoff artifact for engineering.

Sources: ../mockup/src/main.jsx (screen inventory), AUDIT.md (design rules and per-screen audit log), REVIEW.md (adjudicated design decisions — binding where old and new mockup sections conflicted), FEEDBACK-SYNTHESIS.md (stakeholder requirements that motivated the F1–F5 screens).

1. Overview

Product. QuranFlow is a Qur'anic recitation app built around a 15-week semester. Each week a student watches a lesson video, records a recitation submission, receives audio feedback from an assigned coach, and (depending on level) attends live sessions. Year 2 students additionally book recurring 1:1 sessions with their coach. Coaches use a companion Coach app to review submissions, track student history, and manage their own live-session schedule.

Roles.

Role Description App surface
Year 1 student Submission-centric. No 1:1 appointments. Live sessions are group circles (QRC, Level Class, Office Hours). Student app, Year-1 view
Year 2 student Everything Year 1 has, plus a recurring or week-to-week 1:1 slot with their coach. Student app, Year-1 view + Sessions tab "One-to-one" row + booking flow
Coach Reviews submissions, replies with audio feedback, manages a personal schedule (group sessions + 1:1s), keeps shared student notes. One coach per student (single-coach model; see §5 Open Questions). Coach app

The mockup's reference student is Sarah — Level II, Week 8 of 15, coach Ust. Amina (audio feedback).

Organizing principle: Weekly Rhythm. Every core screen orients the student inside a fifteen-week arc — "Week 8 of 15" — rather than as a flat list of content or an isolated task. This solves the disorientation identified in the original audit (NN/g HEART methodology, Nov 2025): students lost track of where they stood in the semester. The week strip (SakStrip total={15} done={7} current) is the single recurring visual anchor for this; per AUDIT.md Rule R1, it appears once per screen, never duplicated as a second caption or footer.

2. Navigation map

Student app — four root tabs

  1. Today — the daily landing screen: date, current lesson status, today's live sessions (inline expanding rows), submission deadline reminder.
  2. Learn — the syllabus: current lesson hero, part list, lesson history.
  3. Sessions — the weekly live-session timeline (day-strip + Tuesday-focused view by default), with a Recordings sister-state reached via a segmented control, and a calendar icon in the header that opens Week at a glance (a lower-density, full-week overview — see B2 below).
  4. Profile — identity, coach panel, submissions archive, settings, subscription, support.

Drill hierarchy (screens reached by tapping into a tab, not tabs themselves)

Notification deep-link targets

Per REVIEW.md C4, SakSessionDetail / SakSessionDetailQRC (full session detail pages) are not reached by any on-canvas tap — they exist solely as the destination when a student taps a session-reminder push notification. Other deep-link targets:

Coach app — tabs

The coach tab bar defines four tabs — Queue, Students, Schedule, You — of which two have designed artboards in this mockup:

  1. Queue (designed) — list of pending submissions awaiting review.
  2. Students (no dedicated artboard) — reached contextually via a submission or schedule row; destination is Student record.
  3. Schedule (designed) — the coach's own calendar: group sessions + 1:1 rows, each labeled Recurring or This week only (REVIEW.md D1).
  4. You (undesigned) — coach profile/settings; build by analogy with the student Profile tab (see Section C).

Drill screens: Review queue row → Review a submission (assignment text + audio + annotation + reply, the "unified workspace" from the coach questionnaire). Student record is reached from a submission or schedule row and carries shared notes visible to any coach who has taught that student (cross-coach visit history — REVIEW.md A4's Ust. Rania shared-note example).

3. Screen-by-screen specification

Organized in main.jsx artboard order. Each entry: purpose, key content/data, states, actions and destinations, role gating.

Section 00 — The four tabs

Today (SakToday)

Purpose. Daily landing screen; answers "what do I do today?"

Key content. Header eyebrow "Tue · 17 Apr" + greeting "Good morning, Sarah." Hero card (ink, the screen's one anchor): "Today's lesson" eyebrow, lesson title ("Idghām with ghunnah"), meta line "1 video · 1 recording · about 12 min," the week strip (SakStrip total={15} done={7} current), "Week 8 of 15" label, and a single primary CTA "Continue" → enters Lesson. Below the hero: Sessions today section listing the day's live sessions (SessionRow) — e.g. 2:00 PM QRC "Sisters' Reading Circle" with Ust. Radwa (live now, showing "Join"), 7:00 PM "Idghām review & practice" (also Ust. Radwa). A verse closer (Arabic + citation only, no translation) closes the screen.

States. Live session row shows a "Join" pill instead of a chevron. Non-live rows are tappable to expand an inline shelf (see Actions).

Actions / destinations.

Role gating. None — same for Year 1 and Year 2 (Year 2's 1:1 does not appear on Today; it lives on the Sessions tab).

Learn — syllabus (SakLearn)

Purpose. The syllabus: current lesson + full 15-week structure grouped into three parts.

Key content. Header "Spring 2026 · Level II" eyebrow, title "Your syllabus." "Current lesson" paper hero card: title "Idghām with ghunnah," week strip, CTA "Open lesson." Below: three collapsible Parts (flat tappable rows, not cards) — "1 · Foundations" (3 lessons, all done), "2 · Tajweed rules" (6 lessons, lesson 8 current, 9 next), "3 · Application & review" (6 lessons, all upcoming). The part containing the current lesson is expanded by default; opening a part reveals its lesson rows in a quiet card. Closing panel: "By June 22, you'll" — one sentence stating the term's outcome ("Read short sūrahs aloud with steady tajweed, and submit a final recital of Al-Mulk to your coach").

States. Each lesson row is done (checkmark, struck through), current (open-book icon, highlighted), next, or soon. Each Part's collapsed summary line reads differently depending on progress: "N lessons · all done," "X of N done · in progress," or "N lessons · starts Wk N."

Actions. Tapping "Current lesson" hero or a lesson row → Lesson. Tapping a Part row toggles expand/collapse (no navigation).

Role gating. None.

Sessions — Tuesday timeline (SakSchedule)

Purpose. The week's live-session schedule, timeline-style, defaulting to the current day.

Key content. Header eyebrow "Tue · 17 Apr," title "Sessions," calendar icon action. Segmented control: Upcoming / Recordings (Upcoming selected here — see 00a for the Recordings state). A 7-day day-strip (Sat 22 → Fri 28, Tuesday selected/today). A quiet zone banner: "All times shown in Toronto (EDT)" (REVIEW.md B3). Below, a vertical timeline for the selected day with a gold "now" thread. Canonical Tuesday items (REVIEW.md A3): 9:20 AM "One-to-one — recitation" with Ust. Amina (type chip "1:1," state ended — Year 2 only, see Role gating), 2:00 PM "Sisters' Reading Circle" (QRC) with Ust. Radwa (state soon, countdown "in 12 min," shows a live "Join" pill), 7:00 PM "Idghām review & practice" (Level Class) with Ust. Radwa (state upcoming).

States. Each timeline row is ended (dimmed, play icon instead of chevron), soon/live (gold "Join" pill, no expand), or upcoming (tappable, expands an inline shelf identical to Today's — coach, what's covered, Open Zoom / Remind me). A deadline row type exists in the component (dashed border, "Due today · Submission deadline") for weeks where a deadline falls on the viewed day.

Actions / destinations.

Role gating. The 1:1 / "One-to-one" row appears only for Year 2 accounts. Year 1 accounts never see it (REVIEW.md C2). Entry to booking: Sessions ▸ calendar icon ▸ "Book your one-to-one" (also surfaced during Year-2 enrollment).

Profile (SakProfile)

Purpose. Identity, coach relationship, account/settings/support menus.

Key content. Frontispiece card: avatar (with camera/edit affordance), full name "Sarah Ahmed," "Level II · Reading with fluency," three stats (7 weeks done, 6 submissions, 85% attendance). Your Quran coach panel (ink card): "Ust. Amina al-Qārī," "Certified · Level I–II · Cairo," a mini waveform line ("1 note"), primary CTA "Message" (REVIEW.md B5 — standardized verb) → Message thread. Three menu groups:

Actions / destinations. Each menu row is a drill (chevron) to its named destination, except Sign out (destructive, no chevron).

Role gating. None on this screen itself (Year 2's appointment surfaces live under Sessions, not Profile).

Section 00a — Tab states

Sessions — Recordings (SakScheduleRecordings)

Purpose. Sister-state of the Sessions tab: past sessions that have a recording, in place of the Upcoming timeline.

Key content. Same header/segmented control/day-strip chrome as Upcoming, with "Recordings" selected. Rows grouped by week ("This week," "Week 7 · Apr 8–14," "Week 6 · Apr 1–7"), each row showing a video thumbnail (partial-watch progress bar if in progress), type chip, title, coach, date, and duration (e.g. "Tue · 9 Apr · 10:00 AM · Level Class · Idghām — practice patterns · Ust. Radwa · 52:04"). Watched state is labeled "watched" (fully seen) or "N% in" (partial).

Actions. Tapping a recording row plays it (implementation detail: opens video playback; no separate screen defined in this mockup).

Role gating. None.

Section F1 — Feedback loop

Submission — feedback ready (SakSubmissionFeedback)

Purpose. The unified feedback object: assignment text with the coach's marks, the coach's audio note, timestamped corrections, the student's own recording, and the loop-closing actions — replacing the fragmented notebook/printout/spreadsheet workflow coaches reported (top convergent finding in FEEDBACK-SYNTHESIS.md).

Key content. Eyebrow "Week 7 · Reviewed" (see REVIEW.md A2 — week 7 is the canonical "reviewed" state; week 8 is "in review," tracked by SakSubmissionPending). Assignment passage (SakPassageCard, 3 āyāt of Al-Mulk 67:1–3) with word-anchored marks (danger = correction needed, warm = praised) numbered 1–5. Coach feedback card (ink, the squint anchor): "Ust. Amina's notes," "2 days ago · 6:48" duration, playable waveform with 5 tappable markers aligned to the 5 marks above. Timestamped notes list (collapses past 3, "Show N more notes") — each note pairs a mark number, a play chip with its timestamp, a short title (e.g. "تَبَارَكَ — stretch the madd"), and detail ("Four counts, not two · 67:1"). "Your recording" card (2:41, playable). Primary CTA "Practice the corrections" (does not burn an attempt) → Practice the corrections. Two secondary actions: "Mark as heard" and "Voice reply."

States. Notes list collapsed (default, showing 3) vs. expanded (all 5).

Actions / destinations.

Role gating. Student-only screen.

Submission — in review · revoke window (SakSubmissionPending)

Purpose. State of a just-submitted recording still inside its revoke window — the sole owner of revoke-window UI (REVIEW.md A1; do not duplicate this countdown on the Submitted confirmation screen).

Key content. Eyebrow "Week 8 · In review." "Your recording" card, "sent 3 min ago," 2:41 duration, playable. Revoke window card (dashed border): "Changed your mind?" with a live countdown ("6:52 left"), body copy "Take it back and re-record — it won't count as one of your two weekly attempts," and a "Revoke & re-record" button. "What happens next" card: "Ust. Amina will listen next · Feedback within 48 hours."

States. Only one state shown (countdown ticking down); the countdown reaching zero is the transition to a closed submission (not separately modeled in the mockup — an engineering-defined transition, not a design one).

Actions. "Revoke & re-record" → discards the submission and returns to Recording — Ready without decrementing the attempt count.

Role gating. Student-only.

Practice the corrections (SakRecPractice)

Purpose. Records a corrected take against one coach note at a time — free of the two-submission weekly limit (REVIEW.md C3).

Key content. Eyebrow "Week 7 · Practice," title "Corrections." Stepper: "Correction 1 of 3" + dot progress. The flagged passage fragment only (e.g. "تَبَارَكَ" underlined) with the coach's correction text ("Stretch the madd — four counts, not two"). A "Hear Ust. Amina's note" reference-clip card ("from 0:41 · 18 sec"). A breathing accent-colored mic button (visually distinct from the recording flow's red mic — accent/plum signals "practice," not "graded"), with prompt "Record your corrected take" and sub-copy "It attaches to this week's feedback — Ust. Amina will check it against her notes."

States. Steps through corrections one at a time (this artboard shows step 1 of 3); implies the same screen re-renders for corrections 2 and 3.

Actions. Recording → Practice — review take.

Role gating. Student-only.

Practice — review take (SakRecPracticeReview)

Purpose. Review screen for a practice take — reuses SakRecReview's chrome without modifying that component (REVIEW.md C3); the missing "next state" the practice loop lacked before this addition.

Key content. Eyebrow "Week 7 · Practice," title "Your take." Verse card (compact). "Your recording" duration (0:19), waveform playback card, Play + Re-record buttons. Primary CTA "Attach to feedback" (not "Submit to coach") with sub-copy "Practice takes don't use your weekly attempts." No attempt dots are shown anywhere on this screen — practice takes are exempt from the two-submission limit.

Actions. "Attach to feedback" → attaches this take to the current week's feedback thread (returns to Submission — feedback ready with the new take visible, per the surrounding narrative — exact return screen is an implementation choice). "Re-record" → re-enters recording for this correction.

Role gating. Student-only.

Section F2 — Time & schedule

Week at a glance (SakWeekAtGlance)

Purpose. The full week's schedule on one screen, entirely in local time — answers "what's on this week?" at a lower zoom level than the Sessions tab's day-focused timeline (REVIEW.md B2's "two density levels of one surface").

Key content. Eyebrow "Week 8 · Your local time," title "This week," a calendar-plus header action. Zone banner: "All times shown in Toronto (EDT)." Canonical Week 8 layout (REVIEW.md A3): Monday 23 Apr — 10:00 AM "Idghām with ghunnah" (Class, Ust. Radwa, reminder on); Tuesday 24 Apr — 2:00 PM "Sisters' Reading Circle" (QRC, Ust. Radwa, reminder on) + 7:00 PM "Idghām review & practice" (Class, Ust. Radwa, reminder off); Thursday 26 Apr — 9:00 PM "Drop-in Q&A" (Office Hours, Ust. Amina, reminder off); Sunday 29 Apr — 11:59 PM "Week 8 submission deadline" (Due, reminder on). Each row shows a bell icon (filled/tinted when a reminder is set). Whole-week action: "Add the week to my calendar." Footer: "Reminders arrive 15 minutes before each session."

Actions. Header calendar-plus icon and the "Add the week to my calendar" row both add calendar entries. Individual row bell icons toggle that item's reminder.

Role gating. None — Year 2 students additionally see their 1:1 in this list (not shown as a distinct row type in the current mock data, but logically part of the same day-grouped structure).

Section F3 — Communication

Announcements (SakAnnouncements)

Purpose. One-way, audience-filtered board replacing the old community board (FEEDBACK-SYNTHESIS.md decision #2); this is the notification sheet's deep-link target for announcement-type rows (REVIEW.md B4c/C1a).

Key content. Title "Announcements," bell icon. Filter chips: "All" (default, active) / "My level" / "Schedule." Pinned post card (paper, gold hairline): audience "Everyone," "Eid break — no sessions May 4–6," body, "QF Team · 2 days ago." "This week" list: e.g. "Thursday's Level Class moved to 11:00 AM" (Level II audience, from Ust. Radwa — same copy as the notification-sheet row per REVIEW.md B4b), "Running 5 minutes late to tonight's QRC" (Everyone, Ust. Amina), "Week 9 recordings posted" (Level II, QF Team). Footer note: "Announcements are one-way. To reach your coach, send her a message" (links to Message thread).

States. Unread rows show a gold dot indicator.

Actions. Footer "send her a message" link → Message thread.

Role gating. Audience filtering ("My level," "Schedule") implies posts are tagged by year/level and filtered per FEEDBACK-SYNTHESIS.md decision #2; no coach/admin authoring UI is defined in this mockup (out of scope — presumably an admin/coach-side tool).

Messages — Ust. Amina (SakMessageThread)

Purpose. Guarded 1:1 text/voice thread between student and coach — replacing the peer community board's messaging function (FEEDBACK-SYNTHESIS.md decision #2).

Key content. Eyebrow "Usually replies within a day," title "Ust. Amina." Date divider ("Tue · 17 Apr"). Message bubbles: student text (right-aligned, accent color, "I can't make tomorrow's appointment. Can I move to Thursday?"), coach text reply (left, panel color, "Thursday 2 PM is open, I've moved you"), coach voice-note bubble (playable, 0:22, timestamp "2:14 PM"). Composer: a voice-first row ("Write to your coach…" placeholder text field + a prominent mic button for voice messages), with a gentle weekly-limit line: "2 of 3 messages left this week" — the guardrail from FEEDBACK-SYNTHESIS.md's messaging decision (weekly caps), surfaced as information, not a hard wall in this mock.

Actions. Mic button → records and sends a voice message. Text field → sends a typed message (implementation detail; no distinct compose screen).

Role gating. Student-only surface shown; a mirrored coach-side thread view is implied but not designed in this mockup (Coach app's tabs, per §2, do not include a dedicated Messages tab — treat as a gap to close during build, see §5 if unresolved).

Section F4 — Support & pre-semester

Report an issue — sheet (SakReportIssue)

Purpose. Bottom sheet, reachable from any screen, capturing context automatically so the user only has to describe what happened (FEEDBACK-SYNTHESIS.md top-5 finding #5).

Key content. Presented over the current screen (dimmed/blurred backdrop — mockup shows it over Today, but it can open from anywhere). Title "Report an issue," eyebrow "Something's off?" Auto-attached-context row (dashed border, checkmark icon): "Screen, app version and account attach automatically" with the live example "Today · 2.0.1" shown at right — no user action required to populate this. A free-text field ("What happened? What did you expect instead?"). Two submission modes: "Narrate it instead" (voice) and "Send" (text).

Actions. "Send" or a completed narration submits the report with the auto-attached context (current screen name, app version, account ID).

Role gating. Available from any screen, any role (student or coach — the coach questionnaire specifically requested a narrate-instead option).

Today — state: pre-semester (SakTodayCountdown)

Purpose. Named state of Today (REVIEW.md B1) for the window before a semester begins, so Today has a purposeful screen instead of sitting empty.

Key content. Eyebrow "Sat · 12 Sep," greeting "Salaam, Sarah." Countdown hero (ink): "Fall 2026 · Level II" eyebrow, "Class begins in nine days," date "Monday · 21 September," action "Add start date to calendar." "While you wait" checklist card: "Meet your coach" (Ust. Amina audio welcome, 1 min — done), "Choose your Qur'an script" (done), "Watch the welcome lesson" (not done, chevron).

Actions. "Add start date to calendar" adds the term start to the device calendar. Unfinished checklist rows are tappable (chevron) to their respective tasks (coach intro, font picker, welcome video).

Role gating. None — applies to any account before their semester start date.

Section F5 — Year 2 appointments

Book your one-to-one (SakBookAppointment)

Purpose. Hybrid booking flow for the Year-2 1:1 (FEEDBACK-SYNTHESIS.md decision: pre-book a fixed weekly slot for the whole booking window, or book week-to-week — the "midnight slot-camping" problem this design solves).

Key content. Eyebrow "Fall 2026 · Year 2," title "Book your one-to-one." Two mode cards: "Same time weekly" ("Lock one slot for all 15 weeks", default selected) vs. "Pick each week" ("Choose a fresh time every week"). Coach card: "Ust. Amina · Your coach" with a quiet "Change" link (REVIEW.md A4 — changing coach is a legitimate affordance, not a bug). Slot grid, "Tuesdays · 20 min," zone label "Toronto (EDT)": 8:40 AM (taken), 9:00 AM (free), 9:20 AM (free, selected), 9:40 AM (free), 10:00 AM (taken), 10:20 AM (free). Confirm CTA: "Book Tuesdays 9:20 AM · all 15 weeks" (fixed mode) or "Book Tue 24 Apr · 9:20 AM" (flex mode), with mode-specific reassurance copy ("Travelling one week? You can swap any single session later" / "Book up to two in one week to catch up on a missed one").

States. Mode toggle (fixed/flex) changes the slot-grid semantics, CTA label, and footer copy, but not the grid itself in this mock.

Actions. Confirm CTA → Appointment detail. "Change" (coach) → implies a coach-reassignment flow (not designed here).

Role gating. Year 2 only. Entry points: Sessions tab ▸ calendar icon ▸ "Book your one-to-one," and during Year-2 enrollment/onboarding.

Appointment — recurring weekly (SakAppointmentDetail)

Purpose. Detail screen for a booked 1:1: join, prepare, reminders, calendar, and the three "quiet management" actions coaches and students both asked for (swap, message, cancel without guilt).

Key content. Chips "One-to-one" + "Recurring · Week 8 of 15." Title "Recitation with Ust. Amina." Meta row: Time "Tue · 9:20 AM," Duration "20 min," Where "Zoom." "Prepare" section: this week's passage card ("THIS WEEK · AL-MULK 67:1–5," compact). Primary "Join Zoom" + secondary "Calendar" buttons. Reminder line: "Reminder 15 minutes before · every week." Quiet action card: "Swap this week's time" (keeps the recurring slot for other weeks), "Message Ust. Amina" ("Running late, or a question before class"), "Can't make it? Cancel this week" ("Even a minute before is fine — it frees the slot" — the guilt-free cancellation from FEEDBACK-SYNTHESIS.md's no-show-anecdote finding).

Actions / destinations. "Join Zoom" → Live class (or the 1:1's Zoom session). "Calendar" → adds this occurrence to the device calendar. "Swap this week's time" → opens a reschedule flow (not separately designed). "Message Ust. Amina" → Message thread. "Cancel this week" → cancels this occurrence only, keeping the recurring booking intact.

Role gating. Year 2 only.

Availability — asked during Year-2 booking (SakOnbAvailability)

Purpose. Collects when a Year-2 student can join live sessions, so the live schedule can be shaped around students rather than the reverse (FEEDBACK-SYNTHESIS.md: "hybrid teacher-first/student-exception scheduling"). Per REVIEW.md C5, this is not part of first-run onboarding — it is asked during the Year-2 booking/enrollment context, header converted to SakNavDrill ("Fall 2026 · Year 2" eyebrow, "Availability" title, no onboarding dots).

Key content. Prompt "When could you join a live circle?" with sub-copy "Pick every time that could work — even odd hours. We shape the live schedule around these answers." A 7-day × 5-time-band grid (Early/Morning/Midday/Evening/Late × Mon–Sun), tappable cells. Demo state has 6 cells picked (Tue Evening/Late, Thu Evening, Sat Morning/Midday, Sun Morning). Footer: "6 windows picked · your local time." Primary CTA "Continue."

Actions. Tapping a grid cell toggles that availability window. "Continue" submits the availability set and proceeds in the booking/enrollment flow.

Role gating. Year 2 only, asked during booking — not during core (6-step) onboarding.

Section C — Coach app

The coach tab bar (SakCoachTabBar) defines four tabs: Queue, Students, Schedule, You. This mockup wires artboards only for Queue and Schedule; Students is reached contextually via a submission or schedule row (destination: Student record); "You" (coach's own profile/settings) has no designed screen in this mockup — treat as a gap for engineering to fill by analogy with the student Profile tab.

Coach — review queue (SakCoachQueue)

Purpose. Oldest-pending-first queue of submissions awaiting review — the filter coaches explicitly asked for.

Key content. Eyebrow "Tue · 17 Apr," greeting "Salaam, Ust. Amina." Stat hero: "5 submissions waiting," "Oldest is Sarah's — 2 days. Your 48-hour promise holds." Filter chips: "Oldest first" (default), "By level," "Fewest submissions." Queue rows (avatar-initial, name, level chip, week, duration, waiting time) — e.g. Sarah M. (Lvl II, Week 8, 2:41, waiting 2 days, flagged), Khadija R., Noor A., Hafsa T., Maryam S.

Actions. Tapping a queue row → Coach — review a submission.

Role gating. Coach-only.

Coach — review a submission (SakCoachReview)

Purpose. The unified review workspace — assignment text visible while listening (the #1 gap coaches reported), word-anchored marking, auto-timestamped notes, private-vs-student-facing note split, and side-effect hour logging.

Key content. Eyebrow "Sarah M. · Week 8," title "Review." Assignment passage (tap-to-mark, cite "AL-MULK · 67:1–3 · TAP A WORD TO MARK IT") with two marks already placed. Student's recording (scrubbable, playhead at 1:08 of 2:41). "Your marks" list — each note auto-stamps the playhead time it was placed at (e.g. "تَبَارَكَ — madd too short," marked at 0:41). Note-audience segmented toggle: "For Sarah" (student-facing) vs. "Private — just me" (coach-only) — the split coaches asked for. Note composer placeholder: "Add a note Sarah will see with her feedback…" Actions: "Record feedback" (red mic button) + "Send." Footer: "14:32 on this review · logged automatically" — hours accrue as a side effect of using the screen, replacing the manual Time Clock Wizard.

Actions. Tapping a word in the passage places a new word-anchored mark (implementation detail — the mockup shows two pre-placed marks). "Record feedback" records the coach's audio reply. "Send" submits the review (marks + audio + note) back to the student, transitioning their submission from review to reviewed.

Role gating. Coach-only.

Coach — student record (SakCoachStudent)

Purpose. Per-student history and notes visible to every coach who has taught that student — the cross-coach continuity feature (REVIEW.md A4).

Key content. Identity strip: "Sarah M.," "Level II · Week 8 · 3rd semester." "Working on" tag row (AI-collated from the coach's last 3 notes): "Madd length," "Ghunnah hold," "Pace under nerves." "Submissions" history (same status-pill vocabulary students see): Week 8 "in review," Week 7 "practiced," Week 6 "heard." "Coach notes" — visible to all coaches: a note from Ust. Amina (Week 7) and, notably, one from "Ust. Rania · Week 6 · one-to-one" (REVIEW.md A4 — this is the one legitimate cross-coach reference remaining in the mockup, demonstrating a substitute coach's note is visible to Sarah's primary coach; it is not evidence of a two-coach assignment model).

Actions. Header action icon → message the student (implementation detail).

Role gating. Coach-only.

Coach — my schedule (SakCoachSchedule)

Purpose. The coach's own calendar — group sessions and 1:1s in one place, in the coach's own timezone, replacing the prior workaround of coaches logging into student accounts to find their own class times.

Key content. Eyebrow "Tue · 17 Apr · Cairo (EEST)," title "My schedule." Rows: 2:00 PM "Sisters' Reading Circle" (QRC, "8 registered," live, "Start" button); 4:20 PM "Sarah M. — recitation" (1:1, "Recurring · Week 8"); 4:40 PM "Khadija R. — recitation" (1:1, "This week only") — the exact two-word vocabulary locked by REVIEW.md D1; 7:00 PM "Level II — Idghām review" (Class, "23 registered"). Footer: "Attendance + hours log from Zoom automatically."

Actions. Live row's "Start" button starts/joins that Zoom session. Other rows drill to their detail (implementation detail; not separately designed for group sessions).

Role gating. Coach-only. Confirms REVIEW.md A5's timezone math: the student's 9:20 AM Tuesday booking in Toronto (EDT) is this coach's 4:20 PM Tuesday in Cairo (EEST) — a 7-hour offset, computed from the same UTC instant.

Section 01 — Lesson & recording

Lesson — Idghām with ghunnah (SakLesson)

Purpose. The weekly lesson's three-step loop: Watch → Record → Hear back, one āyah at the center.

Key content. Title "Idghām with ghunnah" + one-sentence description. Āyah focal card (Al-Mulk 67:1, single verse, generous type). Step 1 — Watch: video list with progressive disclosure — the current "Up next" video gets a hero card ("Practice reading aloud," 5 min); the two already-watched videos ("What is Idghām?," "Ghunnah letters — ي ن م و") collapse behind a "2 watched · Show" toggle. Step 2 — Record: a recital "plate" (dormant waveform hint), primary CTA "Begin recording," attempt dots (0 of 2 used), deadline line "Due Sunday · 11:59 PM" (REVIEW.md A3 — corrected from a hardcoded "tonight"/EST string). Step 3 — Hear back: the most recent coach note as an inline playable card (Ust. Amina, "Week 7 · 2 days ago," waveform, quoted text).

States. Step 1's watched-videos list is collapsed by default (progressive disclosure); Step 3 only appears once feedback exists for a prior submission.

Actions. Tapping "Up next" video or a row in the expanded watched list → Video player. "Begin recording" → Recording — Ready. Tapping the Step 3 feedback card → Submission — feedback ready.

Role gating. Student-only.

Video player — chapter complete (SakVideoPlayer)

Purpose. In-lesson video playback with a chapter (video-list) sidesheet and a completion banner.

Key content. Video stage (dark plum) with a "Video 3 of 3" chip, center play/pause glass button, and a scrubber. Shown state: 92% progress (just past the 90% completion threshold), so the "Marked as watched" banner is visible. Title block: "Week 8 · Idghām with ghunnah" eyebrow, "Practice & examples" title, "Recite alongside Ust. Amina · 4:00." "In this chapter" video list (all 3 videos, current one highlighted "Now"). Primary CTA "Record submission" + secondary "Lesson." A collapsed transcript teaser with "Read full transcript."

States. Mid-watch (any progress <90%) vs. completed (≥90%, banner shown).

Actions. "Record submission" → Recording — Ready. "Lesson" (secondary) → back to Lesson. Video list rows → play that video (same screen, different video loaded).

Role gating. Student-only.

Recording — Ready (SakRecReady)

Purpose. Entry state before recording begins.

Key content. Shared recording header (SakRecHeader): title "Submission," close (x) action, attempts indicator ("Attempts this week" + dots, default 2 of 2 remaining). Verse card (full). Center: a breathing red mic button, prompt "Tap to begin recording."

Actions. Tapping the mic button → Recording — In progress. Close (x) → exits back to Lesson without starting a recording.

Role gating. Student-only.

Recording — In progress (SakRecRecording)

Purpose. Live recording state.

Key content. Same header (attempts unchanged since nothing has been submitted yet). Compact verse card. Live indicator: blinking red dot, "Recording," elapsed time (e.g. "0:23"). Animated live waveform. Center: red stop button (square icon), prompt "Tap to stop," sub-copy "You can re-record after listening back."

Actions. Tapping stop → Recording — Review.

Role gating. Student-only.

Recording — Review (SakRecReview)

Purpose. Playback and decision point before submitting: keep or re-record.

Key content. Header + compact verse card. "Your recording" duration (0:47). Waveform playback card with elapsed/total time. Play button (FbPlayBtn — per REVIEW.md D2, replacing a prior bespoke 54px play circle) + "Re-record" button. Primary CTA "Submit to Ust. Amina" with footer "Feedback within 48 hours."

Actions. "Re-record" → back to Recording — In progress (does not decrement attempts — only an actual submission does). "Submit to Ust. Amina" → Recording — Submitted, decrements attempts by one and starts the revoke window.

Role gating. Student-only.

Recording — Submitted (SakRecSubmitted)

Purpose. Confirmation state immediately after submitting.

Key content. Header shows attempts now at 1 of 2 remaining (post-decrement). Animated check medallion. "Recording submitted," body "Your coach Ust. Amina will listen and send notes within 48 hours." Primary CTA "View my submission." Per REVIEW.md A1, this screen carries no revoke countdown — that UI lives solely on SakSubmissionPending.

Actions. "View my submission" → Submission — in review · revoke window (SakSubmissionPending) — i.e., this is not a dead end; it routes into the submission detail where the actual revoke window lives.

Role gating. Student-only.

Recording — No attempts (SakRecNoAttempts)

Purpose. Terminal state once both weekly attempts are used without a passing/accepted result.

Key content. Header shows 0 of 2 attempts remaining (danger-tinted). Compact verse card. Crossed-out mic icon. "Both attempts used," body "You've recorded twice this week. Your next attempt opens on" + date pill ("Monday · 9 March"). Reassurance copy: "Rest is part of the practice. Listen to your coach's notes while you wait." Secondary action "Hear coach's notes."

Actions. "Hear coach's notes" → Submission — feedback ready (or whichever submission detail holds the most recent feedback).

Role gating. Student-only.

Section 02 — Identity sub-pages

Coach detail (SakCoach)

Purpose. Destination from Profile's coach panel / "Message" CTA — coach identity, feedback history, and upcoming sessions with that coach.

Key content. Hero card: portrait initial, "Ustadha Amina," "Cairo · ijāza in Hafs from 'Āsim," three inline stats (6 reviewed, 48h reply window, L1–2 levels). Primary CTAs: "Message Ust. Amina" (REVIEW.md B5) + secondary "Office hours." "Recent feedback" list — time-grouped, playable audio-note previews with quoted excerpts; 2 shown by default, "Show N earlier notes" reveals the rest (progressive disclosure). "Upcoming" section: sessions with this coach (e.g. Tue Feb 25, 2:00 PM QRC; 9:00 PM Office hours).

Actions. "Message Ust. Amina" → Message thread. "Show N earlier notes" expands the feedback history in place.

Role gating. Student-only.

Submissions archive (SakSubmissions)

Purpose. Full history of weekly submissions, time-grouped, progressively disclosed past the current month.

Key content. Summary stat hero: "Since September," "7 submissions, 1 in review," week strip. "This month" group (4 rows): Week 8 "Al-Mulk 67:1–3" — status review ("In review," muted tint — this is the in-flight submission SakSubmissionPending tracks, per REVIEW.md A2); Week 7 "Al-Mulk 67:1" — status reviewed ("Feedback ready," warm/gold tint — REVIEW.md A2's canonical week-7 state); Week 6 — heard; Week 5 — reviewed. "Earlier" group (3 older rows, weeks 4–2, all heard) is hidden behind "Show 3 earlier submissions" until tapped.

States/status vocabulary (SubStatusPill, locked by REVIEW.md A2): review = "In review" (muted/ink tint) → reviewed = "Feedback ready" (warm/gold tint) → heard (green tint) → practiced (accent/plum tint). These four states describe the full loop for one submission from arrival to practiced-and-closed.

Actions. Tapping a row → the corresponding submission detail screen (Submission — feedback ready for reviewed/heard/practiced rows, Submission — in review for the review row). "Show 3 earlier submissions" reveals older weeks in place.

Role gating. Student-only.

Personal details (SakPersonalDetails)

Purpose. Read-mostly account/identity form.

Key content. Nameplate (avatar + "Sarah Ahmed" + "Joined · Sep 2024"). Identity group: Full name, Pronunciation (optional phonetic hint), Date of birth. Contact group: Email, Phone, Timezone: "Toronto · Eastern (EDT)" (REVIEW.md B3 — one canonical city per account). Class group (both rows readonly, locked-pill): Level ("II · Reading with fluency"), Cohort ("Tuesday 2 PM local" — REVIEW.md B3's normalized cohort copy). Footer note: "Class details are managed by your coach."

Actions. Editable rows (Identity, Contact) → per-field edit (chevron). Class rows are locked (not editable by the student).

Role gating. Student-only.

Qur'an font picker (SakFontPicker)

Purpose. Live-preview font selection for Qur'anic text rendering, plus size control.

Key content. Three font cards (Amiri Quran / Amiri / Naskh), each rendering a live preview verse in its own face; selected card shows a check badge. Size slider (18–36pt) with "Smaller"/"Larger" labels. A live preview card at the bottom reflecting the currently selected font + size.

Actions. Tapping a font card selects it (updates the preview immediately). Dragging the slider updates size across all previews live.

Role gating. Student-only (implied also available to coaches for their own reading preference, though not designed separately here).

Notifications sheet (SakNotifSheet)

Purpose. The notification inbox.

Key content. Title "Notifications," "Mark all" action. Pinned row: "Announcements · 1 pinned" (megaphone icon) — deep-links to the Announcements board (REVIEW.md C1a), sitting above "New" so it reads as a fixture, not a transient note. "New · 2" section: "Feedback ready — Week 7" (unread), "QRC starts in 15 min" (unread). "Earlier" section: "Submission due today," "Schedule change — Week 9" (announcement type — copy matches the board exactly per REVIEW.md B4b: "Thursday's Level Class moved to 11:00 AM"), "Feedback ready — Week 6." Footer: "That's all from this fortnight."

States. Unread rows show bold title + gold dot + tinted background.

Actions / destinations.

Role gating. None (student view shown; a coach-side equivalent is implied but not designed).

Notification settings (SakNotifSettings)

Purpose. Per-type push/email notification preferences.

Key content. Master switch card: "Push notifications," "On · 4 types," toggle on. Types group (each with its own toggle, all default on): "Session reminders" ("15 min before a live session"), "Feedback alerts" ("When your coach replies"), "Deadline reminders" ("Submission due dates"), "Announcements" ("Schedule changes & program updates") — default ON per REVIEW.md B4a, a change from the prior default-off behavior. Email group: "Weekly digest" ("Your progress, every Sunday morning") — default off. Footer: "You can fine-tune sounds and previews in your device's Settings app."

Actions. Each toggle sets that notification type's on/off state independently; the master switch is a convenience toggle for all push types together.

Role gating. Student-only screen shown; role-appropriate equivalents (coach notification prefs) are implied but not designed.

Section 03 — Live class

Live class — Sisters' QRC (SakLiveClass)

Purpose. In-session live-class screen, reached by tapping "Join" on any live session row across the app.

Key content. Dark (ink) full-bleed screen — deliberately no tab bar (a focused screen, back chevron only). Header: live indicator + elapsed time ("Live · 14:22"), title "Sisters' Reading Circle." Speaking-coach hero card: "Ust. Radwa" with an animated speaking ring around her avatar (indicates who is currently talking). "In the circle" participants strip (horizontal scroll, "8 of 12," "You" highlighted first). "Currently reading" card: live verse text (Al-Mulk 67:3) synced to what the coach is reading aloud. Bottom control row: Mute, Camera, Raise hand (warm-tinted), Leave (danger-tinted, red).

Actions. "Leave" exits the live class (returns to the screen that launched it — Today, Sessions, or Appointment detail). Mute/Camera toggle local AV state. "Raise hand" signals the coach.

Role gating. Available to whichever role joined the session (student for group circles and 1:1s; the same screen would serve a coach starting their own session, though the coach-start flow is on SakCoachSchedule's "Start" button, not designed as a distinct screen here).

Section 04 — Enrollment

Subscription & billing (SakSubscription)

Purpose. Current-semester enrollment status as a "passport," not a paywall — reframing subscription management around the semester's identity rather than transactional billing.

Key content. Passport card (ink): "Current semester · Active," "Level II / Spring 2026," term ledger (Term: "Jan 12 – Jun 22," Paid: "$149.00"), progress ribbon ("Week 8 of 15," 53%). "Next semester" quiet dashed card: "Level III · Fall 2026," pill "Opens Sept," copy "You'll receive an email to review and confirm before any charge." "Payment method" card (Visa •••• 4242, expires 08/27). "Ledger" — payment history (3 rows, all "paid"). CTA "Manage subscription."

Actions. "Manage subscription" → Manage subscription. Payment method row → update card (implementation detail).

Role gating. Student-only.

Manage subscription (SakManageSub)

Purpose. Deeper billing controls, framed so the destructive "cancel" action feels considered rather than casual (a deliberate design choice, per the component's own code comments).

Key content. "Current plan" summary (Level II, Spring 2026, "Week 8 of 15 · ends June 22, 2026," Paid $149.00). "Next semester" card with pricing options when enrollment opens ("$149 once" or "$55/mo three months") and pill "Not yet open." "Billing" group: Auto-renewal (on, "Confirmation required before each charge"), Update payment method, "Stripe billing portal" (invoices, receipts, tax info — REVIEW.md-adjacent audit note: the duplicate Stripe portal link elsewhere was dropped, this is the sole entry point). Contemplative cancel area, set apart with generous whitespace and an italic epigraph ("Rest is part of the practice. Pause is a choice, not a loss."), with a quiet outlined "Cancel enrollment" button (danger-tinted text only, not a filled destructive button — deliberately de-emphasized).

Actions. "Stripe billing portal" → hands off to Stripe's hosted portal. "Cancel enrollment" → begins the cancellation flow (confirmation step implied, not designed).

Role gating. Student-only.

Section 05 — Onboarding

Six steps, each a "frontispiece" page inside a shared OnboardingShell (back chevron + step-dot progress + "Skip," a primary "Continue"/"Begin" pill at the foot of each step).

  1. Welcome (SakOnb1) — QuranFlow seal, "Sarah, welcome to QuranFlow," one sentence ("A quiet, weekly rhythm for learning to read the Qur'ān well"). CTA: "Begin."
  2. Your level (SakOnb2) — Roman-numeral medallion ("II"), "Level II · Reading with fluency," reassurance line ("you begin here — neither at the start nor the end, but at the right page").
  3. Choose script (SakOnb3) — three font cards (Amiri Quran / Amiri / Naskh) with live Bismillah preview in each; Amiri Quran pre-selected. Footnote: "You can change this any time in Settings."
  4. Your coach (SakOnb4) — coach medallion with a verified checkmark badge, "Ustadha Amina," "Cairo · ijāza in Hafs from 'Āsim," two bullet facts: she listens weekly and replies with 1–3 min audio; she answers follow-up messages within 48 hours.
  5. The weekly rhythm (SakOnb5) — three numbered steps on a connecting thread: 1 Watch your lesson (2–3 short videos, ~12 min total), 2 Recite the āyah (record once, two attempts), 3 Hear back from Ust. Amina (audio reply within 48 hours).
  6. Live circles (SakOnb6) — three session-type cards: Reading Circle (QRC — small-group real-time coaching), Level class (group lesson, whole Level II cohort), Office hours (1-on-1 coach drop-in). Reassurance: "Can't make it? Every circle is recorded." CTA: "Begin your week."

Role gating. Core onboarding is 6 steps for every student, Year 1 or Year 2 (per REVIEW.md C5, the Year-2 Availability step is asked separately, during booking — not inserted into this sequence).

Section 06 — States

Edge/empty variants of screens already specified above — same chrome, different content, so they read as states of one screen rather than separate designs.

Today — state: rest day (SakTodayRest)

A quiet (paper, not ink) variant of Today for a day with nothing due — shown here as the Sunday after Week 8's submission. Hero: "Rest the eye today," body explaining the last submission's status ("with Ust. Amina — feedback usually comes by Tuesday"), week strip (done=8, no "current" marker since nothing is due today). "If you have ten minutes" optional suggestions: "Re-read this week's verse" (2 min), "Listen to last week's circle" (48 min). Quieter verse closer. No primary CTA — the absence of one is itself the message.

Profile — first week (SakProfileFirstWeek)

Minimal frontispiece variant for a brand-new student ("Week 1 · Day 2," "The beginning is dignified," seat reservation copy). "Next steps" checklist: "Meet Ust. Amina" (done, 5 min audio), "Record your first verse" (current, Al-Fatiha, due Friday), "Attend a live circle" (Tuesday 9am, not started). Quiet stat row shows em-dashes for streak/submitted counts rather than zeros — framed as a beginning, not a deficit.

Submissions — empty archive (SakSubmissionsEmpty)

Same nav/eyebrow ("Archive," "Your submissions") as the populated archive. Empty-state card: "No recordings yet," explanatory copy, CTA "Record your first." A quiet schematic list ("What lives here"): Audio attempt, Coach response, Notes & corrections — previewing the archive's eventual structure before it has content.

Notifications — all caught up (SakNotifEmpty)

Same nav as the populated Notifications sheet. Empty-state card: "All caught up," "Nothing new since Tuesday's office hours." "Earlier this week" section retains one dimmed, already-read row so the shape of the list persists even when there's nothing new.

Recording — mic permission (SakRecPermission)

Bridges Ready state with the OS-level microphone permission prompt, framed as an invitation ("Open the microphone") rather than a warning. Reuses the recording header (2 of 2 attempts) and compact verse card. Broken-halo mic glyph (dashed rings, not the solid breathing red of Ready). Primary CTA "Allow microphone"; secondary text link "Open Settings instead" for a previously denied permission.

Deep-link-only screens (not on the canvas; notification destinations)

Per REVIEW.md C4, these two screens exist in the codebase (sak-schedule.jsx) but have no on-canvas entry point — they exist solely as the destination when a student taps a session-reminder push notification.

Session detail — Class variant (SakSessionDetail)

Example instance: "Fluency drills," "Today · 12:00 PM," Ust. Radwa, 45 min, Zoom. Sections: "What we'll cover" (3 numbered rows — Idghām review, paired reading, live correction), "Bring with you" (reading passage + a short pre-watch video), "Cohort" (avatar stack, "6 of 8 confirmed"). Primary CTA "Open Zoom" + secondary "Remind me."

Session detail — QRC variant (SakSessionDetailQRC)

Example instance: "Sisters' Reading Circle," "Today · 6:00 AM · Live," Ust. Radwa, 60 min, Zoom. Sections: "This week's reading" (verse card, Al-Mulk 67:1–10), "How the circle runs" (3 numbered rows — opening recitation, round-robin recitation, coach's notes), "Sisters here" (avatar stack, "8 of 10 joined"). Primary CTA "Join Zoom" + secondary "Remind me."

Both share a common SessionDetailFrame (title block, meta row, coach card, body sections, primary/secondary CTA pair) so a third session type can be added later as a content change, not a new design pass.

4. Business rules

These rules are drawn from the coach-feedback synthesis (FEEDBACK-SYNTHESIS.md) and locked by REVIEW.md's adjudicated resolutions. They apply across every screen that touches the relevant object — an engineer should treat them as constraints on the data model, not just copy.

5. Open questions / deliberately unresolved

Documented here rather than in the mockup, per REVIEW.md's "Out of scope for the mockup" list — these need a product/engineering decision before or during build, not a mockup screen.