Architecture Specification v2

QuranFlow Architecture Specification v2

Version: 2.0 Date: February 25, 2026 Organizing Principle: Weekly Rhythm -- "The app follows my weekly learning cycle." Status: Conditional Pass -- ready for detailed design (Year 1)

Executive Summary

The Problem in One Sentence

QuranFlow's current app provides no temporal orientation: students cannot answer "What week am I on?", "What should I be doing right now?", or "When does the next thing happen?" -- and some give up within the first two weeks.

The Architecture at a Glance

This specification defines a four-tab iOS architecture organized around a single organizing principle: the Weekly Rhythm. The app is structured to mirror the program's actual weekly cadence -- lesson unlocks Saturday, student watches and practices, submits a recording, receives audio feedback from their Quran Coach, and attends live sessions -- and to make every student's position within that rhythm immediately visible at every launch.

The four tabs:

How Disorientation Is Solved

The Today screen is the core solution. Its dominant visual element is the Week Header: "Week 8 of 15 -- Level 2 -- Reading with Fluency" in Large Title size, the first thing the eye lands on every launch. Below it: a context-dependent Primary Action Card that changes state based on where the student is in the weekly cycle (lesson not started / lesson in progress / submission due / awaiting feedback / feedback ready / all caught up). Below that: a Status Triptych showing compact Lesson, Submission, and Feedback cards side by side, giving returning students a 5-second status read without scrolling. Below that: today's upcoming sessions with timezone always displayed.

A student who has not opened the app in three days opens it and knows -- within five seconds, without scrolling -- exactly where they stand.

Key Decisions Made

1. Submission unified into Learn, not a standalone tab. The week-as-unit principle demands that lesson, submission, and feedback for the same week be co-located. Recording is an action within the weekly learning flow, not a standalone destination. This frees a tab slot and eliminates the cognitive split between "Learn" and "Submit."

2. Four tabs, not five. The Phase 2 quality bar establishes a four-tab ceiling. Today (orient), Learn (learn and submit), Schedule (attend sessions), Profile (identity and settings) cover 100% of the weekly critical path. No fifth tab is justified.

3. No hamburger menu, anywhere. All eight features previously buried in the hamburger menu (Quranic font, student level, coach identity, weekly schedule, session recordings, support, feedback archives, font size settings) now have discoverable homes in the four-tab structure. The hamburger menu pattern is eliminated entirely.

4. Font selection is mandatory during onboarding. The non-standard Quranic font was the most disorienting P0 issue for students. The five-step onboarding flow (Welcome > Level > Font > Coach > Semester) makes font selection mandatory at Step 3 -- it cannot be skipped -- ensuring every student sees mushaf script before they ever encounter Quranic text to recite.

5. Behind-state handled honestly and neutrally. When a student is behind, the Today screen shows the actual calendar week ("Week 8 of 15") alongside an amber banner: "You have 2 submissions to catch up on. You can submit up to 2 this week." with a one-tap "Catch Up" button. The language is functional, not shaming.

6. Schedule is a first-class tab. Previously hidden five clicks deep behind Hamburger > Resources > external Google Calendar link, the schedule now occupies Tab 3 with a full calendar view, timezone selector, session type filters, and a toggle to session recordings of past weeks.

Validation Results

Phase 5 validated the architecture against the full Phase 2 quality bar. Verdict: Conditional Pass.

• All mandatory structure, navigation, content, lifecycle, and notification tests: PASS
• [Core] task coverage: 24 of 27 fully covered (3 are Year 2 appointment tasks explicitly deferred)
• All 7 P0 issues addressed at the architecture/design level
• Total User Capability Map coverage: 93% (54 of 58 capabilities)

Four findings require resolution before implementation: (F1) the inactive Join Session button needs a countdown state specified in the Session Detail modal; (F2) a tap-count discrepancy in Flow 3's summary line needs correction; (F3) the pre-placement waiting state needs to specify what the Learn, Schedule, and Profile tabs show before level assignment; (F4) Year 2 appointment design should be explicitly scoped out rather than left implied. None of these findings invalidate the core architecture.

The architecture is ready to proceed to detailed design (wireframes and mockups) for Year 1, with the five findings resolved either in a document revision or during the wireframe phase.

1. Problem Brief

Version: 1.0 Date: February 25, 2026 Organizing Principle: Weekly Rhythm -- "The app follows my weekly learning cycle."

1.1 The Disorientation Problem

QuranFlow's core failure is that the app provides no temporal orientation. Students cannot answer three fundamental questions by looking at the app: "What week am I on?", "What should I be doing right now?", and "When does the next thing happen?" The program has a clear weekly cadence -- lesson, practice, submit, receive feedback, attend live sessions -- but the app treats each of these as isolated features scattered across tabs and buried menus, with no connective thread tying them to the student's actual position in the semester. The result is that students who skip reading onboarding emails (most of them) arrive in an app that gives them no sense of place, no sense of time, and no sense of sequence -- and some give up within the first two weeks.

1.2 The Weekly Rhythm

Each week within a 15-week semester follows the same critical path:

