QuranFlow iOS App — Requirements Traceability Matrix

Part of the production handoff package, alongside FEEDBACK-SYNTHESIS.md (the synthesized stakeholder asks) and handoff/PRODUCT-SPEC.md (the screen-by-screen functional spec). This document's job is narrower and mechanical: prove that every stakeholder ask landed somewhere — designed, deferred, or rejected — so nothing silently fell through between the four feedback sources (Coaches' Questionnaire, IT Revamp Discussion transcript, App Wishlist, Mock App Feedback) and the finalized Sakīna mockup at ../mockup/.

Sources checked against: FEEDBACK-SYNTHESIS.md, ../mockup/REVIEW.md (adjudicated design decisions), ../mockup/src/main.jsx (finalized screen inventory — artboard labels are cited as design evidence below), spot-checked against the individual ../mockup/src/sak-*.jsx files, and — where the synthesis summarized rather than quoted — the raw source files in /feedback for new app/ (the Coaches' Questionnaire responses, the App Wishlist, the IT Revamp transcript, and the Mock App Feedback doc).

Jul 24 2026 product correction (Lejla) — what changed

Added Jul 26 2026. A product review with Lejla (PM) and Kamran on Jul 24 2026 corrected the Year-2 model and added a new-student entry flow. The affected asks are re-dispositioned here; the specific matrix rows in §2 are annotated in place (not renumbered). Source: the flow map, ../../explorations/flow-map/ (screens designed in the shared Sakīna kit, Jul 26 2026). Working defaults await Lejla's confirmation — see ../../explorations/flow-map/QUESTIONS-FOR-LEJLA.md.

• Year 2 has no weekly submissions. Appointments replace them (up to 3/week, any coach on the team, included in tuition); feedback arrives as per-appointment teacher's notes. Earlier docs modelled Year 2 as "everything Year 1 has, plus a 1:1" — corrected across PRODUCT-SPEC and DATA-MODEL.
• Per-appointment, multi-coach booking supersedes the single-recurring-slot model for Year 2. The "Hybrid 1:1 booking" row (Schedule / time) is annotated below: recurring "lock all 15 weeks" is dropped pending Q13; Year-2 appointments book per week and need not be with the same coach. The "Two-coach model — rejected" row (Strategy items) still stands for Year-1 assigned-coach review routing but no longer constrains Year-2 booking — a shared coach pool is not a two-coach assignment.
• Appointment notes are now Designed. The "Notes + voice notes for one-to-one appointments" row (Appointments) previously read Designed only via SakCoachStudent text, "no separate voice-note UI built." Jul 26 2026 added dedicated screens: Coach — appointment notes (record → transcribe → auto-summary → coach edit → send) and the student-facing Appointment — teacher's notes (AppointmentNote entity, DATA-MODEL §2). That row is annotated below.
• Entry / placement flow is now Designed. New: a web-registered student signs in via an emailed link, books a first assessment, waits for placement, and receives a level before ever seeing the Year-1 loop. Four new screens (Sign in, Book your first assessment, Waiting for placement, Placement result) in PRODUCT-SPEC Section E; the account/enrollment state machine is in DATA-MODEL §2. This was not an original stakeholder ask — it comes from the Jul 24 correction — so it has no prior matrix row; it is recorded here as Designed.

Jul 27 2026 product correction (Lejla) — what changed

Added Jul 27 2026. A screen-by-screen review with Lejla on Jul 27 2026 (decision record: ../../reviews/App-Review-Jul27-Lejla.md, the binding source for this pass) overturned five Jul-24 defaults and reshaped the entry lane. The five corrections are tracked as answered questions in ../../explorations/flow-map/QUESTIONS-FOR-LEJLA.md (Q1, Q2, Q4, Q5, Q8); the derived design changes are encoded across the walkthrough, the flow map (v7), the ambient layer (v3), and the two handoff specs. This addendum maps each Jul-27 decision to the record section it comes from and the artifacts that encode it. It adds no new stakeholder asks (those were dispositioned Jul 24) — it re-dispositions the entry/placement and Year-2 rows already annotated in §2.

Open items from this pass (nothing "encodes" them yet — they need Lejla): Q15 the exact name of the mandatory Year-2 semester (tentatively "Advanced Tajweed Rules", distinct from the Tajweed Practice elective); Q16 the student-facing rename of the first assessment ("Your first recitation" proposed; coach side keeps "First assessment"). Both are recorded in QUESTIONS-FOR-LEJLA.md.

Aug 5–6 2026 design review (Lejla + Sr. Yasmine) — what changed

Added Aug 10 2026. Lejla and Sr. Yasmine (coach and curriculum manager) reviewed the redesign screen by screen against the flow map over two recorded sessions (transcripts: ../../reviews/QF-App-Feedback-Yasmine-Lejla-session-1-Aug-5-2026.txt and …session-2-Aug-6-2026.txt, the binding sources for this pass). The remarks reconcile to a 119-item register (../../reviews/v12-review-response/unified-register.json, U-001–U-119); the decisions were built into walkthrough v12 (decision record: ../walkthrough/DECISION-LOG.html §v12) and the flow map. The illustrated summary — before/after captures per change — is ../../reviews/v12-review-response/index.html, deployed at https://quranflow-redesign.pages.dev/changes/. The review covered S01–S33 plus S37 and S42; S34–S51 and the coach lane (C01–C09) were not reviewed — a third session was planned to resume at S33.

Screen numbering changed in this pass. Codes are now sticky (a retired number is never reused; new screens append). The ledger at ../walkthrough/build-notes/screen-codes.md is the authority. Retired: S10, S11, S20, S27, S28. New: S52–S59.

Spec sync pending: these decisions are encoded in the walkthrough build and the flow map; PRODUCT-SPEC and DATA-MODEL have not been re-cut for them yet. Wording on new and revised screens is directional pending Sr. Yasmine's screen-by-screen copy pass. Open policy questions from the review (booking limits and no-shows, passing criteria, the behind-students protocol, where student-coach messaging lives) are listed in the change document's open-questions section — they block spec rows, not the build. The Aug 6–11 section below extends this same list — the spec now trails two rounds, not one.

Aug 6–11 2026 — session 3, the coach review and the Aug 11 pass — what changed

Added Aug 11 2026. Four binding sources close the review of the whole app: session 3 (Aug 6, Lejla + Sr. Yasmine, resuming the student walk at S33/S34 — ../../reviews/QF-App-Feedback-Yasmine-Lejla-session-3-Aug-6-2026.txt); the coaches-app session 1 (Aug 6, the first review the coach lane C01–C09 has ever had — …COACHES-APP-Yasmine-Lejla-session-1-Aug-6-2026.txt); Lejla's coach-side audit written against the April 2026 coach survey of 11 responses, which is evidence about how coaches work today rather than a reaction to the drawn screens (U-244 — ../../reviews/QuranFlow-Coach-Side-Audit.md); and the Aug 11 Kamran + Lejla meeting walking the v12 change document screen by screen (../../reviews/App-Review-Aug11-Lejla.md) — mobile part only, since that meeting pivots to the admin portal about halfway through and the admin half is excluded from this round and revised separately. The remarks reconcile to a 284-item register (../../reviews/v13-review-response/unified-register.json, U-120–U-403, continuing the v12 numbering), adjudicated in ../../reviews/v13-review-response/adjudication-brief.md and built into walkthrough v13 (decision record: ../walkthrough/DECISION-LOG.html §v13). The illustrated before/after summary is the v13 change document at https://quranflow-redesign.pages.dev/changes-v13/; v12's stays at https://quranflow-redesign.pages.dev/changes/, because links already shared keep showing what they showed when they were sent.

Coverage, honestly stated. With this round the whole app has been reviewed. The student side S01–S59 has now been seen twice — once against the flow map, once via the v12 change document — and the coach lane has been seen once: the coach session ended early and neither reviewer exhausted her list (U-242), and Sr. Yasmine owes a further document covering anything major in the coach feedback the app does not yet address (U-241). Sr. Yasmine's screen-by-screen copy pass still gates all wording (U-353); nothing in v13 is settled copy.

Sticky-code ledger delta. Codes remain sticky — a retired number is never reissued, new screens append — and ../walkthrough/build-notes/screen-codes.md is still the authority. Retired this round: S18 (pre-semester Today; now a countdown bar on the ordinary Today with locked items greyed), S36 (teacher's notes, folded into S35) and S40 (week at a glance, whose job moved to the month calendars) — joining S10, S11, S20, S27 and S28. New student codes S60–S71: S60 a submission that came back rejected · S61 resources with a home of their own · S62 the day's open booking times · S63 the conflict screen for a recurring booking · S64 the live month behind the Sessions calendar button · S65 the booked semester on the Appointments calendar · S66 subscription and billing · S67 learning history as previous enrollments · S68 previous levels inside the learning space · S69 the Assignments tab before placement · S70 Learn before a level is set · S71 a past 1:1 and the notes that stay. New coach codes C10–C18: C10 the coach's day ahead of the queue · C11 placement on its own screen · C12 a student's short reply to feedback (proposal) · C13 the live-class surface (proposal) · C14 the curriculum and resources · C15 her inbox · C16 hours · C17 every one-to-one, past and upcoming · C18 an announcement in her own name. C19 is reserved. (C12, C13 and C17 were retired on Aug 18 2026 — see the Aug 18 section below.)

Aug 12 post-review pass (Kamran's review of the finished build; rulings in reviews/v13-review-response/wiring/ORCHESTRATOR-RULINGS.md): the Today header carries the bell alone — U-184's three-circle quick-access row (a suggestion, built Aug 11) was overruled the next day as more toolbar than the field guide's "context + local actions" allows; U-138 still holds through the bell-as-one-inbox (U-172) and the foot-of-Today announcement preview (U-164). Resources' home-level door is a row on Learn (both states, S42 and S70), pushing S61 — U-151's disposition is unchanged, its door moved. The page ground stays the 3% plum wash app-wide (U-179); a generation-split ground was rejected. The hub landing now leads with "Open the app" as the closest to end usage.

Spec sync pending: PRODUCT-SPEC and DATA-MODEL now trail both rounds — the Aug 5–6 review above and this one. Wording across v13 stays directional until Sr. Yasmine's copy pass. The parked policy questions from this round (whether the reply channel and the live-class surface exist at all, where messaging lives, the late-cancellation and availability rules, passing criteria, the placement rubric, the finance-side half of hours) block spec rows, not the build; they are listed in the change document's open-questions section and in the adjudication brief's "Parked" list.

Aug 18 2026 — messaging, the coach tab bar, and the state model that was missed — what changed

Added Aug 18 2026. One binding source: the Aug 18 review meeting (Kamran, Sr. Yasmine, Lejla — ../../reviews/App-Review-Aug18-Lejla-Yasmine.md), walking a slide deck Sr. Yasmine had assembled from feedback forwarded by many teachers and students. Deck items are therefore third-hand, and nearly every one of them was adjudicated live by the three in the room. The remarks reconcile to a 43-item register (../../reviews/v14-review-response/register.json, U-404–U-446, continuing v13's numbering), adjudicated in ../../reviews/v14-review-response/adjudication-brief.md and built into walkthrough v14 (decision record: ../walkthrough/DECISION-LOG.html §v14). The illustrated before/after summary is the v14 change document at https://quranflow-redesign.pages.dev/changes-v14/; v13's stays at /changes-v13/ and v12's at /changes/, because links already shared keep showing what they showed when they were sent. A small, sharp round on a build people like — Sr. Yasmine, on the record, reports "the bazillion messages of this is so cool" from the coaches.

The repeat item, stated plainly. U-341 ("one submission state model, student- and admin-side alike") was decided Aug 11 and did not reach the v13 build: the build guide translated it additively — the union gains rejected and revoked — so nobody removed practiced and heard, which were still in the code on Aug 18 (submissions-archive.tsx:93, coach-student.tsx:101). Lejla caught it in the meeting. U-435 is that same ask, shipped, and it shipped first: the model is unsubmitted → awaiting review → in review (locked) → reviewed, with rejected and revoked as exits, one vocabulary in both seats — Awaiting review / In review / Feedback ready / Returned / Taken back to the student, Needs review / In review / Feedback sent / Returned / Taken back to the coach. The two retired words are gone from types, fixtures, chips, filters and copy, and a mechanical assertion on the built HTML now fails the build if either reappears. The U-120/U-341/U-342 row above is closed by this; the class of failure it belongs to is closed by the assertion.

Sticky-code ledger delta. No new codes this round; three retired, per the same ledger rule, in ../walkthrough/build-notes/screen-codes.md. C12 (a student's short reply to feedback) and C13 (the live-class surface) were v13's two "proposal — decision needed" screens and are both now answered: C13 is rejected outright — sessions run in Zoom and marking a 250-name roster is unworkable (U-418) — and C12 is accepted in another form, the reply channel living as a week-tagged thread in the coach's one inbox (U-426), so the separate surface retires rather than being cut. C17 (every one-to-one) retires with the Appointments tab, its content folded into C07 behind the Live classes / Appointments filter (U-414). They join S10, S11, S18, S20, S27, S28, S36 and S40 as never-reissued.

Answered in the meeting, nothing to build: Resources' placement on Learn re-affirmed (U-422) · the week strip on S38 is fine and the month calendar already exists behind the calendar button (U-423) · "message your teacher" stays tucked in You, because friction there is a feature (U-425) · Today's announcements window as built (U-430) · messaging from an announcement rejected, since announcements come from admin and often concern another teacher (U-431) · "display settings don't work" is a mockup artifact and moot anyway, the section being removed by U-433 (U-429) · three uninterpretable deck items skipped (U-444).

Parked to the admin track (documented here, excluded from this round): U-407 an alarm when a submission passes about four days waiting — an admin-dashboard concern, not a coach-app surface, and Sr. Yasmine believes it may already exist; U-409 coach notes as their own tab in the admin portal, separate from admin notes (Kamran proposed one filtered list; Lejla held that academic content and account/billing content are "not even close", and he accepted the separation); U-410 coach pickers listing only active coaches, alphabetically, never the full historical roster; U-419 a join-click count per live session, associated with that session and reportable — the attendance and donor number that replaces self-reporting and Zoom-stat archaeology, and a data-model line for the dev handoff (a join-click event per student and session). The Kamran + Lejla backend review (~Aug 19) takes these four as its agenda seed.

Open and owed. U-437 — an exception in rescheduling, so a student can move to another time soon without being blocked by next week's booking — was read off the deck and never adjudicated: the conversation moved to the Mon–Sun booking window and did not return. It is Lejla's call and bundles with the end-to-end booking walkthrough she and Sr. Yasmine owe (U-443). Sr. Yasmine's screen-by-screen copy pass still gates all wording, and the vibe pass (U-445 — keep the craft, add warmth) is its own track, agreed with Kamran before any design work starts; nothing in this round depends on it.

Spec sync pending: PRODUCT-SPEC and DATA-MODEL now trail three rounds. Their submission-status vocabulary in particular (in_review → reviewed → heard → practiced) is superseded by U-435's model above; the correction is annotated in place in both files and in DESIGN-SYSTEM §5 rather than re-cut, so no reader takes the old four states as current while the spec pass is outstanding.

1. How to read this document

Every ask gets exactly one status:

"Designed" is a claim about the mockup, not about shipped code — the mockup is the design evidence; implementation fidelity is verified separately during build QA.

2. The matrix

Coach review workspace

Feedback loop

Schedule / time

Communication

Appointments

Attendance / data

Support / launch

Student experience

Coach prep / compensation

Strategy items

3. Backlog — deferred items restated for pickup

Each entry: what was asked, why it's valid, and what's unresolved so the next pass doesn't start from zero.

1. Student-centric QRC/live-session scheduling algorithm. The IT call surfaced a real tension: today's live-class schedule is built around teacher availability, then students adapt. The program lead proposed inverting this — collect student availability first, then shape the schedule (and staffing) around it. The unresolved question is cost vs. value: a student-first model may require recruiting additional coaches for odd-hour slots (e.g., late evening for one region, early morning for another) or accepting scheduling strain on existing coaches. No decision was made on whether the value (fewer missed sessions, less "student adapts to us" friction) justifies that staffing cost. Pick this up as a staffing/ops modeling exercise before it becomes a design task — the app can display whatever schedule results, but the policy has to be decided first.

2. 20 appointment credits per semester (make-up sessions for Year 2). Raised in the IT discussion as a Year-2 lifecycle feature — a bank of credits a student can spend to book make-up 1:1s beyond their normal recurring slot. Not designed because the credit-consumption rules (what burns a credit, whether unused credits roll over, interaction with the recurring-vs-flex booking split already built in F5) weren't specified. Needs a small spec pass before it's a screen. Revised Jul 26 2026 (Lejla, Jul 24): the Year-2 model now includes appointments in tuition with a soft cap of 3/week and per-week booking (recurring dropped, Q13). A separate "make-up credits" bank may be redundant with the soft cap — revisit whether it is still wanted before designing it.

3. AI feedback summaries. An AI-generated summary of a coach's audio/text feedback, shown to both coach and student as a quick-reference overview. Flagged by Yasmine and others in the questionnaire and listed as an explicit backlog item in FEEDBACK-SYNTHESIS.md. Depends on production feedback-text/transcript data existing at volume; treat as a v2 layer on top of the already-built SakSubmissionFeedback object, not a new screen.

4. AI post-session survey analysis. The IT call decision was: automated post-session survey loop (did the student attend? if not, why?) with AI-aggregated trends — called out as "a priority even ahead of the app." The survey trigger and delivery is straightforward (push a short survey after a missed or attended session); the AI-aggregation/trend layer is the deferred part. Needs a decision on where aggregated trends surface (coach dashboard? program admin?) before designing that view.

5. Lesson asset banks for coaches (slides, games, practice exercises per lesson). Raised by Radwa specifically to address uncompensated prep time — "that would be time off the clock for the teacher." Not a student-facing screen; would live in the Coach app as a per-lesson resource shelf. Needs content production (someone has to build the actual assets) before it's a design problem.

6. Peer community channel revival. The IT call's messaging decision (1:1 + announcements) explicitly replaced the open community board, but Ibrahim separately wants students able to stay in touch with each other, remind one another what was covered, and share notes. This is a distinct ask from the rejected-and-replaced community board — it's peer-to-peer, not coach-broadcast-to-many. Revisit as a moderated peer channel (not a return to the unmoderated board) if student isolation becomes a retention problem.

7. Embedded Zoom. Multiple coaches (questionnaire) wanted Zoom launched/embedded from within the app rather than a separate login — "an online portal... Zoom embedded so I don't have to log in separately." Currently the mockup's live-class flow (SakLiveClass, section 03) implies an "Open Zoom" action but does not embed the Zoom SDK. Real engineering lift (Zoom SDK integration, auth passthrough); scope as its own workstream.

8. Desktop coach portal. Ibrahim Abou Arab explicitly asked for "a dedicated teachers' portal (desktop/laptop)... prefer working on a larger screen, with a keyboard and more structured workspace," and the questionnaire's device-split question shows 5 coaches mobile-only, 4 both, 1 (Ibrahim) desktop-only. The Coach app in this mockup is phone-first — all four Coach-app artboards (SakCoachQueue, SakCoachReview, SakCoachStudent, SakCoachSchedule) are 390×844 device frames. Ibrahim's desktop preference is unmet in v1. This is not merely "make it responsive" — a desktop review workspace (keyboard shortcuts for note-taking, multi-pane layout for assignment text + audio + notes side by side) is a genuinely different information density than the phone screens, closer to what Radwa also described ("a website for text and pdf files for weekly lessons and submissions and level notes"). Scope as a real second surface, not a CSS breakpoint.

9. Assessment rubrics in-app (First Assessment guideline, End of Course Assessment guideline), surfaced to the coach before they begin reviewing/assessing a student. Two distinct wishlist items (Wishlist "First Assessment Guideline", "End of Course Assessment Guideline"). Not designed — no Coach-app artboard shows a rubric reference screen. Needs the actual rubric content finalized by the program side before it's a design task.

10. Multi-week-behind state, designed explicitly. Mock App Feedback asked to eliminate the dedicated "Behind" screen in favor of a notification — done, no "Behind" artboard survives in main.jsx. But the reviewer also asked to "design the multi-week-behind case explicitly" — i.e., what does Today/Learn look like for a student who is 2, 3, 4+ weeks behind, not just one week? That state is not represented among the section 06 "States" artboards (which cover rest day, first week, empty archive, all-caught-up, mic permission — but not multi-week-behind). Needs its own state design: likely a variant of SakToday/SakLearn with a catch-up plan rather than a simple "N weeks behind" label, to avoid the punitive tone the original "Behind" screen had.

11. Coach access to all levels/mastery courses + lesson-breakdown preview, and the related Year 2 weekly assignments & lesson overviews for appointment prep (both from the Wishlist). Neither is represented on a Coach-app artboard. Bundle with item 9 (assessment rubrics) as a single "coach reference library" feature — all four are read-only content-access asks a coach needs while prepping or reviewing, and likely share one implementation (a coach-facing curriculum browser).

12. Coach re-recording a portion of the student's take within feedback, to demonstrate correct pronunciation (Wishlist, Year 1). Distinct from the built "Voice reply" (a new, separate reply) and from SakRecPractice (the student re-recording). This is the coach recording a clip of the student's own audio, re-performed, attached inline to a specific note. Needs a small addition to FbNoteRow/SakCoachReview — a "record demonstration" action per note.

4. Known launch-day requirements checklist

These are cross-cutting requirements that don't belong to any single screen and must be verified as engineering/QA gates, not designed as artboards:

• Report Issue accessible from every screen — the sheet design (SakReportIssue, F4) is proven once; confirm the entry point (and auto-attached screen/app-version/account context) is wired on every screen in the shipped app, not just the ones shown on the canvas.
• Timezone correctness through DST transitions — the mockup fixes the display rule (one local-time zone banner, no bare "EST"/"EDT" suffixes anywhere; REVIEW.md B3). Verify the underlying scheduling engine correctly recalculates local-time display across US/Europe/Turkey/Egypt when any region crosses a DST boundary — this was a live, recurring bug in the current app (calendar showing 7 PM for an 8 PM class) and must be tested explicitly at each region's DST transition date, not just at ship time.
• Announcement toggle default is ON — confirmed in the mockup (sak-settings.jsx:51-52); verify the same default ships in production notification-preference initialization for new accounts.
• Comment-truncation class of bugs — the current app's text-comment field truncates content (multiple coach reports). The redesign de-emphasizes free text in favor of voice reply, but any remaining text-input surface (coach private/shared notes, the 1:1 message composer, the self-reflection field if later built) must be explicitly tested for truncation — this is a bug class, not a single screen's bug, and needs its own QA pass across every text field in the shipped app.