• Saturday: New weekly lesson unlocks (1-2 short videos, 3-5 minutes each, explaining that week's concept)
• Throughout the week: Student watches lesson videos, practices the concept using their Level Notes binder
• When ready: Student records themselves reciting the assigned Quranic passage and submits to their Quran Coach
• Within 48 hours of submission: Quran Coach reviews the recording and sends back audio feedback in-app
• Student reviews feedback: Listens to audio feedback, makes notes on what to improve, optionally asks follow-up questions via comments
• Live Level Class (2 timings offered): 1-hour weekly class covering that week's topic in depth, with Q&A -- one weekday, one weekend slot
• Quran Reading Circles (~12 sessions/week): Drop-in live practice sessions with any Quran Coach, gender-specific, open to all levels
• Repeat the following Saturday when the next lesson unlocks

Critical completion requirement: 12 of 15 weekly submissions must be completed, plus a successful End of Course (EOC) assessment, to graduate the level. Students may submit up to 2 recordings per 7-day period, allowing catch-up if they fall behind.

1.3 Task Inventory

[Core] Tasks -- Must be reachable in 2 taps or fewer

[Supporting] Tasks -- Important but app still functions without them

1.4 Hidden Features Table

Pattern: The hamburger menu is a graveyard for features. Every hidden feature lives behind it. The menu itself is a deprecated iOS pattern that violates platform conventions, and its icon (a small QuranFlow logo) does not signal "menu" to users. Anything placed here is effectively invisible.

1.5 Student Lifecycle Phases

Phase 1: Enrollment & Assessment (approx. 2 weeks before semester)

The student signs up via an external sales page and receives login credentials by email. Upon first app login, they are presented with an assessment screen where they record a reading sample. Within 48 hours, a Quran Coach listens to the recording and places the student in one of four levels (Level 1-4), assigning them a same-gender Quran Coach. The student should see their level and coach prominently in-app. Currently, both are buried in the hamburger menu.

Phase 2: Pre-Semester Orientation (remaining days before Day 1)

The student is waiting for the semester to begin. They should see a countdown to semester start, welcome/tutorial videos explaining the program, and information about pre-semester "housewarming" live sessions they can attend. Currently, the app shows none of this -- the semester start date exists only in emails, there are no orientation videos in-app, and pre-semester sessions are not distinguished from regular ones.

Phase 3: Active Semester -- Weekly Cycle (15 weeks)

This is the core phase. Each week the student follows the rhythm: lesson unlocks Saturday, watch videos, practice, record and submit, receive feedback, attend live sessions. The student needs to always know what week they are on, what is due, and what has been completed. This repeats for 15 weeks. The student may fall behind and catch up (up to 2 submissions per week). Currently, there is no week indicator, no "what to do this week" summary, and the various activities (lessons, submissions, live sessions, feedback) live in disconnected tabs with no temporal context.

Phase 4: End-of-Course Assessment (final weeks of semester)

After completing at least 12 of 15 weekly submissions, the student accesses the End of Course Assessment -- a single submission that combines all concepts from the level. The Quran Coach evaluates it and determines whether the student graduates. The student needs to clearly see: EOC availability, what it covers, their submission/feedback for it, and their graduation status. This phase is not well-documented in the current app.

Phase 5: Level Transition / Graduation

If the student passes, they are promoted to the next level (e.g., Level 1 to Level 2). They may receive a new Quran Coach. The next semester's start date and onboarding cycle begins. The student returns to Phase 2 with a new level context. If the student was in Level 4, they are eligible to enroll in QuranFlow Advanced (Year 2), which has a fundamentally different model: no weekly submissions, replaced by 1:1 appointment bookings with Quran Coaches, elective-based curriculum. This transition must be clearly explained since the app interaction model changes entirely.

Phase 6: Year 2 -- Advanced (ongoing)

Year 2 students have graduated from the structured submission cycle. Their primary interaction is booking and attending 1:1 appointments with Quran Coaches, attending live sessions, and pursuing elective content. The weekly rhythm is less rigid -- driven by appointment scheduling rather than submission deadlines. This phase has not been fully audited but shares the same platform and many of the same usability problems (navigation, discoverability, schedule access).

1.6 Summary of P0 Issues

For reference, these are the six P0 (critical/blocking) issues identified in the original audit, plus one elevated from the PM discussion:

1. Video playback failure -- lessons cannot be watched reliably (Task 3A.3)
2. Missing submission history -- past submissions and their feedback are not accessible in a unified view (Task 3B.6)
3. Broken notifications -- notification content is useless; no timestamp, no submission reference, no deep link (Tasks 3C.1, 6E.2)
4. Non-standard Quranic font -- default font is not mushaf script; correct font hidden in settings (Tasks 3B.2, 6B.1)
5. Inadequate user profile -- missing billing, subscription, learning history; broken photo upload (Task 6A.1)
6. No timezone on live sessions -- international students cannot determine correct local time (Task 3D.3)
7. Feedback inaccessible from progress screen -- progress shows percentages but no way to reach actual feedback (Tasks 3C.2, 3C.4) [elevated from PM discussion]

1.7 The Design Challenge

The app must be rebuilt around the weekly rhythm so that a student at any point in their lifecycle -- from pre-enrollment to Year 2 -- can open the app and immediately answer:

• What week of the semester is this?
• What should I be doing right now?
• What have I completed and what is still due?
• When is my next live session, in my timezone?
• Where is my Quran Coach's feedback on my last submission?
• How do I get help?

No emails. No manuals. No digging. The app itself must be the single source of truth for the student's relationship with the program.

2. Design Principles

Version: 1.0 Date: February 25, 2026 Input: WWDC25 Field Guide + Phase 1 Problem Brief Organizing Principle: Weekly Rhythm -- "The app follows my weekly learning cycle."

2.1 Preamble: What This Phase Is For

The WWDC25 Field Guide presents four diagnostic layers -- Structure, Navigation, Content, Visuals -- and a set of tests to apply at each layer. Phase 2 uses those tests not to audit the current app but to establish the standards the new architecture must meet. Every principle below is derived from the Field Guide and then sharpened against a specific QuranFlow failure from the Phase 1 problem brief.

The goal is a quality bar that is concrete enough to fail. Vague goals ("the app should feel clear") cannot be tested. Each criterion below can be answered with yes or no.

2.2 The 3 Questions Test

The WWDC25 Field Guide states this directly: "Before touching a pixel, the app must answer The 3 Critical User Questions immediately upon launch. If the user has to guess, the design has failed."

QuranFlow's current home screen fails all three. A student opens the app and sees a tab bar with unlabeled icons, a lesson list with no week context, and a hamburger menu that hides their level, coach, schedule, and every orientation tool they need. The disorientation problem identified in Phase 1 is not a content problem -- it is a structure problem. The app never tells the student where they are in time or in sequence.

The new architecture must answer all three questions from the home screen, without scrolling, on every launch, for every lifecycle phase.

2.3 Tab Worthiness Criteria

The Field Guide test is: Is it a destination? If yes, it belongs on the tab bar. Is it an action or a subset? If yes, it does not.

QuranFlow's current navigation violates this at every level. The hamburger menu makes destinations invisible. The top-of-screen tabs (the current pattern) mix destinations with filtered views of the same data. Some items that should be tabs (Feedback, Schedule) are buried. Some items that should not be tabs (the "+" record action on some screens) are treated as primary navigation.

The following criteria govern every tab bar decision in this architecture:

A tab is worthy if:

1. It is a place, not an action. The student navigates to it. Tapping it changes their location in the app. Tapping "Record" is an action -- it triggers a flow, not a destination. Tapping "Learn" takes the student to a place they will return to repeatedly.

2. It is used at least once per week during an active semester. Frequency of return is the test. If a typical student visits a destination less than once per week, it does not belong on the tab bar -- it belongs one level deeper. The Live session schedule meets this bar. The Settings screen does not.

3. Its absence would leave the student unable to complete a core task. The tab bar must cover the full critical path of the weekly rhythm: learn, submit, receive feedback, attend live sessions. Any destination not reachable from the tab bar must still be reachable in 2 taps from a tab.

4. It represents a coherent, self-contained information space. A tab contains things that belong together. The Learn tab contains lessons. The Live tab contains scheduled sessions and session recordings. A tab is not a dumping ground for loosely related features.

A tab is NOT worthy if:

• It is a subset of another tab. Submission history is a subset of the student's learning record, not a top-level destination. Feedback archives are a subset of submission history. Neither warrants its own tab.
• It is an action. Record, Submit, Add -- these are toolbar or inline actions. Placing an action on the tab bar confuses navigation with task initiation.
• It is administrative. Password change, notification settings, billing details -- these are settings-layer content. A Settings or Profile tab may house them, but they do not each deserve a tab.
• It serves only one lifecycle phase. Pre-semester orientation content, the EOC assessment flow, and Year 2 appointment booking are all important but phase-specific. They should surface contextually (as cards, banners, or state changes) within the existing tabs, not as dedicated tabs that are empty or irrelevant 90% of the time.

The 4-tab ceiling. QuranFlow's core weekly rhythm involves exactly four types of activity: orienting to the week (Home), learning the lesson (Learn), submitting and receiving feedback (could be unified as Practice or My Progress), and attending live sessions (Live). Four tabs. Any proposal for a fifth tab requires justification against the criteria above and against the organizing principle.

2.4 Content Principles

The WWDC25 Field Guide identifies three content-layer principles: Progressive Disclosure, layout selection (Grid vs. List vs. Collection), and grouping by human logic (Time, Progress, Pattern). Each maps directly to a QuranFlow failure.

2.4.1 Progressive Disclosure -- The Most Critical Principle for QuranFlow

The Field Guide pattern: Show the top 5 items in a collection (horizontal scroll), add a disclosure indicator, let the user tap through to the full list.

The QuranFlow problem it solves: The current Live session screen is described in the Phase 1 brief as "a wall of unstructured text." There are up to 20 live sessions per week (Quran Reading Circles, Level Classes, Office Hours) spanning multiple timings and days. Dumping all of them onto one screen means students "cannot find sessions they know are scheduled." The same problem occurs in the feedback archive (a flat list of every submission, requiring month/year filters) and in Resources (15+ items with no hierarchy).

How to apply it in QuranFlow: The Home screen applies progressive disclosure by surfacing only the current week's relevant sessions, not all sessions. The full schedule is one tap away via "See All" or the Live tab. The Learn tab shows the current week's lesson at the top, with prior weeks accessible via "See All Lessons." The feedback detail within a submission shows the coach's audio note and a summary of the comment; a "See full thread" action reveals the full comment history. Nothing is hidden permanently -- everything is one tap deeper.

The rule: No screen in the new architecture shows more than 7 items without a progressive disclosure mechanism. If a list can grow beyond 7 items, it must have a natural entry point (the top 3-5 most relevant) and a "See All" escape.

2.4.2 Grouping by Time and Progress -- Not by Feature Type

The Field Guide pattern: Group by human-centric themes: Time (Recent, This Week), Progress (Continue Watching, Drafts), Pattern (Genre, Related).

The QuranFlow problem it solves: The current architecture groups by feature type -- there is a Lessons tab, a Submissions tab, a Feedback tab. But the student does not think in feature types. They think in weeks. "What did I do in Week 6?" should return: the lesson video, the submission recording, the coach's audio feedback, and whether they attended the live session. These four things currently live in four different places with no linking mechanism.

How to apply it in QuranFlow: Time-grouping is the primary grouping strategy. The Home screen is organized around "This Week." A history view (whether in a dedicated tab or within the Practice/Progress tab) groups submissions chronologically by week: "Week 6," "Week 5," and so on -- each entry expanding to show lesson, submission, and feedback together. The Live schedule is grouped by day, then by session type, not by a flat alphabetical list of session names. Progress grouping is applied at the macro level: the student can see what is complete, what is in-progress, and what is upcoming.

The rule: Items that belong to the same week of the student's learning journey must be co-located or cross-linked. The Week 7 lesson, the Week 7 submission, and the Week 7 feedback are one unified record, not three separate items in three separate tabs.

2.4.3 Layout Selection -- List Over Grid for QuranFlow's Data

The Field Guide rule: Use grids for highly visual items (album art, photos). Use lists for text-dense or heterogeneous data. Use horizontal collections for themed groupings where you want to show a sample and let the user dive deeper.

The QuranFlow problem it solves: The core data in QuranFlow is text-heavy and status-driven: lesson titles, week numbers, submission states (Not started / In progress / Submitted / Feedback received), coach names, session times. None of this is primarily visual. A grid layout would sacrifice scannability for aesthetics. The student scanning for "Week 8 submission" needs to read titles and states quickly -- a list is correct.

How to apply it in QuranFlow: Lists are the default layout for lessons, submissions, feedback history, and live sessions. Horizontal collection rows (5 items with a "See All" disclosure) are appropriate for the Home screen to surface the current week's sessions without overwhelming the screen. A grid layout is acceptable only where visual differentiation is the point -- for example, coach avatars in a hypothetical coach directory, or thumbnail previews for session recordings. The default is always list.

The rule: No grid layout without a clear visual differentiator for each item. If the primary differentiator is text (a title, a date, a status), use a list.

2.4.4 The Squint Test Applied to QuranFlow

The Field Guide test: Squint until the screen blurs. You should still be able to identify the most important element and the structure of the page. If the screen looks like a uniform grey blob, or a decorative element overpowers content, it fails.

The QuranFlow problem it solves: The Phase 1 brief notes that the progress screen shows "9%" with no label, a redundant circle and bar display, and legacy "QR" branding. A student squinting at that screen cannot identify what 9% means or whether it is good or bad. The Live session screen is a wall of text with no visual hierarchy -- everything has equal weight, so nothing is findable.

How to apply it in QuranFlow: Every screen must have one clear visual anchor -- the element that draws the eye first and communicates the most important information. On the Home screen, the anchor is the weekly status card. On the Learn screen, the anchor is the current week's lesson. On the Live screen, the anchor is the next upcoming session. The anchor must survive the squint test: even blurred, it should be readable as "the thing that matters most right now."

The rule: Each screen has exactly one primary visual anchor. If two elements compete equally for the eye, the hierarchy is broken.

2.4.5 Standard Titles and Navigation Over Custom Patterns

The Field Guide warning: "Branding Over Utility -- Large, decorative headers that look nice but don't explain the utility."

The QuranFlow problem it solves: The hamburger menu icon is the QuranFlow logo -- a small graphic that does not signal "navigation" to users who encounter it without training. Critical features are buried behind it. The current top tab bar uses a custom pattern that mixes contexts. Labels like "Feedback" are misread as "give feedback" rather than "receive feedback."

How to apply it in QuranFlow: All navigation uses iOS standard components: a tab bar at the bottom for global destinations, a navigation bar at the top with a clear screen title and contextual actions in the top-right. Screen titles are functional, not decorative. "My Submissions" not "Your Journey." "Live Sessions" not "Community." Labels on the tab bar are single nouns that exactly describe what the tab contains. Where there is any ambiguity about a label's direction (receive vs. give), the label is rewritten to remove it -- "Coach Feedback" rather than "Feedback."

2.5 Quality Bar

These are the specific, testable criteria the architecture must meet before it is considered complete. Each is a binary test: pass or fail. Partial credit does not count.

Structure Tests

S1 -- The 3 Questions Test (10-second rule) A person who has never used QuranFlow opens the app's Home screen and is asked: "What week of the semester is this? What should you do next?" They must answer correctly within 10 seconds, using only what is visible on screen, without scrolling. Pass: They answer correctly within 10 seconds. Fail: They cannot answer, answer incorrectly, or require scrolling.

S2 -- No Hamburger Menu The architecture contains zero hamburger menus, sidebar drawers accessed via a logo, or navigation patterns that are not part of the iOS standard tab bar + navigation bar system. Pass: None exist. Fail: Any exist.

S3 -- Core Task Reach in 2 Taps Every [Core] task from the Phase 1 task inventory is reachable from the tab bar in 2 taps or fewer. "Reachable" means the student arrives at the screen where the task begins -- not necessarily that the task is complete in 2 taps. Pass: All [Core] tasks satisfy the 2-tap rule. Fail: Any [Core] task requires 3 or more taps from the tab bar.

S4 -- Hidden Features Eliminated Every feature listed in the Phase 1 "Hidden Features Table" (Quranic font selector, student's level, Quran Coach identity, weekly schedule, session recordings, support/help, feedback archives, font size settings) is accessible from a primary tab or is surfaced contextually without requiring the student to know it exists. Pass: All 8 hidden features are discoverable without prior knowledge. Fail: Any of the 8 remain hidden.

Navigation Tests

N1 -- Tab Bar Destination Test Every tab on the tab bar passes the Tab Worthiness criteria: it is a destination (not an action), it is visited at least once per week during an active semester, and it represents a coherent information space. Pass: Every tab passes all three criteria. Fail: Any tab fails any criterion.

N2 -- No Actions on the Tab Bar The tab bar contains only nouns (destination labels). No tab initiates a workflow, creates a record, or performs an action. Pass: All tab labels are nouns; no tab triggers a flow. Fail: Any tab triggers an action rather than navigating to a destination.

N3 -- First Submission Without Help A new student, using only the app, can complete their first submission (watch lesson, view Quranic text, record, review, and submit) without reading an email, asking for help, or leaving the app. Pass: They complete the flow unassisted. Fail: They get stuck at any point and require external guidance.

N4 -- Return Test (5-second rule) A returning student who has not opened the app in 3 days opens it and can state their current submission status (submitted / not yet submitted / feedback received) within 5 seconds, without scrolling. Pass: Correct answer within 5 seconds. Fail: They cannot determine status, determine it incorrectly, or must scroll to find it.

Content Tests

C1 -- No Screen Exceeds 7 Unmediated Items Any list on any screen that can contain more than 7 items has a progressive disclosure mechanism (a "See All" link, a collapsed section, or a filtered default view). The default state shows no more than 7 items. Pass: No default list view shows more than 7 items without a disclosure mechanism. Fail: Any list shows 8 or more items in its default state without a "See All" path.

C2 -- The Squint Test (per screen) Each primary screen (Home, Learn, Live, and the fourth tab) has a clear visual anchor -- the single most visually prominent element. When the screen is blurred, the anchor is still identifiable as the dominant element. Pass: Each primary screen has one identifiable anchor. Fail: Any primary screen has two competing anchors, or no discernible anchor at all.

C3 -- Week-Grouped History A student looking for their Week 6 submission and feedback can find both in one location, grouped by week, without needing to navigate to separate tabs for submission vs. feedback. Pass: Week 6 submission and Week 6 feedback are co-located or cross-linked within one tap of each other. Fail: They live in separate tabs with no link between them.

C4 -- Timezone Always Displayed Every live session time display includes the timezone. There are no bare times (e.g., "7:00 PM") without an associated timezone label or confirmation that the display is in the user's local time. Pass: Every time display carries explicit timezone information. Fail: Any time is displayed without a timezone.

C5 -- Standard Quranic Font on First Encounter The first time a student views Quranic text to recite (at the submission screen), the text is displayed in the standard mushaf font (not the default non-mushaf font). The student does not need to visit Settings to correct the rendering. Pass: Mushaf font is active by default on first use. Fail: The student sees a non-standard font and must navigate to Settings to fix it.

Lifecycle Tests

L1 -- Pre-Semester State A student who has completed the initial assessment but whose semester has not yet started opens the app and sees: their assigned level, their Quran Coach's name, the number of days until semester start, and at least one action they can take now (such as watching orientation videos or attending a pre-semester housewarming session). Pass: All four elements are visible from the Home screen. Fail: Any element is missing or requires navigation beyond the Home screen to find.

L2 -- Behind Test (2 weeks behind) A student who is 2 weeks behind on submissions opens the app. They can see their current deficit (e.g., "You are 2 submissions behind -- you can submit up to 2 this week to catch up") and a direct path to begin catching up, all from the Home screen. The messaging is neutral and functional, not shame-inducing. Pass: Deficit is visible, the catch-up path is one tap away, and the language is neutral. Fail: The deficit is not shown, the path requires more than 2 taps, or the language implies failure.

L3 -- EOC Phase State A student who has completed 12 of 15 submissions opens the app during the End-of-Course Assessment phase. The Home screen shows a distinct EOC state: what the EOC is, that they are eligible to submit it, and a direct path to the EOC submission screen. Pass: EOC card is visible on Home screen; student can reach EOC submission in 2 taps. Fail: EOC is not surfaced, is indistinguishable from a regular submission, or requires more than 2 taps.

L4 -- Recovery Test A confused student who does not know what to do next can find a support path (whether that is in-app help, a way to contact their Quran Coach, or a link to support) within 2 taps from any screen. Pass: Support is reachable in 2 taps from any screen. Fail: Any screen requires more than 2 taps to reach support, or there is no visible support affordance.

Notification Tests

V1 -- Notification Deep Links Every push notification delivers the student to the specific content referenced. A "feedback received" notification navigates to the feedback for the specific submission. A "new lesson available" notification navigates to that lesson. Pass: Every notification type has a functional deep link. Fail: Any notification lands on the app's home screen or a generic tab without context.

V2 -- Notification Content Every push notification contains: what happened, which submission or session it refers to (by week number and title), and when it happened (relative timestamp). Pass: All three elements are present in every notification type. Fail: Any notification is missing any of the three elements.

2.6 Principle Priority Stack

When design decisions must trade off against each other, apply this stack in order:

1. Temporal orientation first. If a screen does not tell the student where they are in time, it fails the organizing principle. This takes precedence over aesthetic choices, information density preferences, and feature completeness.

2. Guidance over flexibility for the Home screen. The Home screen optimizes for the student who does not know what to do next. Flexibility (browsing, exploring, catching up on old material) is served by the other tabs.

3. Clarity over density. When in doubt, show less and disclose progressively. A screen that shows 4 things clearly is better than a screen that shows 12 things at once.

4. Standard platform patterns over custom ones. Every custom navigation or layout pattern requires explicit justification. The default is always iOS standard: tab bar, navigation bar, list, system text styles, semantic colors.

5. No dead ends. Every screen state -- including empty states (no submissions yet), error states (video playback failure), and transition states (semester not yet started) -- must offer the student a clear next action or orientation. A blank screen with an error message is never acceptable.

3. Learnings from Previous Attempt

Version: 1.0 Date: February 25, 2026 Input: Architecture Proposals (A, B, C) + Design Review of Exploration A Mockup + Phase 1 Problem Brief + Phase 2 Design Principles Organizing Principle: Weekly Rhythm -- "The app follows my weekly learning cycle."

3.1 Preamble

This document extracts concrete lessons from the first attempt at implementing Proposal A as a mockup. The mockup reached approximately 80% alignment with the specification and 57% coverage of the full User Capability Map. That is a useful signal: it tells us what the Proposal A spec got right (the mockup could follow it), what the spec left ambiguous (the mockup had to improvise), and what the spec missed entirely (the mockup did not attempt it). Phase 4 must resolve every gap identified here.

3.2 What Worked in Proposal A (Preserve These)

3.2.1 The Schedule Page -- Near-Perfect Execution (95% alignment)

The Schedule page is the strongest screen in the mockup and the strongest section of the Proposal A spec. It implements: timezone selector with multiple options (EST, GMT, GST, AEDT), timezone display in the header, week navigator with arrows, calendar day strip, session type filters (All / Classes / QRCs), session cards with type badges and descriptions, Join Zoom buttons, Add to Calendar buttons, RSVP toggles with attendee counts, session detail modals, and deadline cards showing submission cutoffs. The design review found zero missing elements.

Why it worked: The spec was precise. It described the exact components, their states, and their relationships. It left nothing for the implementer to guess. The Schedule page also maps to a well-understood pattern (calendar views) that has clear iOS conventions.

Preserve: The full Schedule page design. Carry it forward as-is into Phase 4. It solves the P0 timezone issue, eliminates the 5-click-deep Google Calendar link, and passes every quality bar test from Phase 2 (C4: Timezone Always Displayed, S3: Core Task Reach, S4: Hidden Features Eliminated for schedule).

3.2.2 The Submit Page -- Excellent Submission UX (95% alignment)

The Submit page implements the core recording workflow correctly: week indicator, attempts counter ("1 of 2 Attempts Remaining"), Quranic text display in Amiri font with RTL rendering, tap-to-record with visual feedback, playback before submit, re-record option, confirmation dialog with explicit warning, success state with animation, submission history showing prior weeks, "Feedback Ready" badge, feedback bottom sheet with audio playback, and follow-up question input.

Why it worked: The submission flow is the most linear workflow in the app -- record, review, submit. Linear flows are easiest to spec and implement. The spec addressed the P0 issues directly (confirmation dialog for accidental submissions, proper Quranic font, submission history).

Preserve: The recording interface, confirmation dialog, feedback sheet pattern, and submission history list. These solve P0 issues (missing submission history, non-standard font, accidental submissions) and pass quality bar tests (C5: Standard Quranic Font on First Encounter, N3: First Submission Without Help).

3.2.3 The Learn Page -- Unified Week View (90% alignment)

The Learn page implements the key Proposal A insight: organizing content by week rather than by feature type. It uses expandable week cards that contain lesson videos (with checkboxes and duration), learning objectives, a submission sub-tab, and a "Feedback Ready" badge. The segmented control ([Current Week] [All Weeks]) enables progressive disclosure -- current week expanded, past weeks collapsed.

Why it worked: Grouping by week is the architectural decision most aligned with the Weekly Rhythm principle. The Phase 2 design principles (Content Principle 2: Grouping by Time and Progress) demand that "items belonging to the same week must be co-located." The Learn page does this.

Preserve: The week-as-unit grouping pattern, expandable week cards, the co-location of lesson + submission + feedback within a single week entry, and the segmented control for temporal filtering. This directly satisfies quality bar test C3 (Week-Grouped History).

3.2.4 The More Page -- Coach and Profile Surfacing (90% alignment)

The More page surfaces previously hidden features: profile card with avatar, name, level, and semester; stats display; My Quran Coach section with photo, name, message button, and bio; account management (Personal Details, Subscription, Notifications); Help Center; App Settings; and Sign Out. The coach section is prominent, not buried.

Why it worked: The More page is a standard iOS pattern (Settings/Profile hub) and the spec was clear about what belongs here. Moving the Quran Coach from the hamburger menu to a prominent section with a message action solves the discoverability problem identified in Phase 1.

Preserve: The coach section design, the profile card, and the overall More page organization. These satisfy quality bar tests S4 (Hidden Features Eliminated for coach identity and support) and L4 (Recovery Test -- support reachable in 2 taps).

3.2.5 The P0 Resolution Pattern

Six of seven P0 issues were addressed in the mockup. This validates that the Proposal A architecture creates natural homes for the fixes:

• Broken notifications: feedback alert on Today page
• Missing submission history: history section on Submit page
• Non-standard font: Amiri font as default on Submit page
• No timezone: timezone selector on Schedule page
• Inadequate profile: full profile on More page
• Feedback inaccessible: feedback sheet in Submit + alert on Today

Preserve: The principle that every P0 fix must have a visible, discoverable home in the primary tab structure -- not buried in settings or secondary screens.

3.3 What Didn't Work (Fix These)

3.3.1 The Today Page Failed the 3 Questions Test (60% alignment)

This is the single most important failure. The Today page is the home screen -- the first thing a student sees on every launch. Phase 2's quality bar test S1 requires that a person who has never used QuranFlow can answer "What week of the semester is this?" and "What should you do next?" within 10 seconds, without scrolling. The mockup's Today page fails this test.

Specific failures:

• "Week 8" without "of 15": The mockup shows "Current Week 8" as a small badge rather than the giant header "WEEK 8 OF 15" specified in Proposal A. Without "of 15," the student has no sense of position in the semester. Are they near the beginning? The middle? Almost done? The Phase 1 problem brief identifies this as the core disorientation symptom: students cannot tell where they are in the 15-week sequence.
• No level indicator: The Today page does not show the student's level (e.g., "Level 4 -- Tajweed Rules"). Level is a fundamental piece of identity context. The Phase 1 Hidden Features Table lists "Student's level" as hidden; the Today page was supposed to surface it permanently.
• No countdown to next week: Proposal A specifies "3 days until Week 9 unlocks" as a temporal anchor. The mockup omits this. Without it, the student has no sense of urgency or pace.
• No submission status card on Today: The mockup keeps submission in a separate tab. Proposal A specifies a submission status card on Today ("Awaiting feedback / Not started / Feedback ready") so the student sees their submission state on every launch. This is the "What should I do next?" answer for students mid-week.
• No video progress on lesson card: The mockup's lesson card shows title and description but not "Video 1/3 watched." Without per-video progress, the student cannot assess how far through the lesson they are from the home screen.
• Date header instead of week header: The mockup leads with "Thursday, Dec 19" -- the calendar date. But students do not think in calendar dates; they think in program weeks. The date is secondary context; the week number is primary.

Why it matters: The Today page IS the Weekly Rhythm. If the home screen does not foreground the week, the organizing principle is not implemented. Phase 2's Principle Priority Stack puts "Temporal orientation first" above all other concerns. A Today page that shows a date instead of a week number has inverted the priority.

Fix required: The Today page must be completely redesigned with the week header as the dominant visual element, the level below it, a progress bar, a countdown, and status cards for lesson, submission, and upcoming sessions -- all without scrolling.

3.3.2 Tab Structure Deviates from Proposal A

The mockup uses: Today | Learn | Submit | Schedule | More. Proposal A specifies: Today | Learn | Schedule | Progress | More.

Two deviations:

• Submit exists as a standalone tab instead of being unified into Learn. Proposal A's key architectural decision is that submission is part of the weekly learning flow, not a separate destination. When submission has its own tab, the student thinks of it as a separate activity rather than the natural next step after watching the lesson. This breaks the week-as-unit grouping principle from Phase 2.
• Progress tab is missing. Proposal A allocates tab slot 4 to Progress (feedback history, stats, achievements). The mockup has no Progress tab. This means feedback archives -- identified in Phase 1 as a hidden feature -- remain homeless at the top level. The student has no single place to see their full learning trajectory.

Why it matters: The tab bar is the skeleton of the information architecture. Phase 2's Tab Worthiness Criteria state that a tab must be "a place, not an action" and must "represent a coherent, self-contained information space." Submit-as-a-tab is debatable: it is arguably an action (recording) dressed as a destination. Progress-as-a-tab is clearly a destination (the student's full history). This is a structural decision that Phase 4 must resolve definitively.

3.3.3 Pre-Semester Phase Is Completely Absent (12% coverage)

The mockup implements 1 of 8 pre-semester capabilities. Missing entirely:

• Initial assessment flow (Task 2A.2)
• Level placement display (Task 2A.3)
• Program structure orientation/onboarding (Task 2B.1)
• Semester start countdown (Task 2B.2)
• Pre-semester housewarming sessions (Task 2B.8)
• Resources exploration (Task 2B.4)

Why it matters: Phase 2's quality bar test L1 (Pre-Semester State) requires that a student who has completed assessment but whose semester has not started sees: their assigned level, their Quran Coach's name, the number of days until semester start, and at least one action they can take now. The mockup cannot pass this test. Onboarding is where the app either hooks or loses the student. Phase 1 identifies that students who skip onboarding emails arrive to an app that "gives them no sense of place, no sense of time, and no sense of sequence -- and some give up within the first two weeks." The in-app onboarding must compensate for this.

3.3.4 No "Behind" State Handling

The mockup shows a student at Week 8 with normal progress. It does not address what happens when a student is behind. Phase 2's quality bar test L2 (Behind Test) requires: visible deficit messaging ("You are 2 submissions behind"), a catch-up path reachable in one tap, and neutral (not shaming) language. Proposal A's own trade-off analysis flagged this as a risk: "Students significantly behind may feel shame seeing 'Week 8' when they're on Week 5."

Why it matters: A substantial portion of students fall behind. The 12-of-15 completion requirement with 2-submissions-per-week catch-up policy means the app must actively support recovery. If the Today page only shows the current calendar week without acknowledging the student's actual position, it creates cognitive dissonance and potential shame. Phase 4 must design the behind state explicitly.

3.3.5 End-of-Course Assessment Phase Is Absent (0% coverage)

Zero implementation of Section 4 capabilities: EOC assessment screen, final results display, graduation flow, Level 4-to-Year 2 transition. Phase 2's quality bar test L3 (EOC Phase State) requires a distinct EOC card on the Home screen when the student has completed 12+ submissions and is eligible.

3.3.6 Session Recordings Are Missing (0% coverage)

Section 3E of the capability map (Find recordings, Filter recordings, Watch recordings, Track watched recordings) is at 0%. The Phase 1 Hidden Features Table lists session recordings as hidden behind "hamburger menu > Recordings > filter by date." The mockup does not surface them. Proposal A places them in "Progress tab > Past Sessions section" and in "Schedule > Past weeks," but since the Progress tab was not implemented, recordings have no home.

3.3.7 Font Settings UI Not Implemented

The mockup defaults to Amiri font (solving the P0 for first encounter), but there is no Settings UI for changing the font after onboarding. The Phase 1 audit notes that the font selector is one of 8 hidden features that must become discoverable. Phase 2 test S4 requires all 8 to be accessible without prior knowledge.

3.4 Elements from Proposals B and C Worth Incorporating

From Proposal B (Dashboard Command Center)

1. The Three-Card Dashboard Layout

Proposal B's home screen uses three equal-weight status cards side by side: Lesson (with video count), Submission (with status), and Feedback (with new count). Each card has a clear state and a single action button. This is a more information-dense approach than Proposal A's stacked cards, but it solves a real problem: the returning student who wants to assess all three statuses simultaneously without scrolling.

How to incorporate: The Today page should borrow the triptych pattern -- three status indicators visible in the top half of the screen -- but use it within Proposal A's temporal framework. The week header remains dominant at the very top; below it, three compact status cards (Lesson, Submission, Feedback) give the at-a-glance status. Below those, the day's sessions. This merges Proposal B's density with Proposal A's temporal anchoring. It directly serves the Phase 2 Return Test (N4): a returning student can state their submission status within 5 seconds.

2. Dedicated Feedback Tab Concept (Pending + History)

Proposal B gives Feedback its own tab with two views: Pending (submissions awaiting feedback) and History (all past feedback in chronological order, no complex date filters). This is a simpler, more scannable alternative to the current proposal's "feedback lives inside each week in the Learn tab."

How to incorporate: If Phase 4 decides that Progress deserves a tab, the Progress tab should adopt the Pending + History structure from Proposal B. Pending submissions at the top, then a reverse-chronological feed of all feedback grouped by week. This solves the feedback archives problem (Phase 1 Hidden Feature) and passes quality bar test C3 (Week-Grouped History). The key insight from B is that feedback should be browsable as a timeline, not only accessible by drilling into individual weeks.

3. Live Tab Combining Schedule + Recordings

Proposal B's Live tab uses a toggle: Schedule | Recordings. This co-locates the two things that relate to synchronous sessions -- upcoming ones and recorded past ones. It is more discoverable than Proposal A's approach (recordings in Progress tab, separate from Schedule).

How to incorporate: The Schedule tab should include a secondary access point to session recordings -- either as a toggle or as a "Past Sessions" section below the current week's schedule. Students who come to the Schedule tab looking for a session they missed should find the recording in the same location, not in a different tab.

4. Profile Tab with Full Account Hub

Proposal B's Profile tab includes: photo, name, level, week; My Quran Coach with message action; Account (Personal Information, Subscription & Billing, Learning History); Settings (Quranic Font Style, Notifications, Display); and Support (Help Center, Contact Support, FAQ). This is more comprehensive than the mockup's More page, particularly the inclusion of Learning History and the explicit "Quranic Font Style" setting.

How to incorporate: The More/Profile tab should adopt this full structure. Learning History is important for multi-semester students. The font setting must be explicitly labeled and accessible. These are Phase 1 requirements (Hidden Features Table, P0 font issue).

From Proposal C (Guided Journey)

1. The "Your Next Step" Single-Task Focus

Proposal C's Now tab shows exactly one task with a hero card: "YOUR NEXT STEP: Watch Lesson Video -- Video 2 of 3: Practice Stretches -- 12 minutes -- [Watch Now]." Below it, a single "Up Next" preview. This extreme focus is too restrictive as the default architecture (it fails Phase 2's Return Test because returning students cannot see full status), but the underlying pattern -- a context-dependent primary CTA that changes based on the student's state -- is valuable.

How to incorporate: The Today page should have a context-dependent primary action that adapts to the student's state within the weekly cycle. The state machine from Proposal C is precise and should be adopted:

• Lesson not started: "Watch Lesson Video"
• Lesson in progress: "Continue Lesson" (with specific video number)
• Lesson complete, no submission: "Record Your Submission"
• Submission awaiting feedback: "Waiting for Feedback" (passive state)
• Feedback ready: "Review Your Feedback" (highlighted/prominent)
• All done for week: "You're all caught up" (with suggestions for live sessions or review)

This state machine should drive the primary action on the Today page, but the other status cards remain visible so the student retains full context.

2. The Journey Visualization (Progress as a Map)

Proposal C's Progress tab shows a vertical journey map: Week 1 through Week 15, each with a status indicator (completed, in-progress, upcoming), the current position highlighted, and achievements below. This is a motivating, scannable visualization that answers "how far have I come" at a glance.

How to incorporate: The Progress tab (if it earns a tab slot) should include a journey map as its header element. The map provides the macro-level temporal orientation that complements the Today page's micro-level (this week) orientation. Week 1 through Week 15, the student's current position, completed weeks, and the EOC assessment at the end. Tapping any completed week should expand to show that week's lesson, submission, and feedback -- preserving the week-as-unit grouping. This visualization also provides a natural home for the EOC assessment (Week 15 becomes "EOC Assessment" at the end of the journey).

3. Guided Onboarding Sequence

Proposal C specifies a multi-step onboarding: Welcome > Font selection (required) > Meet your Quran Coach > See your journey map > Land on Week 1. This is the most thorough onboarding of the three proposals. Proposals A and B mention onboarding but are less prescriptive.

How to incorporate: Adopt Proposal C's onboarding structure but adapt it for the Weekly Rhythm context:

1. Welcome to QuranFlow + level placement confirmation
2. Font selection (required, not skippable -- solves P0)
3. Meet your Quran Coach (name, photo, brief bio)
4. Your semester overview (Week 1 of 15, start date, weekly rhythm explanation)
5. Land on Today page with Week 1 context

This ensures Phase 2 test L1 (Pre-Semester State) can pass and addresses Phase 1's finding that students who skip emails are completely lost.

4. The "Connect" Concept for Human Touchpoints

Proposal C groups all human connection into a single tab: Quran Coach, upcoming sessions, community, and support. While "Connect" as a standalone tab is not justified under Phase 2's Tab Worthiness Criteria (it mixes multiple information spaces), the insight is valid: the student's relationship with their coach, with live sessions, and with support are all interpersonal. These should feel connected, even if they live in different tabs.

How to incorporate: The Quran Coach should appear in multiple places contextually -- on feedback screens (who gave this feedback), on submission screens (who will review this), on the Today page (as a presence, not just in the More tab). Support should be reachable from multiple entry points: the More tab, a help icon on complex screens, and within the onboarding flow. The "interpersonal" layer should be woven through the app rather than isolated in one tab.

3.5 Open Design Questions

Phase 4 must make definitive decisions on each of these. They cannot be deferred.

Q1: What earns a spot on the tab bar?

The mockup uses: Today | Learn | Submit | Schedule | More (5 tabs). Proposal A specifies: Today | Learn | Schedule | Progress | More (5 tabs).

The core tension: Submit and Progress both have legitimate claims to a tab slot, but Phase 2 caps the tab bar at 4-5. If submission is folded into Learn (as Proposal A intends), the Learn tab carries the heaviest load in the app -- lessons, videos, recording, submission, and per-week feedback. Is that too much for one tab? Conversely, if Submit keeps its own tab, where does Progress live? And does a standalone Submit tab violate the "place not action" criterion?

Phase 4 must commit to one tab bar and justify every slot against the Tab Worthiness Criteria from Phase 2.

Q2: What dominates the home screen above the fold?

The mockup leads with a date and a small "Current Week 8" badge. Proposal A specifies a giant "WEEK 8 OF 15" header with level, progress bar, and countdown. Proposal B uses a dense three-card layout. Proposal C uses a single hero task.

The Phase 2 priority stack is clear: temporal orientation first. The week indicator must be the dominant visual element. But how much of the remaining above-the-fold space goes to status cards versus the primary CTA versus upcoming sessions? The design review shows that when the spec is vague about visual hierarchy, the implementation defaults to a generic date-driven layout. Phase 4 must spec the visual hierarchy in exact detail -- what is largest, what is second, what is below the fold.

Q3: Are submissions and feedback unified or separate?

Three possible models:

• Unified in Learn (Proposal A): Each week card contains lesson + submission + feedback. Student thinks "Week 7" and finds everything.
• Separate Submit tab (mockup): Submission and feedback have their own tab. Student thinks "I need to submit" and goes to Submit.
• Feedback as its own destination (Proposal B): A dedicated Feedback tab or Progress tab with Pending + History views.

The Phase 2 content principle says "items that belong to the same week must be co-located." This favors unification. But the design review shows that the mockup's standalone Submit tab has excellent UX (95% alignment). The question is whether unification into Learn would preserve that UX quality or degrade it by making Learn too complex.

Phase 4 must decide: Is submission a step within the weekly learning flow (unified) or a destination in its own right (standalone)?

Q4: Where does the schedule live relative to other tabs?

Proposal A gives Schedule its own tab (slot 3). This is justified by the Phase 1 finding that the schedule was hidden 5 clicks deep. But the mockup also demonstrates that Schedule is the strongest implementation -- it works perfectly as a standalone tab.

The question is whether Schedule's tab slot is better used for something else. Could schedule be a section within the Today page (next 24-48 hours of sessions) plus a "See Full Schedule" drill-down, freeing a tab slot for Progress? Proposal B's approach (Live tab combining Schedule + Recordings) is worth considering.

Phase 4 must weigh: Is Schedule important enough to justify a permanent tab, or can it be served adequately through the Today page + a secondary access path?

Q5: How does the app handle "you're behind"?

The mockup does not address this. Proposal A acknowledges the risk but does not specify the behind-state design. Phase 2 test L2 requires: visible deficit, one-tap catch-up path, neutral language.

Questions:

• Does the Today page show the student's actual completion week (e.g., "You are on Week 5 content") or the calendar week (e.g., "Week 8")?
• If the student is behind, does the week header show "Week 8 of 15 -- You have 3 submissions to catch up" or does it show "Week 5 of 15" (where the student actually is)?
• What language communicates deficit without shaming? ("You can submit 2 this week to get back on track" vs. "You are 3 weeks behind")
• Is there a catch-up mode that simplifies the Today page to focus on the most urgent submission?

Q6: Where does feedback history live?

Three options emerged from the proposals:

• Inside each week card in Learn (Proposal A's primary spec)
• In a Progress tab as a chronological timeline (Proposal A's secondary spec)
• In a dedicated Feedback tab with Pending + History views (Proposal B)

The Phase 1 problem brief identifies feedback archives as a hidden feature (currently behind "Hamburger > Feedback History sidebar > month/year filter"). The fix must make feedback browsable without complex filtering. The Phase 2 test C3 requires that Week 6 submission and Week 6 feedback are co-located within one tap.

The question: Is "co-located within each week" sufficient, or does the student also need a flat chronological feed of all feedback? The answer is probably both -- feedback accessible within each week in Learn AND a full timeline in Progress. But this dual-location approach must be designed so it feels like two views of the same data, not two separate features.

Q7: How does onboarding work?

None of the mockup screens address onboarding. The three proposals suggest different approaches: Proposal A mentions an onboarding card on the Today page; Proposal B mentions a "quick setup" prompt; Proposal C specifies a full multi-step guided flow.

Questions:

• Is onboarding a one-time overlay/wizard or a persistent state of the Today page during pre-semester?
• What is mandatory (font selection) versus optional (watching orientation video)?
• Does the Today page look fundamentally different before the semester starts versus during Week 1?
• How does the app transition from pre-semester state to active-semester state? Does it happen automatically on the semester start date, or does the student take an action?

3.6 Coverage Gaps

These are the areas of the User Capability Map at 0% or critically low coverage. Phase 4 must design explicit solutions for each.

0% Coverage -- Must Be Designed from Scratch

Section 4: End of Semester Phase (0/4 capabilities)

• 4.1 Complete end-of-course assessment
• 4.2 View final results
• 4.3 Graduate to next level
• 4.4 Transition from Level 4 to Year 2

The EOC is not a separate screen concept -- it is a state change in the existing architecture. Phase 4 should design it as a special-state week card (Week 15 or "EOC Week") that surfaces in the Learn tab and on the Today page when the student is eligible. Graduation should be a state change in the Progress tab. The Level 4-to-Year 2 transition needs at minimum a clear explanation screen, since the interaction model changes entirely (submissions replaced by appointment booking).

Section 5: Year 2 Differences (0/4 capabilities)

• 5.1 Year 2 overview
• 5.2 Appointment booking
• 5.3 Appointment management
• 5.4 Elective selection

Year 2 may be out of initial scope, but Phase 4 must at minimum design the architecture to accommodate it. The tab bar and information architecture should not need to be rebuilt when Year 2 is added. At a minimum, Phase 4 should identify which tabs change for Year 2 students and ensure the architecture can flex.

Section 3E: Session Recordings (0/4 capabilities)

• 3E.1 Find recordings of missed sessions
• 3E.2 Filter/search recordings
• 3E.3 Watch recorded session
• 3E.4 Track which recordings watched

Recordings need a home. The most natural location is within the Schedule tab (past sessions become watchable recordings) or within the Learn tab (recordings as supplementary material for each week). Phase 4 must decide.

Low Coverage -- Needs Significant Work

Section 2: Pre-Semester Phase (12% -- 1 of 8 capabilities)

Only "Meet assigned Quran Coach" is implemented (via More page). Missing: assessment flow, level placement, program orientation, semester countdown, pre-semester sessions, resource exploration. Phase 4 must design the pre-semester state of the Today page and the onboarding flow.

Section 3F: Progress Tracking (partial -- no grades, no pace comparison)

• 3F.4 See grades/performance: Not implemented
• 3F.5 Compare to expected pace: Not implemented

These require the Progress tab to exist. Phase 4 must decide what "grades" means in context (coaches give qualitative audio feedback, not numeric grades) and how "expected pace" is communicated without shame.

Section 6: Cross-Cutting Capabilities (57% -- missing font settings UI, resources access, community board)

• 6.2 Font settings UI: Menu item exists but no actual settings screen
• 6.5 Community board/Conversations: Not implemented
• 6.7 Resources access: Not implemented

Font settings is a P0-adjacent fix. Resources and Community are lower priority but need a home in the architecture.

3.7 Summary Table: Status of Key Architectural Decisions

4. Architecture Specification

Version: 1.0 Date: February 25, 2026 Input: Phase 1 Problem Brief + Phase 2 Design Principles + Phase 3 Learnings + All Source Files Organizing Principle: Weekly Rhythm -- "The app follows my weekly learning cycle."

4.1 Concept & Philosophy

The Mental Model: "My Weekly Planner"

The student opens QuranFlow and sees a planner organized around the current week of their 15-week semester. The app knows what week it is, what the student has done, and what remains. It presents this information the way a well-organized planner would: the current week is front and center, the weekly tasks are listed with their status, and the upcoming schedule is visible at a glance. The student does not browse. The student does not explore. The student opens the app, sees where they are, and picks up where they left off.

This is not a content library where learners choose what to study. It is not a social platform where learners interact with a community. It is a structured 15-week program with a fixed weekly cadence, and the app reflects that structure directly. The organizing principle is temporal: the week is the unit of work, the semester is the arc, and the student's position within both is always visible.

Why This Fits QuranFlow's Users

QuranFlow's students are busy adults, many older, many balancing families and jobs. The PM captured it precisely: "Not everybody is an exploration type... they just want a plug and play experience. What do I need to do? Just let me know, I'll do it. Don't make me think about the process." These users do not read onboarding emails. They do not explore menus. They open the app expecting it to tell them what matters right now.

A weekly-rhythm architecture serves this user because it eliminates decision-making. The student does not choose what to study -- the week determines it. The student does not figure out what to submit -- the current week's assignment is surfaced. The student does not hunt for their schedule -- it appears in temporal context. The app makes one promise: open it any day during the semester, and you will know exactly where you stand and what to do next.

How It Solves the Disorientation Problem

The Phase 1 problem brief identifies disorientation as the core failure: students cannot answer "What week am I on?", "What should I be doing?", or "When does the next thing happen?" The weekly-rhythm architecture solves this by making all three answers visible on the home screen at all times. The week number is the dominant visual element. The student's task status (lesson watched, submission done, feedback received) is shown as a checklist. The next scheduled event is displayed with a countdown. No inference, no calculation, no digging.

Position on the Guidance-Flexibility Spectrum

This architecture sits at approximately 70% guidance, 30% flexibility. The home screen is fully guided -- it tells the student what to do. The Learn tab offers moderate flexibility -- the student can browse all weeks, not just the current one. The Schedule tab offers full flexibility -- the student can view any week's sessions and recordings. The Profile tab is purely informational. The architecture is opinionated about what matters now but permissive about what the student can access.

How It Incorporates the Strongest Ideas

From the Dashboard approach (Proposal B): The three-card status triptych on the home screen -- Lesson, Submission, Feedback -- each showing a compact state with a single action. This gives the returning student instant status without scrolling.

From the Guided Journey approach (Proposal C): The context-dependent primary action that changes based on the student's state within the weekly cycle. The state machine (lesson not started, lesson in progress, submission due, awaiting feedback, feedback ready, all caught up) drives what the home screen emphasizes. Also adopted: the journey visualization as a progress map, and the structured multi-step onboarding sequence.

From the Weekly Rhythm approach (Proposal A): The week-as-unit grouping, the temporal header, the semester progress bar, the co-location of lesson, submission, and feedback within each week, and the schedule as a first-class tab.

4.2 Navigation Structure

Tab Bar Design

Tab bar justification against the Tab Worthiness Test:

Tab 1 -- Today: A destination (the student's weekly dashboard). Used on every launch. Its absence would leave the student without orientation. It is a coherent space: the current week's status.

Tab 2 -- Learn: A destination (the student's learning library organized by week). Used at least weekly to watch lessons, submit recordings, and review feedback. Its absence would leave the student unable to complete core tasks. It is a coherent space: all learning content grouped by week.

Tab 3 -- Schedule: A destination (the student's calendar of live sessions and recordings). Used at least weekly to check session times. Its absence would leave the student unable to attend live sessions. It is a coherent space: all time-based events.

Tab 4 -- Profile: A destination (the student's identity and settings hub). Used at least weekly to check coach information or access support. Its absence would leave hidden features (font, coach, support, resources) without a home. It is a coherent space: everything about the student's account and preferences.

Why 4 tabs, not 5: Phase 2 establishes a 4-tab ceiling. The four tabs above cover the full critical path: orient (Today), learn and submit (Learn), attend sessions (Schedule), and manage identity/get help (Profile). A fifth tab (Progress or Submit) does not meet the threshold. Submission is folded into Learn because it is a step within the weekly learning flow, not a standalone destination. Progress is folded into Learn as a journey map header. The 4-tab bar is the simplest structure that covers 100% of the weekly rhythm.

Key Decision: Submission Lives Inside Learn

Phase 3 identified this as the most important structural question. The decision: submission is unified into the Learn tab, within each week card.

Rationale:

1. Phase 2's content principle states that items belonging to the same week must be co-located. The Week 7 lesson, the Week 7 submission, and the Week 7 feedback are one unit of work.
2. A standalone Submit tab violates the "place not action" criterion. Recording is an action, not a destination. A student goes to Learn to engage with their weekly content; recording is one step in that engagement.
3. The mockup proved that the submission UX is excellent at 95% alignment. That UX does not require its own tab -- it requires a well-designed recording screen accessible from within the week card. The recording interface, confirmation dialog, and feedback sheet are preserved exactly as implemented.
4. Freeing the tab slot allows Profile to absorb all hamburger-menu content, eliminating the need for a "More" catch-all.

Tab 1: Today -- Screen Hierarchy

Level 0: Today (home screen)

No sub-screens navigate downward from Today. It is a dashboard. All interactive elements navigate laterally to other tabs or open modals:

• Tapping the lesson status card navigates to Learn tab, current week expanded
• Tapping the submission status card navigates to Learn tab, current week's submission section
• Tapping the feedback alert navigates to Learn tab, current week's feedback sheet
• Tapping a session card navigates to Schedule tab, that session's detail
• Tapping the coach avatar navigates to Profile tab, coach section
• Tapping the notification bell opens a notification sheet (modal)
• Tapping the week progress ring opens Learn tab with journey map visible

Empty state (pre-semester): Countdown to semester start, level and coach info, orientation video card, pre-semester sessions card.

Tab 2: Learn -- Screen Hierarchy

Level 0: Learn (journey map + week list) Level 1: Week Detail (expanded week card with Lesson / Submission / Feedback segments) Level 2: Video Player (full-screen video playback) Level 2: Recording Screen (Quranic text display + recording interface) Level 2: Feedback Detail (audio playback + comment thread)

The Learn tab uses an expandable-card pattern. The journey map is the header (a compact vertical timeline of all 15 weeks showing completed, current, and upcoming). Below it, week cards are listed in reverse chronological order with the current week at the top, expanded by default.

Each week card contains three segments accessed via an internal segmented control: Lesson | Submission | Feedback.

• Lesson segment: Video list with per-video watch status, duration, and play buttons. Learning objectives displayed below videos.
• Submission segment: Quranic text display, recording interface, submission history, attempts remaining counter.
• Feedback segment: Coach's audio feedback with playback controls, timestamp, comment thread for follow-up questions.

Empty state (pre-semester): Journey map showing "Week 1 of 15" with all weeks as upcoming. A single card: "Your first lesson unlocks on [date]. Here's what to expect." with a link to the orientation video.

Tab 3: Schedule -- Screen Hierarchy

Level 0: Schedule (weekly calendar view with session cards) Level 1: Session Detail (modal sheet with full session info, Zoom link, add-to-calendar) Level 1: Recordings (accessed via "Past" toggle, showing recorded sessions)

The Schedule tab uses the design from the mockup, which achieved 95% alignment and zero missing elements. It includes: timezone selector in the header, week navigator with arrows, calendar day strip, session type filters (All / Classes / QRCs / Office Hours), session cards with type badges, Join Zoom buttons, Add to Calendar buttons, RSVP toggles, and deadline cards.

A segmented control at the top provides access to recordings: Upcoming | Past. The Past view shows recorded sessions for previous weeks, with session type labels, dates, and watch status indicators. This solves the session recordings discoverability problem -- students who come to Schedule looking for a missed session find the recording in the same location.

Empty state (pre-semester): Shows pre-semester "housewarming" sessions if any are scheduled. If none, shows "Sessions begin [semester start date]" with the weekly schedule overview (what types of sessions happen each week).

Tab 4: Profile -- Screen Hierarchy

Level 0: Profile (identity card, coach section, menu groups) Level 1: Personal Details (name, email, phone, photo upload) Level 1: Subscription & Billing (plan, payment history) Level 1: Learning History (past levels completed, dates, performance) Level 1: Notifications Settings (push toggle, email preferences, notification types) Level 1: Quranic Font Settings (font selector with preview, font size) Level 1: Display Settings (text size, accessibility options) Level 1: Help Center (FAQ, contact support categories: General, Tech, Billing) Level 1: Resources (organized by category: Essential, Supplementary, Reference) Level 1: About QuranFlow (version, legal)

The Profile tab surfaces every feature previously buried in the hamburger menu. The coach section is prominent -- positioned directly below the profile card, with the coach's photo, name, bio, and a "Message Coach" button. This ensures the coach relationship is visible and the communication channel is discoverable.

Empty state: Never truly empty. Even pre-semester, the profile card shows the student's name, level, and assigned coach.

4.3 Screen Specifications

Screen: Today

Purpose: Show the student exactly where they are in the semester and exactly what to do next, without scrolling.

Content (top to bottom):

Navigation Bar:

• Left: QuranFlow logo (small, non-interactive, purely branding)
• Center: (empty -- the week header below serves as the screen title)
• Right: Notification bell icon with badge count if unread notifications exist

Week Header (dominant visual element):

• Line 1 (Large Title size, bold): "Week 8 of 15"
• Line 2 (Subheadline size, secondary color): "Level 2 -- Reading with Fluency"
• Line 3 (Caption size, tertiary color): "3 days until Week 9 unlocks"
• Right-aligned: Circular progress ring showing semester completion percentage (e.g., "53%") with the number inside the ring

This header is the visual anchor of the screen. It is the largest text element. It answers "Where am I?" instantly.

Primary Action Card (context-dependent):

A single prominent card that changes based on the student's state within the weekly cycle. The card has a colored left border (accent color), a title, a subtitle, and a single action button.

The state machine determines the card content:

Status Triptych (three compact status indicators in a horizontal row):

Borrowed from Proposal B. Three small cards side by side, each showing one status:

These three cards answer "What can I do?" and serve the returning student who wants to assess status in 5 seconds.

Upcoming Sessions Section:

• Section header: "Today's Sessions" (or "Tomorrow's Sessions" if none today, or "This Week's Sessions" if none today or tomorrow)
• Shows up to 3 session cards, each with: type badge (Level Class / QRC / Office Hours), time with timezone (e.g., "7:00 PM EST"), title, and a "Join" button if the session is within 15 minutes of start or currently live
• "See Full Schedule" link at the bottom, navigating to the Schedule tab
• If no sessions remain this week: "No more sessions this week. See next week's schedule."

Behind State Banner (conditional):

If the student is behind on submissions, a banner appears between the week header and the primary action card:

• Background: warm amber (not red -- not alarming)
• Icon: arrow.clockwise (catch-up icon)
• Text: "You have [X] submissions to catch up on. You can submit up to 2 this week."
• Button: "Catch Up" -- navigates to the oldest incomplete week in Learn

The language is neutral and functional. It states the fact and offers the path. It does not say "you're behind" or "you're falling behind." It says what can be done.

States:

Behaviors:

• Tapping the lesson status card navigates to Learn tab with current week expanded, Lesson segment active
• Tapping the submission status card navigates to Learn tab with current week expanded, Submission segment active
• Tapping the feedback status card navigates to Learn tab with the relevant week expanded, Feedback segment active
• Tapping a session card navigates to Schedule tab with that session highlighted
• Tapping the notification bell opens a notification sheet showing recent notifications in reverse chronological order, each with: type icon, description (e.g., "Week 7 feedback from Coach Amina"), relative timestamp, and a tap target that deep-links to the relevant content
• Tapping the "Catch Up" button on the behind banner navigates to Learn tab, scrolled to the oldest incomplete week
• Pull-to-refresh updates all status data
• The primary action card and status triptych refresh automatically when the app returns to foreground
• Push notifications that arrive while the app is open update the notification badge count and the relevant status card in real time

Connection to other screens:

• Navigates TO: Learn (via any status card or primary action), Schedule (via session cards), Profile (via coach avatar if present), Notification Sheet (via bell icon)
• Navigated FROM: App launch always lands here. Deep links from notifications may pass through here. Tab bar returns here from any other tab.

Screen: Learn (Journey Map + Week List)

Purpose: Show the student's complete learning journey organized by week, with the current week expanded and ready for action.

Content (top to bottom):

Navigation Bar:

• Title: "Learn"
• Right: Filter icon (for future use -- filter by status: All / Incomplete / Complete)

Journey Map Header:

A compact horizontal visualization of the 15-week semester:

• A horizontal track of 15 circles (one per week), connected by a line
• Completed weeks: filled circles with checkmark, accent color
• Current week: larger filled circle, pulsing border, week number inside
• Upcoming weeks: hollow circles, muted color
• EOC assessment: a special icon at the end of the track (star or graduation cap)
• Below the track: "Week 8 of 15 -- 7 completed, 8 remaining"
• Tapping any completed week circle scrolls to and expands that week card below

The journey map provides macro-level orientation. It answers "how far have I come" at a glance.

Segmented Control:

• [This Week] [All Weeks]
• "This Week" shows only the current week card, expanded
• "All Weeks" shows all 15 weeks in reverse chronological order (current at top), with completed weeks collapsed and current week expanded

Week Cards (the core content):

Each week card is a collapsible container with a header showing:

• "Week [N]: [Topic Name]"
• Status badge: "Complete" (green) / "In Progress" (blue) / "Not Started" (gray) / "Feedback Ready" (amber with dot)
• Chevron to expand/collapse

When expanded, the week card contains an internal segmented control: Lesson | Submission | Feedback

Lesson Segment:

• Topic header: "Week 8: [Full Topic Name]"
• Learning objectives: Blue info box with 2-4 bullet points describing what the student will learn
• Video list: Each video as a row with:
  • Checkbox (filled if watched, empty if not)
  • Video title (e.g., "Introduction to Madd Rules")
  • Duration (e.g., "4:32")
  • Tap target: opens Video Player screen
• Below videos: "Mark Lesson Complete" button (appears after all videos watched; includes confirmation dialog; reversible)

Submission Segment:

• Header: "Week 8 Submission"
• Quranic text display: The assigned passage rendered in mushaf font (Amiri Quran), RTL, with proper Arabic typography. Font is mushaf by default -- no settings change required.
• Passage reference: Surah name and ayah numbers below the Arabic text
• Attempts counter: "1 of 2 Attempts Remaining" (or "2 of 2 Attempts Remaining" if the student has catch-up capacity)
• "Record Submission" button (large, centered, mic icon)
• Tapping "Record Submission" navigates to the Recording Screen (Level 2)
• Submission history below: A list of past attempts for this week (if any), each showing timestamp and status (Submitted / Under Review / Feedback Ready)
• If feedback is ready for this week: "Feedback Ready" badge with "Listen" button that opens the Feedback segment

Feedback Segment:

• If no submission yet: "Submit your recording to receive feedback from your Quran Coach."
• If submission under review: "Your coach is reviewing your submission. You'll be notified when feedback is ready." with a timestamp of when the submission was sent.
• If feedback is available:
  • Coach avatar and name: "[Coach Name]'s Feedback"
  • Audio player: Play/pause button, scrubber, duration display
  • Timestamp: "Received [relative time]"
  • Coach's written notes (if any): displayed below audio
  • Comment thread: Existing comments between student and coach
  • Text input: "Ask a follow-up question..." with a send button
  • The text input must function correctly (Phase 1 identified broken text input as a bug)

States:

Behaviors:

• Tapping a video row opens the Video Player in full-screen
• Tapping "Record Submission" opens the Recording Screen
• Tapping the audio player play button begins feedback playback
• Tapping "Send" on a follow-up question posts the comment and notifies the coach
• Expanding a week card auto-collapses any other expanded card (accordion behavior in "All Weeks" view)
• Tapping a journey map circle scrolls to and expands that week card
• Pull-to-refresh updates all week statuses
• New feedback arrivals update the relevant week card's badge in real time

Connection to other screens:

• Navigates TO: Video Player (from video row), Recording Screen (from "Record Submission"), Feedback Detail (from feedback audio -- inline, not a separate screen)
• Navigated FROM: Today (via status cards and primary action), Tab bar

Screen: Recording Screen (Level 2 within Learn)

Purpose: Allow the student to view the Quranic passage, record their recitation, review it, and submit to their coach.

Content (top to bottom):

Navigation Bar:

• Left: "< Back" to return to the week card
• Title: "Week 8 Submission"
• Right: (none)

Week and Attempt Info:

• "Week 8 of 15 -- Level 2"
• "Attempt 1 of 2 Remaining"

Quranic Text Display:

• The assigned passage in mushaf font (Amiri Quran), large size, RTL
• Surah name and ayah reference below (e.g., "Surah Al-Baqarah, Ayah 255")
• Font defaults to mushaf. A small "Aa" icon in the top-right of the text area allows switching font style (opens a compact font picker inline -- no navigation to Settings required)

Recording Interface:

• Large circular "Record" button (centered, red mic icon)
• Before recording: "Tap to start recording"
• During recording: Animated audio waveform visualization, elapsed time counter, "Stop" button replaces "Record"
• After recording: Playback controls (play/pause, scrubber, duration), "Re-record" button, "Submit" button
• Play and Submit buttons have clear visual separation (play on the left, submit on the right, with different colors and sizes) to prevent accidental submission

Confirmation Dialog (on submit tap):

• Modal overlay: "Submit This Recording?"
• Body: "This will be sent to [Coach Name] for review. You will receive feedback within 48 hours. You will have [N] attempt(s) remaining after this submission."
• Buttons: "Cancel" (secondary) and "Submit" (primary, accent color)
• This dialog is mandatory -- it prevents accidental submissions (P0 fix)

Success State (after confirmed submit):

• Checkmark animation
• "Recording Submitted"
• "Your coach [Coach Name] will review your submission and send feedback within 48 hours."
• "Return to Week 8" button

States:

Behaviors:

• Tapping Record starts audio capture with microphone permission prompt on first use
• Tapping Stop ends recording and transitions to Review state
• Tapping Play plays back the recording
• Tapping Re-record discards the recording and returns to Ready state (with confirmation if recording exists)
• Tapping Submit opens the Confirmation Dialog
• Confirming Submit sends the recording and shows Success state

Connection to other screens:

• Navigated FROM: Learn tab, week card's Submission segment
• Navigates TO: Returns to Learn tab week card after submission

Screen: Video Player (Level 2 within Learn)

Purpose: Play lesson videos with reliable playback and progress tracking.

Content:

• Full-screen or large-format video player using native iOS player controls
• Adaptive bitrate streaming (not locked to 1080p -- this fixes the P0 video playback failure)
• Single-tap full-screen toggle with large touch target
• Progress bar with resume-from-last-position support
• "Next Video" button if multiple videos in the lesson
• "Back to Lesson" button to return to the week card
• Auto-marks video as watched when the student reaches 90% completion

Behaviors:

• Video playback resumes from last position if previously started
• Completion status syncs back to the week card's video checklist
• Background audio continues if the student switches away briefly (configurable)
• Subtitles/captions available if provided

Connection to other screens:

• Navigated FROM: Learn tab, week card's Lesson segment, video row
• Navigates TO: Returns to week card; optionally auto-advances to next video

Screen: Schedule

Purpose: Show the student's weekly live session schedule with timezone clarity, session details, and access to recordings of past sessions.

Content (top to bottom):

Navigation Bar:

• Title: "Schedule"
• Right: Timezone selector button showing current timezone (e.g., "EST")

Timezone Selector (drops down on tap):

• Dropdown or action sheet with timezone options: Auto-detect (device timezone), EST, GMT, GST, AEDT, and other common student timezones
• Selected timezone persists across sessions
• All times on this screen and throughout the app display in the selected timezone

Segmented Control:

• [Upcoming] [Recordings]

Upcoming View:

Week Navigator:

• "< Week 8 >" with left/right arrows to browse other weeks
• Current week shown by default

Calendar Day Strip:

• Horizontal scrollable row of day circles (Sat, Sun, Mon, Tue, Wed, Thu, Fri)
• Current day highlighted
• Days with sessions show a dot indicator

Session Type Filters:

• Horizontal pill buttons: All | Level Classes | QRCs | Office Hours
• "All" selected by default

Session Cards (list below filters):

Each session card shows:

• Type badge: "Level Class" (blue) / "QRC" (green) / "Office Hours" (purple)
• Time: "7:00 PM EST" (always with timezone)
• Title: e.g., "Level 2 Class -- Week 8: Madd Rules"
• Coach name (for QRCs and Office Hours)
• Gender indicator (for QRCs): "Sisters" or "Brothers"
• Status indicator: "Upcoming" / "Live Now" (pulsing) / "Ended"
• Action buttons:
  • "Join Zoom" (primary, only when session is within 15 minutes of start or live)
  • "Add to Calendar" (secondary, + icon)
  • "RSVP" toggle with attendee count

Deadline Cards (interspersed with sessions):

• "Submission Deadline -- Friday 11:59 PM EST"
• Styled differently from session cards (dashed border, muted background)

Recordings View:

Week Navigator: Same as Upcoming view

Recordings List:

• Each recording card shows:
  • Type badge (same as live sessions)
  • Date and time of original session
  • Title
  • Duration
  • Watch status: "Watched" checkmark or "New" badge
  • Tap to open recording player
• Sorted by date, most recent first
• Filter by session type (same pills as Upcoming view)

States:

Behaviors:

• Tapping a session card opens a Session Detail modal sheet with: full description, Zoom link, coach bio, Add to Calendar action, RSVP action, and (for past sessions) a link to the recording
• Tapping "Join Zoom" opens the Zoom link in Zoom app or browser
• Tapping "Add to Calendar" creates a calendar event via iOS calendar integration
• Toggling RSVP updates the attendee count and adds/removes the session from the student's "My Sessions" list
• Switching to Recordings view shows past session recordings
• Pull-to-refresh updates session list and live status

Connection to other screens:

• Navigated FROM: Today (via session cards or "See Full Schedule"), Tab bar
• Navigates TO: External Zoom app (via Join button), iOS Calendar (via Add to Calendar), Recording Player (from Recordings view)

Screen: Profile

Purpose: Provide access to the student's identity, their coach relationship, all settings, and support -- replacing the hamburger menu entirely.

Content (top to bottom):

Navigation Bar:

• Title: "Profile"

Profile Card:

• Avatar (tappable to change photo -- gallery and camera options)
• Name (e.g., "Sarah Ahmed")
• Level and semester: "Level 2 -- Semester 1"
• Status: "Week 8 of 15" or "Pre-Semester" or "EOC Phase"

Quick Stats Row:

• Three compact stats: "7 Weeks Completed" | "6 Submissions" | "85% Attendance" (or equivalent metrics)

My Quran Coach Section:

• Coach photo (circle avatar)
• Coach name (e.g., "Coach Amina")
• Brief bio (1-2 lines, e.g., "Certified Quran Coach, specializing in Level 1-2 instruction")
• "Message Coach" button (opens a message composition sheet that sends to the coaching team email or in-app messaging when available)
• This section is visually prominent -- bordered card with slight elevation

Menu Groups:

Account:

• Personal Details (name, email, phone, photo management)
• Subscription & Billing (plan details, payment history, renewal date)
• Learning History (past levels completed, semesters, dates)
• Notifications (push notification toggle, email notification preferences, notification types: Feedback, Sessions, Announcements, Deadlines)

Settings:

• Quranic Font (font style picker with live preview of Arabic text; options: Amiri Quran (mushaf), Simplified Arabic; font size slider)
• Display (text size, dark mode preference, accessibility options)
• Language (if applicable in future)

Support:

• Help Center (FAQ organized by topic: Getting Started, Lessons, Submissions, Live Sessions, Technical Issues)
• Contact Support (category selection: General, Technical, Billing; then message composition)
• Resources (organized list with categories: Essential -- Level Notes PDF, Weekly Schedule Overview; Supplementary -- Additional Practice Materials; Reference -- Program FAQ, Glossary)

Bottom:

• Sign Out button (red text, bottom of screen)
• Version number: "QuranFlow v2.0 (Build XXX)"

States:

Behaviors:

• Tapping "Message Coach" opens a composition sheet. The message is sent to the coaching team (coaches@quranflow.org initially, transitioning to in-app messaging when available).
• Tapping any menu item navigates to the corresponding detail screen (push navigation)
• Tapping the avatar opens photo picker (camera or gallery)
• All settings changes are saved immediately
• Font changes take effect immediately across the app with a live preview in the settings screen

Connection to other screens:

• Navigated FROM: Today (via coach avatar), Tab bar
• Navigates TO: All Level 1 sub-screens (Personal Details, Subscription, Help Center, etc.)

Screen: Notification Sheet (Modal from Today)

Purpose: Show the student all recent notifications in one place with deep links to relevant content.

Content:

• Modal sheet (half-height, swipeable to dismiss)
• Header: "Notifications"
• List of notifications, each with:
  • Type icon (feedback: message icon; session: calendar icon; deadline: clock icon; announcement: megaphone icon)
  • Title: e.g., "Feedback Ready -- Week 7"
  • Subtitle: e.g., "Coach Amina reviewed your submission"
  • Relative timestamp: "2 hours ago"
  • Unread indicator (blue dot)
• Tapping a notification marks it as read and navigates to the relevant content:
  • Feedback notification: Learn tab > relevant week > Feedback segment
  • Session reminder: Schedule tab > relevant session
  • Deadline reminder: Learn tab > relevant week > Submission segment
  • Announcement: Displayed inline in the notification (no navigation needed)

States:

• Empty: "No notifications yet. You'll see updates about feedback, sessions, and deadlines here."
• With notifications: Chronological list, newest first, max 50 shown

4.4 Critical User Flows

Flow 1: First-Time Student Opens the App (Onboarding)

Precondition: Student has submitted their initial assessment and received level placement. They open the app for the first time post-placement.

Total taps on critical path: 5 (Welcome > Level > Font > Coach > Semester > Today) Time estimate: 60-90 seconds Why this works: Each step delivers one piece of essential information. Font selection (the P0 fix) happens before the student ever sees Quranic text. The coach introduction happens before the student ever receives feedback. The semester overview happens before the student has to navigate the app independently.

Flow 2: Watch This Week's Lesson

Precondition: Active semester, Week 8. Lesson available but not started.

Total taps on critical path: 5 (Open app > Start Lesson > Video 1 > Video 2 > Mark Complete) Actual engagement taps: 2 to reach first video from app launch Why this works: The Today screen surfaces the lesson as the primary action. One tap reaches the video list. One more tap starts the video. No hunting.

Flow 3: Submit Weekly Recording

Precondition: Week 8 lesson watched. Student ready to submit.

Total taps on critical path: 7 (Open > Record Submission > Record Submission button > Record > Stop > Submit > Confirm) Taps from app launch to recording start: 3 Why this works: The path from app launch to recording is direct. The confirmation dialog prevents accidental submissions. The success state sets clear expectations about feedback timing.

Flow 4: Check and Respond to Feedback

Precondition: Coach has sent audio feedback for Week 7 submission.

Total taps on critical path: 3 (Open > Listen to Feedback > Play) Why this works: Feedback is surfaced on the Today screen the moment it arrives. One tap reaches the audio player. No hunting through archives or filters.

Alternative entry via push notification:

Taps from notification: 1

Flow 5: Find and Join a Live Session

Precondition: Active semester. A QRC is scheduled for today at 7:00 PM EST.

Total taps on critical path: 2 (Open > session card > Join Zoom) Alternative: Navigate to Schedule tab directly (1 tap from tab bar), select day, find session (1-2 taps). Why this works: Today's sessions are visible on the home screen. Join is 2 taps away. Timezone is always displayed. No ambiguity about when or where.

Flow 6: Catch Up After Missing a Week

Precondition: Student is at calendar Week 8 but has not submitted for Weeks 6 and 7. They are 2 submissions behind.

Total taps for one catch-up submission: Same as Flow 3 (7 taps) Why this works: The behind banner is visible immediately. The "Catch Up" button takes the student to the right place. The system tracks catch-up submissions against the 2-per-week limit. The language is functional ("You can submit up to 2 this week") not shaming ("You're behind").

Flow 7: Pre-Semester Experience

Precondition: Student completed assessment, placed in Level 2, assigned Coach Amina. Semester starts in 5 days.

Why this works: The student is never in a state where the app is empty or confusing. Pre-semester has its own clear purpose: orient, prepare, get excited. The countdown eliminates the "when does semester start?" emails entirely.

Flow 8: End-of-Semester Assessment and Graduation

Precondition: Student has completed 13 of 15 weekly submissions. It is Week 15. EOC assessment is available.

Total taps from results notification to viewing results: 2 Why this works: The EOC is not a hidden feature. It surfaces automatically when the student is eligible. The results communication is clear and celebratory. The transition to the next level or Year 2 is explicit.

4.5 Surfacing Strategy

Every feature that was previously hidden behind the hamburger menu now has a discoverable home.

4.6 State Management

Temporal Events

New week unlocks (Saturday):

• Today screen: Week header updates from "Week [N]" to "Week [N+1] of 15." Primary action card changes to "This Week's Lesson -- Week [N+1]." Countdown resets to "6 days until Week [N+2] unlocks."
• Learn tab: New week card appears at the top. Journey map advances the current position by one step. Previous week card collapses.
• Schedule tab: Week navigator auto-advances. New week's sessions populate.
• Notification: Push notification: "Week [N+1] is here! Your new lesson is ready." Deep links to Today.

Submission deadline approaches (2 days before, 1 day before):

• Today screen: Deadline indicator appears on the submission status card: "Due in 2 days" then "Due tomorrow."
• Schedule tab: Deadline card shows with countdown.
• Notification: Push notification at 2-day and 1-day marks if submission is not yet sent.

Live session about to start (15 minutes before):

• Today screen: Session card shows "Starting Soon" with "Join Zoom" button active.
• Schedule tab: Session card shows "Starting in [X] min" with pulsing indicator.
• Notification: Push notification: "QRC starting in 15 minutes -- Sisters Reading Circle." Deep links to Schedule with session highlighted.

Session is live:

• Today screen: Session card shows "Live Now" with pulsing red dot and active "Join" button.
• Schedule tab: Session card shows "Live Now."

Semester about to end (1 week before EOC deadline):

• Today screen: Primary action card transitions to EOC context if student is eligible.
• Learn tab: EOC card appears at the top.
• Notification: Push notification: "Your End of Course Assessment is now available."

User Actions

Completes a lesson video:

• Learn tab: Video checkbox updates to filled/checked. If all videos in the lesson are watched, "Mark Lesson Complete" button appears.
• Today screen: Lesson status card updates to show updated progress (e.g., "2 of 3 watched" becomes "3 of 3 watched"). If all watched and lesson marked complete, card shows checkmark.
• Journey map: No change until lesson is explicitly marked complete, at which point the lesson portion of the week's status updates.

Submits a recording:

• Learn tab: Submission segment shows "Under Review" with timestamp. Attempts counter decrements.
• Today screen: Primary action card transitions to "Submission Sent" state. Submission status card shows "Submitted [relative time]."
• Behind banner (if present): Catch-up count adjusts. If no longer behind, banner disappears.
• Notification: (None outbound -- the student initiated the action.)

Listens to feedback:

• Learn tab: Feedback segment no longer shows "New" badge. Feedback marked as "Reviewed."
• Today screen: Feedback status card clears the badge. Primary action card transitions to next priority action (e.g., "All Caught Up" or "This Week's Lesson" if it is a new week).
• Notification sheet: Feedback notification marked as read.

Asks a follow-up question:

• Learn tab: Comment appears in the comment thread within the Feedback segment. Sent indicator appears.
• Coach side: Coach receives notification of new comment. (Out of scope for student app, but the data flows.)

RSVPs for a session:

• Schedule tab: RSVP toggle shows "Going" state. Attendee count increments.
• Today screen: If the session is today, it appears in the "Today's Sessions" section with "Going" indicator.

External Events

Feedback arrives from coach:

• Today screen: Primary action card transitions to "Feedback from [Coach Name]" state. Feedback status card shows badge with "1 new."
• Learn tab: Relevant week card shows "Feedback Ready" badge on header. Feedback segment populates with coach's audio and notes.
• Notification: Push notification: "Feedback Ready -- Week [N]. Coach [Name] reviewed your submission." Deep links to Learn > Week [N] > Feedback.
• Notification sheet: New notification appears with unread indicator. Bell icon badge increments.

Schedule changes (session time changed, cancelled, or new session added):

• Schedule tab: Session cards update to reflect new times or status. Cancelled sessions show "Cancelled" badge.
• Today screen: If affected session was in "Today's Sessions," it updates or is removed.
• Notification: Push notification: "Schedule Update -- [Session name] has been rescheduled to [new time]."

New announcement posted:

• Notification: Push notification with announcement content.
• Notification sheet: Announcement appears as a notification entry that can be read inline (no navigation required).
• Today screen: No change (announcements do not alter the dashboard).

Notification received (general):

• Notification bell: Badge count increments.
• Notification sheet: New entry appears at top.
• If the notification is actionable (feedback, session reminder, deadline), the relevant status card or section on Today updates accordingly.

4.7 Edge Cases & Empty States

Pre-Semester Student

Context: Completed assessment, placed in a level, assigned a coach. Semester has not started.

Today screen:

• Week header replaced with: "Semester Starts in [X] Days" (large, bold) and the date below: "[Month Day, Year] -- Saturday"
• Three info cards (replacing the status triptych):
  • "Your Level: Level [X] -- [Level Name]" with brief description
  • "Your Coach: [Name]" with photo
  • "Start Date: [Date]" with "Lessons begin unlocking 2 days before semester classes start"
• Primary action card: "Get Ready for Your Semester" with orientation video thumbnail
• Below: "Pre-Semester Sessions" showing housewarming sessions if available; "Explore Your Resources" link

Learn tab: Journey map shows all 15 weeks as upcoming. Below: a single card "Your first lesson unlocks on [date]. In the meantime, watch the orientation video to learn how the program works." Orientation video embedded.

Schedule tab: Shows pre-semester sessions if any. If none: "Live sessions begin on [date]. Here's what to expect each week:" followed by a schedule overview (types of sessions, typical days and times).

Profile tab: Full profile with coach section, settings (including font), and resources. No empty states here.

Week 1 Student (First Day)

Context: Semester just started. First lesson unlocked. No submissions yet. No feedback.

Today screen:

• Week header: "Week 1 of 15 -- Level [X]"
• Progress ring: "0%"
• Primary action card: "Your First Lesson -- Week 1: [Topic]" with "Start Lesson" button
• Status triptych: Lesson ("Not started"), Submission ("Not started"), Feedback ("No feedback yet")
• Upcoming sessions visible

Learn tab: Week 1 card expanded. Lesson segment shows videos. Submission segment: "Watch the lesson first, then record your submission." Feedback segment: "Submit your recording to receive feedback."

Behind indicator: Not shown. The student is not behind -- they are at the beginning.

Caught-Up Student

Context: Mid-semester. All lessons watched, all submissions on time, feedback reviewed.

Today screen:

• Primary action card: "You're All Caught Up -- Great work this week! Your next lesson unlocks in [X] days." with relaxed tone (green accent, checkmark icon)
• All three status cards show checkmarks
• Upcoming sessions visible
• Optional: "While you wait, consider attending a QRC this week for extra practice" suggestion

Behind Student

Context: Calendar says Week 8. Student has only completed through Week 5.

Today screen:

• Week header: "Week 8 of 15" (shows the actual calendar week, not the student's completion week -- transparency, not distortion)
• Behind banner (amber, positioned between header and primary action card): "You have 2 submissions to catch up on. You can submit up to 2 this week." Button: "Catch Up"
• Primary action card: Shows Week 6 content (the oldest incomplete) with "Start Week 6 Lesson" or "Submit Week 6" depending on lesson status
• Lesson status card: "Week 8 lesson available" (current week's lesson is still accessible)
• Submission status card: "2 behind -- catch up available"

Critical design decision -- What "Week 8 of 15" means when behind: The header always shows the calendar week (Week 8) because this is an objective fact tied to the semester timeline. Showing "Week 5" (where the student's content is) would mislead them about time remaining. Instead, the behind banner bridges the gap: the student sees they are in Week 8 of the semester but have Week 6 and 7 content to catch up on. This is honest without being shaming.

Learn tab: All weeks are visible in "All Weeks" view. Incomplete weeks (6 and 7) show "Incomplete" badges with amber borders. Current week (8) shows as the newest card. The student can work on any incomplete week.

End-of-Semester Student

Context: Week 15. Student has 13 submissions completed. EOC is available.

Today screen:

• Week header: "Week 15 of 15 -- Final Week"
• Progress ring: "93%" or "13 of 15"
• Primary action card: "End of Course Assessment" with description and "Begin Assessment" button (if eligible) or "Complete [N] more submissions to unlock EOC" (if not yet eligible)
• Behind banner (if applicable): Shows how many submissions still needed for EOC eligibility

Learn tab: EOC card appears at the very top with distinct styling (gold/amber border, graduation cap icon). Regular week cards below. Journey map shows the student near the end of the track with the EOC marker highlighted.

Year 2 Transition (Level 4 Graduate)

Context: Student has graduated from Level 4. They are eligible for QuranFlow Advanced (Year 2).

Today screen (post-graduation state):

• Header: "Level 4 -- Complete" with celebration theme
• Results card: Graduation confirmation, coach's final feedback
• Transition card: "You're eligible for QuranFlow Advanced" with key differences listed (appointments instead of submissions, elective-based curriculum) and "Learn More" button
• If next semester enrollment is available: "Enroll in QuranFlow Advanced" button

Learn tab: Journey map shows all 15 weeks completed with EOC passed. Below: a card explaining Year 2 and what to expect. All past week content remains accessible for review.

4.8 Onboarding

Trigger

Onboarding triggers on the first app launch after the student has received their level placement (assessment complete, level assigned, coach assigned). If the student opens the app before placement (assessment submitted but not yet reviewed), they see a waiting state: "We're reviewing your assessment. You'll be placed in a level within 48 hours." with a progress indicator.

What Onboarding Must Accomplish

1. Confirm the student's level placement
2. Set the Quranic font to mushaf (mandatory)
3. Introduce the assigned coach
4. Show the semester timeline and weekly rhythm
5. Set notification preferences
6. Land the student on the Today screen with full context

The Flow

Step 1: Welcome

• Full-screen card with QuranFlow branding
• "Welcome to QuranFlow, [Student Name]"
• "Let's get you set up in under a minute."
• Button: "Get Started"

Step 2: Your Level

• "[Student Name], you've been placed in Level [X]"
• Level name and one-sentence description: "Level 2: Reading with Fluency -- You'll develop ease and comfort in Quranic reading."
• Brief context: "This placement is based on the assessment you completed. If you have questions, you can contact your coach anytime."
• Button: "Next"

Step 3: Choose Your Font (Required -- cannot be skipped)

• "Choose Your Quranic Text Style"
• Two options displayed side by side, each showing a preview of the same Arabic verse:
  • Mushaf Style (Amiri Quran) -- pre-selected, labeled "Recommended. The traditional Quranic script you'll see in printed copies."
  • Simplified Arabic -- labeled "A simpler font for those who prefer it."
• The student sees the text preview update live as they toggle between options
• Button: "Confirm Font" (cannot proceed without confirming)
• Small note at bottom: "You can change this anytime in Settings."

Step 4: Meet Your Coach

• Coach's photo (circle, large)
• "[Coach Name]"
• "Your Quran Coach"
• Brief bio: 1-2 sentences about the coach's background
• "Your coach will review your weekly submissions and send personalized audio feedback. You can message them anytime."
• Button: "Next"

Step 5: Your Semester

• "Your 15-Week Journey"
• A compact visual of the semester timeline (simplified journey map): Week 1 through Week 15 with EOC at the end
• "Each week follows the same rhythm:"
  • "Watch your lesson (short videos, 3-5 minutes each)"
  • "Submit your recording for coach feedback"
  • "Attend live sessions for practice and Q&A"
• "Your semester starts [date]" (if pre-semester) or "You're in Week [X]" (if joining mid-semester)
• Button: "Start Learning"

Step 6: Notification Permission (System)

• iOS permission dialog for push notifications
• If granted: confirmation message
• If denied: "You can enable notifications later in Settings. We recommend them for feedback alerts and session reminders."

Landing:

• Student arrives on the Today screen with full context. If pre-semester, they see the countdown and orientation content. If the semester is active, they see the current week dashboard.

Constraints Met

• Under 2 minutes: 5 content steps with single-tap advancement. Even with reading time, well under 2 minutes.
• Not a tutorial: Each step delivers identity/context information, not "how to use the app" instructions. The app is designed to be self-explanatory.
• Skippable with graceful defaults: A "Skip Setup" link is available on steps 2, 4, and 5 (but NOT step 3 -- font selection is mandatory). If skipped, defaults are: mushaf font (set in step 3 regardless), system timezone, notifications enabled.
• Information findable later: Level is on Today + Profile. Coach is on Profile. Font is in Profile > Settings. Timeline is the journey map in Learn.

4.9 End-of-Semester & Graduation

EOC Assessment Flow

Eligibility: The student must have completed at least 12 of 15 weekly submissions. The EOC becomes available in Week 14 or 15 (program-defined timing).

How it surfaces:

1. Today screen: When the student is eligible, the primary action card transitions to EOC state: "End of Course Assessment -- You've completed [N] of 15 submissions and are eligible. This assessment covers all concepts from Level [X]." Button: "Begin Assessment."

2. Learn tab: An EOC card appears at the top of the week list, above Week 15 (or after Week 15, as the culminating item). It has distinct styling: gold/amber border, graduation cap icon, "End of Course Assessment" header. The card contains:

   • Description: "This final submission covers all concepts from your level. Record your best recitation of the assigned passage."
   • Quranic text passage for the EOC
   • "Record EOC Submission" button
   • Same recording interface as weekly submissions

3. Journey map: The EOC is the final node on the journey map, appearing after Week 15. When the student is eligible, this node is highlighted and interactive.

If not yet eligible:

• Today screen shows: "End of Course Assessment -- Complete [X] more submissions to unlock." with a link to the oldest incomplete week.
• Learn tab: EOC card shows a locked state: "Complete [X] more weekly submissions to unlock the End of Course Assessment."

Results Communication

Timeline: Results take up to 5 business days (longer than weekly feedback, because the coach evaluation is more thorough).

Waiting state:

• Today screen: "EOC Under Review -- Your coach is evaluating your assessment. Results expected by [date]."
• Learn tab: EOC card shows "Under Review" with submission timestamp.

Results arrive (via push notification):

• Notification: "Your EOC Results Are In -- Tap to see your Level [X] results."
• Today screen: Primary action card transitions to results state

Pass (Graduation):

• Today screen: Celebration visual (subtle confetti animation, warm colors). "Congratulations! You've graduated Level [X]!" with a summary: "[N] submissions completed, EOC passed." Below: "View Your Results" and "What's Next" buttons.
• Learn tab: EOC card shows "Passed" badge with green highlight. Full results: coach's audio feedback, written evaluation (if any), pass confirmation.
• Profile tab: Level updates to show "Level [X] -- Complete." Learning History adds an entry.
• Journey map: All nodes filled, EOC node shows a star or graduation cap.

Fail (did not pass EOC):

• Today screen: Supportive message. "Your EOC assessment needs a bit more work. Your coach has feedback to help you prepare for a retake." Button: "Listen to Feedback."
• Learn tab: EOC card shows "Retake Available" with coach's feedback and a new "Record EOC Submission" button.
• The language is encouraging, not punitive. The focus is on the path forward (retake), not the failure.

Transition to Next Level (Level 1-3 graduates)

After passing EOC:

1. Transition card on Today: "You're moving to Level [X+1]! Here's what to expect:" with a brief description of the next level's focus.
2. Key information displayed:
   • Next level name and description
   • Next semester start date (if known) or "Enrollment for next semester opens [date]"
   • Whether the coach changes: "You'll continue with Coach [Name]" or "You'll be assigned a new coach for Level [X+1]"
3. Action: "Enroll in Level [X+1]" button (if enrollment is open) or "We'll notify you when enrollment opens"
4. Access to past content: All completed level content remains accessible in Learn tab under a "Past Levels" section (accessible via a filter or segmented control on the Learn tab)

Year 2 Information (Level 4 Graduates)

After passing Level 4 EOC:

This is a special transition because the learning model changes entirely. The transition card is more detailed:

1. Celebration: Same graduation celebration as other levels.

2. Year 2 Introduction Card:

   • "You've Completed QuranFlow Essentials!"
   • "You're now eligible for QuranFlow Advanced -- our continued learning program for graduates."
   • Key differences explained clearly:
     • "No more weekly submissions -- you've mastered that skill"
     • "1-on-1 appointments with Quran Coaches for personalized guidance"
     • "Elective-based curriculum -- choose what you want to focus on"
     • "Live sessions continue (QRCs, Office Hours)"
   • "Enrollment is separate and opens [date]"

3. If enrolled in Year 2: The app transitions to Year 2 mode. The tab bar remains the same (Today, Learn, Schedule, Profile) but the content adapts:

   • Today screen: Shows upcoming appointments instead of weekly lesson/submission/feedback
   • Learn tab: Shows elective content instead of sequential week cards; no submission segments
   • Schedule tab: Includes appointment booking alongside live sessions (new "Appointments" section)
   • Profile tab: Unchanged

4. If not enrolled: The app shows a graceful post-graduation state with access to all past content and information about Year 2.

Summary of Key Decisions

Quality Bar Validation

Checking the architecture against every test from Phase 2:

Structure Tests

S1 -- The 3 Questions Test (10-second rule):

• "Where am I?" -- "Week 8 of 15 -- Level 2" visible as the dominant header on Today. PASS.
• "What can I do?" -- Primary action card shows the single most important action. Status triptych shows all three statuses. PASS.
• "Where can I go?" -- 4-tab bar at the bottom: Today, Learn, Schedule, Profile. PASS.

S2 -- No Hamburger Menu: Zero hamburger menus in the architecture. All features housed in the 4-tab structure. PASS.

S3 -- Core Task Reach in 2 Taps: Verified against every [Core] task:

• Know which week: 0 taps (visible on Today)
• Access lesson: 1 tap (Today > Start Lesson) or 1 tap (Learn tab)
• Watch video: 2 taps (Learn > video row)
• Record submission: 2 taps (Learn > Record Submission)
• Submit to coach: 2 taps to reach recording screen (submission itself is additional taps for the recording flow)
• Check feedback: 2 taps (Learn > Feedback segment)
• See schedule: 1 tap (Schedule tab)
• Join session: 2 taps (Today > session > Join) or (Schedule > session)
• Know timezone: 1 tap (Schedule tab -- timezone always displayed)
• PASS for all [Core] tasks.

S4 -- Hidden Features Eliminated: All 8 hidden features from Phase 1 have new discoverable homes (verified in Section 4.5). PASS.

Navigation Tests

N1 -- Tab Bar Destination Test: Today (destination), Learn (destination), Schedule (destination), Profile (destination). All are places. All are visited weekly. All are coherent information spaces. PASS.

N2 -- No Actions on the Tab Bar: Today, Learn, Schedule, Profile -- all nouns, all destinations. No "Record," "Submit," or "+" on the tab bar. PASS.

N3 -- First Submission Without Help: Flow 3 demonstrates the full submission path from app launch. Onboarding introduces the weekly cycle. The Today screen surfaces the submission action. The Learn tab provides the recording interface. No emails, no external help needed. PASS.

N4 -- Return Test (5-second rule): Today screen shows the submission status card: "Submitted [date]" or "Not submitted" or "Feedback ready." Visible without scrolling. PASS.

Content Tests

C1 -- No Screen Exceeds 7 Unmediated Items: Today: max 7 items (header, primary card, 3 status cards, sessions section, behind banner). Learn: weeks are collapsed by default; only current week expanded. Schedule: sessions filtered by day (typically 3-5 per day). PASS.

C2 -- The Squint Test: Today: week header is the dominant element. Learn: current week card is the dominant element. Schedule: calendar strip and today's sessions are dominant. Profile: profile card is dominant. PASS (each screen has one clear anchor).

C3 -- Week-Grouped History: Week 6 submission and Week 6 feedback are in the same week card, two segments apart (Submission | Feedback). Within one tap of each other. PASS.

C4 -- Timezone Always Displayed: Schedule tab displays timezone in header and on every session card. Today screen's session preview includes timezone. PASS.

C5 -- Standard Quranic Font on First Encounter: Onboarding step 3 sets mushaf font before the student ever sees Quranic text. Default is Amiri Quran. PASS.

Lifecycle Tests

L1 -- Pre-Semester State: Today screen shows: level (card 1), coach name and photo (card 2), days until semester start (header), and orientation video (primary action card). All four elements visible. PASS.

L2 -- Behind Test: Behind banner on Today: "You have [X] submissions to catch up on. You can submit up to 2 this week." Catch-up path is 1 tap ("Catch Up" button). Language is neutral. PASS.

L3 -- EOC Phase State: EOC card is the primary action on Today when eligible. "Begin Assessment" button reaches EOC submission in 2 taps. PASS.

L4 -- Recovery Test: Profile tab is 1 tap away from any screen. Help Center is 2 taps from any screen (Profile > Help Center). Coach messaging is 2 taps from any screen (Profile > Message Coach). PASS.

Notification Tests

V1 -- Notification Deep Links: Every notification type has a defined deep link target (specified in Section 4.6 and the Notification Sheet screen). Feedback notifications link to Learn > Week > Feedback. Session reminders link to Schedule > Session. PASS.

V2 -- Notification Content: Every notification includes: what happened (type), which submission/session (by week number and title), and when (relative timestamp). Specified in Notification Sheet content. PASS.

Capability Map Coverage Estimate

The architecture provides a defined home for 93% of all capabilities in the User Capability Map. The 4 uncovered items are: external signup (out of scope), elective selection for Year 2 (deferred to Year 2 design phase), and two minor enhancements (community board -- deprioritized per PM assessment that it "lacks vision"; detailed performance analytics -- available as a future enhancement to the Learn tab).

5. Validation Report

Version: 1.0 Date: February 25, 2026 Input: Phase 4 Architecture Specification v1.0 Validator role: Independent review against Phase 2 quality bar, WWDC25 Field Guide tests, User Capability Map [Core] tasks, and P0 issues from Phase 1 Verdict: CONDITIONAL PASS -- architecture is sound; 4 findings require resolution before implementation

5.1 How This Validation Was Conducted

Each test was evaluated by checking the specific claim against the specific evidence in the Phase 4 document. Where the architecture makes a tap-count claim, the actual flow table was traced step by step and the count was verified independently. Where the architecture claims a feature is discoverable, the path was reconstructed from the screen specifications and navigation hierarchy. Failures and borderline cases are noted explicitly. The architecture's own self-assessment (Section 4's "Quality Bar Validation") was treated as a claim to be verified, not as evidence.

5.2 Validation Checklist

The following tests are drawn from the WWDC25 Field Guide and Phase 2 design principles. Each is evaluated against the Phase 4 architecture specification.

5.3 [Core] Task Coverage

The following table traces every [Core]-tagged task from the User Capability Map (Sections 2-6) through the Phase 4 architecture. The tap count is measured from the tab bar -- meaning the student is already in the app, on a tab. "0 taps" means visible on the current screen. "1 tap" means one interaction from the tab bar or current screen. All counts assume the student is starting from the app launch state (Today screen visible).

[Core] Task Coverage Summary

Total [Core] tasks in User Capability Map: 27 Fully covered: 24 Partially covered or underspecified: 3 (Year 2 appointment tasks 5A.1 and 5A.2, and the pre-assessment waiting state for 2A.2) Not covered: 0

Note: Tasks 5A.1, 5A.2, and 5A.3 (Year 2 appointment management) are referenced in the architecture but have no corresponding screen specifications. The architecture explicitly defers this to a Year 2 design phase, which is a reasonable decision but should be documented as out-of-scope rather than counted as covered.

5.4 P0 Issue Resolution

The six P0 issues from the original audit, plus "feedback hard to find" from the PM Discussion (treated as P0 in the Capability Map):

P0 Resolution verdict: All 7 P0 issues are addressed at the architecture/design level. Two items (video playback and notification delivery) have engineering dependencies that the architecture cannot guarantee but correctly specifies.

5.5 Tap Count Audit

The following audits the claimed tap counts against the actual flow steps in the Phase 4 document. A "tap" is defined as one deliberate user interaction (press, tap). Opening the app does not count as a tap. Navigating to a tab counts as 1 tap.

Claimed: All [Core] tasks reachable in 2 taps (Phase 2 test S3)

5.6 Findings and Recommendations

FINDING 1 -- Join Session Tap Count is Misleading (Medium Severity)

What the architecture claims: "Total taps on critical path: 2 (Open > session card > Join Zoom)" for Flow 5.

What actually happens: The "Join Zoom" button is only active "when session is within 15 minutes of start or currently live." If a student taps a session card outside that window, they reach the Session Detail modal -- but the Join button is inactive. They cannot join from there. To join, they must wait until the button activates. This is not a design flaw (the session cannot be joined before it starts), but the tap-count claim conflates two different moments in time. The claim is technically true only at the exact moment the student is joining a live or imminent session. For any other use of the 2-tap path (checking session details, adding to calendar, RSVPing), the count is accurate but the "Join" action is not available.

Impact: The 2-tap-to-join claim is correct for the live-session scenario. It is potentially confusing in documentation when the student follows the same 2-tap path and finds the Join button grayed out.

Recommendation: In the Session Detail modal spec, explicitly state what the student sees when "Join Zoom" is inactive: a countdown ("Join available in [X] hours [Y] minutes") so the modal is useful and not confusing at any time of day. The Architecture section 4.3 Schedule screen addresses "Not yet available" as a P1 fix but does not specify what inactive Join looks like in the modal. This needs to be specified.

FINDING 2 -- Tap Count Discrepancy in Flow 3 Summary (Low Severity)

What the architecture claims: "Taps from app launch to recording start: 4" (Flow 3 summary line).

What the actual flow table shows:

• Step 1: Open app (Today, primary action card shows "Record Submission")
• Step 2: Tap "Record Submission" (opens Learn, Submission segment) -- this is tap 1
• Step 3: Tap "Record Submission" button in Submission segment (opens Recording Screen) -- this is tap 2
• Step 4: Tap Record (starts recording) -- this is tap 3

The recording starts at tap 3, not tap 4. The flow table itself has 9 steps but only 7 are actual taps -- steps 1 and 6 are passive events (opening app, listening to recording). The "4" figure appears to be an error in the summary line. The actual count (3 taps to recording start) is better than claimed, not worse.

Impact: The architecture passes its own targets -- this is a documentation inconsistency, not a design failure. However, it signals that the tap counts in the summary lines were not cross-checked against the actual flow tables. Other summary claims may have similar drift.

Recommendation: Before finalizing the document for handoff to engineering, reconcile every tap-count summary line against its corresponding flow table. Specifically check Flow 2's "5 taps on critical path" (tracing: Today > Start Lesson (1) > Learn tab with Lesson segment > video tap (2) > back (3) > Video 2 tap (4) -- that's 4 taps to complete two videos, not 5 including "Mark Complete" which would be 5 -- this appears correct), and Flow 5's "2 taps" claim which is correct only at join time.

FINDING 3 -- Pre-Assessment Waiting State is Underspecified (Medium Severity)

The gap: Section 4.8 (Onboarding) notes: "If the student opens the app before placement (assessment submitted but not yet reviewed), they see a waiting state: 'We're reviewing your assessment. You'll be placed in a level within 48 hours.'" Section 4.3 Today screen mentions it: "Empty / First Use (post-assessment) -- Waiting for level placement."

What is missing: No specification of what the other tabs show in this state. If a student taps Learn, Schedule, or Profile before receiving placement, what do they see? The current architecture specifies Today's waiting state but leaves the other three tabs undefined. This matters because:

1. Students will explore the app while waiting 48 hours for placement
2. An empty or broken tab during this waiting period creates the exact disorientation the architecture is designed to prevent
3. Phase 2 Principle 5 ("No dead ends") requires that every state provides a clear next action or orientation

Impact: Medium. This is a transition state that every student passes through. If the other tabs show errors or empty screens, it undermines the onboarding experience at the most critical moment (first impressions).

Recommendation: Add a "Pre-Placement" state to the Learn, Schedule, and Profile tab specifications. Minimum viable:

• Learn tab (pre-placement): "Your journey begins once you're placed in a level. Assessment results expected within 48 hours." with orientation video embedded.
• Schedule tab (pre-placement): Show pre-semester/housewarming sessions if available, or "Sessions begin once your semester starts" with expected date if known.
• Profile tab (pre-placement): Already handled ("Never truly empty. Even pre-semester, the profile card shows the student's name, level, and assigned coach.") -- but if level and coach are not yet assigned, this promise cannot be kept. Specify the fallback: "Level: Pending Assessment Review" with expected timeline.

FINDING 4 -- Year 2 Appointment Flow Has No Screen Specification (Low-to-Medium Severity, Scope-Dependent)

The gap: The architecture correctly identifies Year 2 as a different learning model and describes how the tab bar adapts. Section 4.9 states: "Schedule tab: Includes appointment booking alongside live sessions (new 'Appointments' section)." But no screen specification exists for:

• How appointment slots are displayed (calendar? list? TA-by-TA?)
• How booking confirmation works
• How appointments relate to the Today screen in Year 2 mode
• What the Learn tab shows for elective content

Why this matters: The architecture document covers Year 1 Year-2 transition at the graduation level (Section 4.9) and at the tab-adaptation level ("Today screen: Shows upcoming appointments instead of weekly lesson/submission/feedback") but the actual interaction model for Year 2 is unspecified. Three [Core] tasks for Year 2 students (5A.1, 5A.2, 5A.3) have no home in the architecture's screen specs.

Scope judgment: If Year 2 is explicitly out of scope for this design phase, this should be stated clearly in the document as a known gap rather than left implied. The Capability Map Coverage table in Section 4 says "75%" for Year 2 but the reality is closer to 25% (only the transition experience is designed; the actual Year 2 interaction model is not).

Recommendation: Either (a) add a note to Section 4.9 explicitly stating "Year 2 interaction design is deferred to a separate design phase; this architecture covers only the Year 1-to-Year 2 transition experience" and remove Year 2 tasks from the coverage count, or (b) add a basic Year 2 screen specification for the Schedule tab's Appointments section and the Learn tab's elective content view. Option (a) is faster and honest.

FINDING 5 -- C1 (7-Item Rule) Needs Verification for Live Session Edge Cases (Low Severity)

The concern: Phase 2 test C1 states "No default list view shows more than 7 items without a progressive disclosure mechanism." The architecture claims PASS.

The edge case: The Schedule tab's session list is filtered by day by default (the calendar day strip highlights the current day). This is an effective progressive disclosure mechanism -- it reduces a potential 20-session week to the 3-5 sessions on a given day. However, the architecture does not specify a maximum number of sessions per day before a further disclosure mechanism is triggered. On a day with, say, 8 sessions (multiple QRC time slots across different gender/level groupings), the list would exceed 7 items.

Evidence from Phase 1: "Up to 20 sessions per week" is documented. While 8+ sessions in a single day is unlikely, it is not impossible during peak weeks.

Impact: Low. The day-level filtering already provides strong scannability. The failure mode (8+ sessions on one day) is rare and still preferable to the current "wall of unstructured text" described in the audit.

Recommendation: Add a soft cap to the Schedule tab spec: "If more than 7 sessions are displayed for a single day, group them by session type (Level Classes, QRCs, Office Hours) with collapsed sections, each expandable. Show count in collapsed header: 'QRCs (5)' -- tap to expand." This would satisfy C1 formally and improve scannability on dense days.

5.7 Summary Assessment

What the Architecture Gets Right

The architecture's core design decisions are well-reasoned and directly address the problems identified in the audit. The weekly rhythm organizing principle is correct for this user population. The four-tab structure is correct -- it passes the Tab Worthiness Test at every position. The Today screen design is the strongest part of the document: the week header as the dominant visual element, the context-dependent primary action card, and the status triptych together solve the disorientation problem completely.

The P0 issues are resolved in the right places. Font is addressed in onboarding (not just settings). Feedback is co-located with submissions (not in a separate archive). Notifications are specified with content and deep links. The schedule is a tab (not 5 clicks deep). The profile is a full information hub (not a minimal screen).

The progressive disclosure approach throughout (day-filtered sessions, "This Week" default on Learn, collapsed week cards, "See Full Schedule" from Today) is correct and consistent with the WWDC25 Field Guide principles.

The lifecycle state machine is thorough: pre-semester, active (default, submission pending, feedback ready, all done, behind), EOC phase, graduation, Year 2 transition. Each state is specified for the Today and Learn screens. This is production-ready thinking.

What Needs Resolution Before Implementation

Overall Verdict

CONDITIONAL PASS. The architecture satisfies all mandatory Phase 2 quality bar criteria for Year 1 design. The four open findings are gaps rather than design failures -- they do not invalidate the core structure or require revisiting the fundamental decisions. Findings F1 and F3 should be resolved before the document is handed to engineering, as they affect states that every student will encounter. Findings F2, F4, and F5 can be addressed in a targeted revision or carried forward into the detailed design phase with explicit documentation.

The architecture is ready to proceed to detailed design (wireframes/mockups) for Year 1, with the understanding that the five findings above are resolved either in a document revision or in the wireframe phase.

Appendix: Source Materials

The following 8 documents were the primary inputs to this specification. Each phase output drew on a subset of these materials; the complete list represents the full evidence base behind the architectural decisions.