Phase 4 — Architecture Specification

Phase 4 -- Architecture Specification

Version: 1.3 (updated with Learn screen amendments and Schedule screen amendments from implementation findings) Date: February 26, 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 weekly learning workspace). 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, with the current week as the default workspace.

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 in "All Weeks" view with journey progress indicator 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 (weekly learning workspace with [This Week / All Weeks] toggle) Level 1: Week Content (vertically stacked Lesson, Submission, and Feedback sections in continuous scroll) 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 has two modes. "This Week" (default) shows the current week's content as a full workspace with three vertically stacked sections -- Lesson, Submission, Feedback -- in a continuous scroll. The hero header mirrors the Today screen's visual anchor pattern (week number at display size with progress ring). "All Weeks" shows all 15 weeks as compact rows in a single grouped card, with a simplified journey progress indicator at the top.

Each week's content is presented as three vertically stacked sections -- Lesson, Submission, Feedback -- with labeled section headers matching the Today screen's pattern. The vertical layout means all three areas are discoverable by scrolling (no hidden panes), and the natural reading flow mirrors the weekly workflow sequence (learn -> submit -> receive feedback).

• Lesson section: Video list with thumbnails, per-video watch status, duration, and play buttons. Learning objectives displayed above videos.
• Submission section: Quranic text display in dedicated card, submission CTA (gradient card matching Today's Primary Action Card), submission history, attempts remaining counter.
• Feedback section: Coach's audio feedback with playback controls, timestamp, comment thread for follow-up questions.

Empty state (pre-semester): "This Week" view shows a single orientation card: "Your first lesson unlocks on [date]. In the meantime, watch the orientation video." with the orientation video embedded. "All Weeks" view shows journey progress indicator with all 15 weeks as upcoming.

Pre-placement state (assessment submitted, awaiting level placement): "Your journey begins once you're placed in a level. Assessment results expected within 48 hours." with the orientation video embedded below. Journey progress indicator is not yet visible (level unknown).

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 structural design from the mockup, which achieved 95% alignment and zero missing elements. It includes: timezone selector in the header, combined week + day header (merging the week navigator and calendar day strip into a single row), session type filters (All / Level Classes / QRCs / Office Hours), session cards with type badges and state-dependent visual treatments (Live Now, Starting Soon, Upcoming, Ended), Join Zoom buttons, Add to Calendar buttons, RSVP toggles, and deadline cards with urgency-based styling. The visual hierarchy optimizes for scanning speed -- session times and type badges are the most prominent elements, and "Live Now" sessions pin to the top of the list.

A segmented control at the top provides access to recordings: Upcoming | Recordings. The Recordings view shows recorded sessions for previous weeks in a grouped card format (matching the Learn screen's "All Weeks" pattern), with session type labels, dates, watch status indicators, and day-based grouping. 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).

Pre-placement state (assessment submitted, awaiting level placement): Shows pre-semester housewarming sessions if available, or "Sessions begin once your semester starts" with expected timeline. Session type explanations are visible so the student understands what Level Classes, QRCs, and Office Hours are before the semester begins.

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.

Pre-placement state (assessment submitted, awaiting level placement): Profile card shows the student's name. Level displays "Pending Assessment Review" with expected timeline. Coach section shows "Your coach will be assigned once you're placed in a level." All settings (font, notifications, display) and support (Help Center, Resources, Contact Support) are fully accessible.

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's Lesson section visible
• Tapping the submission status card navigates to Learn tab, scrolled to the current week's Submission section
• Tapping the feedback status card navigates to Learn tab with the relevant week's Feedback section visible
• 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 (Weekly Learning Workspace)

Purpose: Provide the student's weekly learning workspace -- the place where they watch lesson videos, read the assigned Quranic passage, submit their recording, and review coach feedback. The current week's content is the default view and primary focus.

The complete learning journey (all 15 weeks with statuses) is a secondary view for navigation, review, and catch-up -- accessed via the "All Weeks" toggle.

Two distinct modes with distinct purposes:

The student's mental model: "I tap Learn to do my weekly lesson." Not "I tap Learn to see a map of my semester."

Content (top to bottom):

Navigation Bar:

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

Segmented Control:

• [This Week] [All Weeks]
• "This Week" is the default view -- the weekly learning workspace
• "All Weeks" is the secondary view -- journey overview and navigation

"This Week" View (Default -- Weekly Learning Workspace)

Visual Hierarchy (matching Today's specificity):

The Learn screen mirrors the Today screen's visual hierarchy pattern, adapted for its workspace purpose:

Above-the-fold rule: On first load, the student must see: the week number and "of 15", the topic name, and the beginning of the Lesson section (first 1-2 video rows) -- without scrolling. Submission and Feedback sections are below the fold.

Squint Test target (Phase 2, C2): When the screen blurs, the week number ("Week 8") remains identifiable as the dominant element. The progress ring is the second identifiable element. The video list card is the third.

Hero Header:

• Line 1 (Display serif, 58pt, font-black): "Week 8 of 15" -- identical treatment to Today's week header
• Line 2 (15pt, semibold, foreground/80): "[Full Topic Name]"
• Line 3 (13pt, muted foreground with icon): "Level 2 · 3 videos · 12 min"
• Right-aligned: Progress ring (56pt) showing lesson completion (e.g., "2/3")

The hero header is the visual anchor. It answers "Where am I?" and "What am I working on?" instantly. No journey map appears in this view -- the hero section provides complete temporal context.

The week's content is presented as three vertically stacked sections -- Lesson, Submission, and Feedback -- in a continuous scroll. Each section has a labeled header matching the Today screen's section header pattern (11pt, bold, uppercase, letter-spaced, muted foreground).

LESSON Section:

Section header: "LESSON" (11pt, bold, uppercase, tracked, muted foreground)

• Learning objectives: A subtle info block between the section header and the video list. Not a separate card -- a muted text block with a small icon (lightbulb or book) and 2-3 short bullet points in 13pt body text. Background: transparent or very subtle tint. No border. After the first visit, collapses to a single line ("3 learning objectives") with expand chevron -- progressive disclosure per WWDC25 Field Guide Part 3. The student sees it fully once, then it gets out of the way.

• Video list: Each video as a row within a single grouped card (bg-card, rounded-xl, border border-border/60), separated by subtle dividers. Each row contains:

  • Thumbnail (52x38pt, rounded corners, 8pt radius): A small visual preview representing the video content. Displays a centered play icon overlay on a topic-appropriate background.

    • For mockup: Use varied gradient backgrounds (shifting hue per video within the purple family) to create visual distinction between videos.
    • For production: Replace gradients with actual video preview frames or topic-appropriate illustrations.
    • Watched state: Thumbnail background desaturated (reduced chroma) to indicate completion.

  • Title and metadata:

    • Line 1: "Video [N]: [Title]" -- 14pt, semibold for unwatched / medium weight + muted color for watched
    • Line 2: Duration + watched indicator -- 12pt, muted secondary text (e.g., "3:45 · Watched")

  • Status indicator:

    • Watched: Filled green checkmark circle (24pt diameter)
    • Unwatched: Right chevron indicating tappability

  • Progress footer (inside the card, below the last row): A thin progress bar showing videos watched out of total, with a count label (e.g., "2/3"). This mirrors the progress ring in the hero section but in a linear format appropriate for the detail level.

  • Tap target: entire row opens Video Player screen

• Below the video card: "Mark Lesson Complete" button (appears after all videos watched; includes confirmation dialog; reversible)

Layout rationale (WWDC25 Field Guide, Part 3): The video list uses a List layout (not Grid) because the items have text titles and heterogeneous metadata (title, duration, status). Thumbnails add visual differentiation within the list pattern. Items are grouped in a single card per the "Grouping by Progress" strategy.

SUBMISSION Section:

Section header: "SUBMISSION" (11pt, bold, uppercase, tracked, muted foreground)

Quranic Text Display:

The assigned passage is presented in a dedicated display card that signals its sacred nature through visual treatment:

• Container: A distinct card with warm, slightly elevated background -- using a subtle warm tint (e.g., oklch(0.97 0.01 75)) that differs from the standard card background. Rounded corners (16pt radius). No hard border -- instead a very subtle shadow or soft border to create gentle separation. Generous internal padding (20pt horizontal, 24pt vertical).
• Typography: Amiri Quran font at 26-30pt (large enough for comfortable reading with diacritical marks). RTL text direction. Line height of 1.8-2.0x to accommodate Arabic marks (tashkeel) without overlap. Text centered horizontally within the card.
• Passage reference: Below the Arabic text, separated by 12pt of space: Surah name and ayah range in the body font at 13pt, muted foreground (e.g., "Surah Al-Mulk, Ayat 1-4"). Left-aligned (LTR) since this is transliterated text.
• Minimum card height: 120pt, to ensure the sacred text has visual prominence and breathing room even for short passages.
• Font is mushaf by default -- no settings change required (P0 fix).

Rationale: The Quranic text is what distinguishes QuranFlow from a generic learning app. Proper visual treatment of the Arabic calligraphy elevates the entire design and signals respect for the content. Users are reading sacred text -- the visual environment should reflect that.

Submission CTA (state-dependent visual treatment):

The Quranic text card sits directly above the submission CTA, creating the visual flow: read the passage -> record your recitation. The text card and CTA should feel like one unit.

• Tapping the CTA button in "Not yet submitted" state navigates to the Recording Screen (Level 2)
• Submission history below the CTA: A list of past attempts for this week (if any), each showing timestamp and status (Submitted / Under Review / Feedback Ready)

FEEDBACK Section:

Section header: "FEEDBACK" (11pt, bold, uppercase, tracked, muted foreground)

• If no submission yet: "Submit your recording to receive feedback from your Quran Coach." -- displayed as a muted placeholder card.
• 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. Displayed as a standard card with amber-tinted icon.
• If feedback is available:
  • Coach avatar and name: "[Coach Name]'s Feedback" -- displayed as a prominent card
  • 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)

"All Weeks" View (Secondary -- Journey Overview & Navigation)

Journey Progress Indicator:

A simplified horizontal progress indicator appears at the top of this view:

• A thin horizontal track (2pt height) connecting 15 small status dots
• Completed weeks: small filled circles (8-10pt) in primary accent color
• Current week: slightly larger filled circle (20pt) with week number, accent color, subtle glow/ring
• Behind weeks: filled circles in amber with alert indicator
• Upcoming weeks: hollow circles in muted color
• Graduation icon at the end of the track (star or graduation cap)
• Below the track: summary text -- "Week 8 of 15 -- 4 completed, 2 behind"

Critical design decision: The dots are visual status indicators, not interactive tap targets. The week list below serves as the interactive navigation. This solves the 44pt minimum tap target problem (15 circles on a 390px screen would each get approximately 20px of space, well below Apple's guideline) and eliminates the need for scroll-to behavior.

Visual Hierarchy (All Weeks View):

Week List:

Past and future weeks are displayed as compact rows within a single grouped card (bg-card, rounded-xl, border border-border/60, dividers between rows). This matches the video list card pattern and the Today screen's session card pattern.

Row layout:

• Left: Week number (bold, tabular, fixed width)
• Center: Topic name (regular weight, truncated if needed)
• Right: Status badge + chevron

Status badges: "Complete" (green) / "In Progress" (blue) / "Not Started" (gray) / "Feedback Ready" (amber with dot) / "Behind" (amber)

Expansion behavior (progressive disclosure, per WWDC25 Field Guide Part 3):

When a row is tapped, it expands inline to show a compact status summary -- three mini-status indicators in a horizontal row:

Plus a "View Full Week" action that loads the complete week content in the workspace layout (replacing the current view with "This Week" mode for the selected week).

Why not full inline expansion: Expanding a past week to show its complete content (video list + Quranic text + feedback audio player) inside a card row creates extreme layout disruption. The expanded state would be 5-10x the height of the collapsed row, breaking the visual rhythm. The compact summary provides status at a glance, and "View Full Week" provides the escape hatch for full content. This follows the Progressive Disclosure pattern: show the top-level summary, add a disclosure indicator, let the user tap through to the full content.

States:

Behaviors:

• Tapping a video row opens the Video Player in full-screen
• Tapping the submission CTA button 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
• In "All Weeks" view, tapping a week row expands it inline to show the compact status summary; tapping "View Full Week" loads that week's full content in workspace layout
• Only one week row is expanded at a time in "All Weeks" view (accordion behavior)
• Toggling between "This Week" and "All Weeks" preserves scroll position within each view
• Pull-to-refresh updates all week statuses and section content
• New feedback arrivals update the Feedback section in real time and show an accent indicator on the hero header

Connection to other screens:

• Navigates TO: Video Player (from video row in Lesson section), Recording Screen (from submission CTA in Submission section), Feedback Detail (from feedback audio in Feedback section -- 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 Learn tab
• 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, Submission section's CTA button
• Navigates TO: Returns to Learn tab Submission section 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 Learn tab's Lesson section
• 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 Lesson section's video list (checkmark and thumbnail desaturation)
• Background audio continues if the student switches away briefly (configurable)
• Subtitles/captions available if provided

Connection to other screens:

• Navigated FROM: Learn tab, Lesson section, video row
• Navigates TO: Returns to Learn tab's Lesson section; 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. The Schedule screen optimizes for scanning speed -- students come with a specific temporal question ("When is my next session? How do I join it?") and need to find the answer fast.

Content (top to bottom):

Navigation Bar:

• Title: "Schedule"
• Right: Timezone selector button showing current timezone (e.g., "EST") -- 13pt, semibold, primary color

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]
• Standard iOS segmented control, compact

Upcoming View

Visual Hierarchy (Schedule -- Upcoming View):

The Schedule screen's visual design optimizes for scanning speed, not emotional anchoring. Unlike Today and Learn (which use 58pt hero headers to answer "Where am I in the semester?"), the Schedule screen answers "When is my next session?" -- a question best served by prominent session cards, not a hero header.

Above-the-fold rule: On first load (current week, current day selected), the student must see at least 2 session cards without scrolling. If no sessions exist today, the "no sessions" message and the next session preview must be visible without scrolling.

Squint Test target (Phase 2, C2): When the screen blurs, the student should identify a vertical rhythm of session cards with colored type badges on the left edge and time values standing out. On a day with a live session, the green "Join" button should be the single most identifiable element. On a normal day, the time column and type badges create the visual structure.

Week + Day Header (combined single row):

A single row combining week context and day selection, replacing the separate week navigator and calendar day strip to reduce navigation chrome and ensure session cards appear above the fold:

• Left edge: Week label -- "Wk 8" in 13pt bold, tabular, muted foreground. Doubles as tap target to return to current week.
• Center: 7 day circles (Sat through Fri), each 36pt diameter within a 44pt touch target area. Current day: filled circle in primary accent color with white day label. Days with sessions: small dot below the circle (4pt, primary color). Other days: outlined circle with muted day label.
• Right edge: Subtle forward arrow (16pt, muted). Left arrow at left edge of the day circles.
• Total row height: 56pt (including top/bottom padding).
• Week advancement: Tapping arrows or swiping the day strip horizontally navigates to adjacent weeks. A brief "Week 9" label flashes during the transition to confirm the change.

Session Type Filters:

• Horizontal pill buttons: All | Level Classes | QRCs | Office Hours
• "All" selected by default with primary-color text and subtle primary tint background (oklch(0.95 0.03 285))
• Inactive pills: 12pt, medium weight, muted foreground, transparent background with subtle border (border-border/40)
• Active pill: Primary color text, rounded-full, subtle primary tint background
• Row height: 32pt total (pills are 28pt with 2pt vertical margin). Individual pill widths exceed 44pt, satisfying the tap target requirement.

Session Cards (individual cards, list below filters):

Each session card follows the Card Pattern (bg-card, rounded-xl, border border-border/60) with the following internal structure:

• Time column (fixed width, 64pt): The most scannable element. Time in 15pt bold tabular figures (high contrast foreground). Timezone abbreviation below in 10pt medium weight, muted foreground.
• Vertical divider: 1px line, border-border/80, 40pt height. Separates time from content. This consistent left edge creates a visual rhythm that makes scanning a list of sessions fast.
• Content area (flexible):
  • Row 1: Type badge (Status Badge Pattern -- 10pt semibold uppercase, rounded pill, color-coded) + coach name (12pt, medium, muted) when applicable.
  • Row 2: Session title -- 13pt, semibold, foreground, single line truncated.
  • Row 3 (optional): Metadata -- gender indicator ("Sisters" / "Brothers"), RSVP count ("12 attending"), in 12pt muted text. Only shown when relevant data exists.
• Action area (fixed width, right-aligned): ChevronRight icon (16pt, muted) for upcoming sessions. "Join" button for live/starting-soon sessions (see below). Countdown text for distant sessions.

Type badge colors (consistent with Today screen):

Touch interaction: active:scale-[0.99] on press (slightly less than the standard 0.97 because session cards are wide -- aggressive scaling on wide elements looks jumpy), 150ms ease-out transition, touch-manipulation.

Session card spacing: 8pt gap between cards. Individual cards (not grouped) because session cards are heterogeneous (different types, different action states, interspersed deadline cards) and each must be a distinct tappable unit.

Session Card State Treatments:

"Live Now" state (session currently in progress):

The most time-critical state in the entire app. The student needs to join immediately.

• Card border: 1px solid green accent (oklch(0.70 0.15 155 / 0.4)) replacing standard border-border/60.
• Time column replacement: Time value replaced by a "Live" indicator:
  • Pulsing dot (6pt diameter, oklch(0.55 0.18 150), CSS animation: 1.5s ease-in-out infinite pulse between 100% and 40% opacity)
  • "LIVE" label: 10pt, bold, uppercase, oklch(0.40 0.12 155)
  • Start time below in 11pt muted (so the student still knows what time it started)
• Join button (replaces chevron): High-contrast action button:
  • Background: oklch(0.50 0.15 155) (rich green)
  • Text: "Join" in 13pt bold white, with small Video icon (14pt) to left
  • Rounded-lg, px-3.5 py-2
  • Shadow: 0 2px 8px oklch(0.50 0.15 155 / 0.25)
  • This button is the highest-urgency interactive element on the screen
• Card background: Standard bg-card (no background tint). The green border and Join button provide sufficient differentiation.
• Pinning: "Live Now" and "Starting Soon" cards are pinned to the top of the session list, separated from chronological sessions below by a subtle "Happening Now" section header (Section Header Pattern). This ensures the student never scrolls past ended sessions to find their urgent session.

"Starting Soon" state (within 15 minutes of session start):

• Card border: Standard border-border/60 (no change)
• Time column: Standard time display + "in 12 min" below timezone in 11pt, semibold, primary color (updates every minute)
• Join button appears: Same green "Join" button as "Live Now" state (Zoom link active 15 minutes before start)
• Pinning: Pinned to top alongside any "Live Now" cards

"Upcoming" state (default):

• Standard Card Pattern treatment
• Time column with time and timezone
• ChevronRight on right edge
• When inactive: disabled countdown text replacing chevron ("Join in 2h 15m" -- 11pt, muted)

"Ended" state:

• 60% opacity on entire card
• Time column: standard time, "Ended" label below in 11pt muted
• No chevron, no Join button. If a recording is available, show a small "Recording" link (12pt, primary color) instead.

Visual priority stack for session states:

Dense Day Handling: If more than 7 sessions are displayed for a single day (after pinned cards), sessions are grouped by type (Level Classes, QRCs, Office Hours) with collapsed sections. Each collapsed header shows the type name and count: "QRCs (5)" -- tap to expand. Expanded sections use the grouped card pattern (single card with dividers between rows). This satisfies the 7-item progressive disclosure rule while maintaining scannability on days with many sessions.

Deadline Cards (interspersed with sessions at chronological position):

Deadline cards use a distinct visual treatment to prevent confusion with session cards. They appear at their chronological position (e.g., a Friday 11:59 PM deadline appears after Friday's last session).

Base treatment (deadline > 24 hours away):

• Dashed border (1px, border-border/60, dash pattern: 6px dash, 4px gap)
• Background: transparent (no fill)
• Content: Clock icon (16pt, muted) + "Submission Deadline" label (12pt, semibold, muted foreground) + date and time with timezone (13pt, medium, foreground)
• No action button -- tapping navigates to Learn tab's Submission section
• Height: compact single row (~52pt)

Approaching treatment (deadline within 24 hours):

• Dashed border color shifts to amber (oklch(0.72 0.12 75 / 0.6))
• Background: subtle amber tint (oklch(0.97 0.02 75))
• Label changes to: "Due Tomorrow" or "Due Today" (12pt, semibold, oklch(0.45 0.12 60))
• Time rendered in bold (13pt, bold, foreground)

Imminent treatment (deadline within 3 hours):

• Border: amber, solid instead of dashed (urgency overrides the "dashed = deadline" signal)
• Background: warmer amber tint (oklch(0.95 0.04 75))
• Label: "Due in [N] hours" (12pt, bold, oklch(0.40 0.12 55))
• If submission not yet submitted: small CTA "Submit Now" link (12pt, semibold, primary color) on the right

Passed treatment (deadline has passed):

• 50% opacity, standard dashed border
• Label: "Deadline Passed" with date
• If submission was made: "Submitted" badge (green pill)
• If not submitted: "Missed" in amber, muted

Note: If the current week's submission is already sent, the deadline card shows a subtle "Submitted" checkmark and uses the base (muted) treatment regardless of time proximity. Urgency states only apply when the submission is still pending.

Recordings View

The Recordings view uses the same Week + Day Header as the Upcoming view (shared navigation element) and the same session type filter pills ("All" selected by default).

Recordings List:

Below the header, recordings are presented in a grouped card (bg-card, rounded-xl, border border-border/60) with dividers (border-border/40), grouped by day within the selected week. The grouped card pattern matches the Learn screen's "All Weeks" week-list pattern and is appropriate here because recordings are a review list (no urgent actions, compact scanning).

Day group header (within the grouped card):

• Day name and date: "Tuesday, Feb 24" -- 12pt, bold, muted foreground
• Recording count: "3 recordings" -- 11pt, muted, right-aligned
• Slightly different background tint (oklch(0.96 0.005 85)) from recording rows for visual separation

Recording row layout:

• Left: Session type badge -- Same color-coded pill as session cards (Status Badge Pattern). Provides instant visual scanning of recording types.

• Center:

  • Line 1: Session title -- 13pt, semibold, foreground
  • Line 2: Date, time, and duration -- 12pt, muted (e.g., "Feb 24, 7:00 PM EST · 45 min")

• Right:

  • Unwatched: "New" badge (small accent pill, 10pt) + chevron
  • Watched: Checkmark icon (16pt, green, muted) + chevron
  • Partially watched: Small progress indicator (thin bar showing percentage, below the title line)

• Sorted by date within each day group, most recent day first

• Tapping a recording row opens the recording player

Progressive disclosure for dense weeks: If a week has more than 10 recordings, the grouped card shows the first 7 rows with a "Show all [N] recordings" footer link (Phase 2 Content Principle 1 -- 7-item rule).

Empty state: "No recordings for this week yet. Recordings appear here after live sessions end." Displayed as muted centered text (13pt, muted foreground) within a single card container.

Schedule Pattern References

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, session type explanation (see below), 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 in grouped card format
• Pull-to-refresh updates session list and live status
• "Live Now" and "Starting Soon" cards are automatically pinned to the top of the session list
• Ended sessions fade to 60% opacity and lose their action buttons; recording links appear when available

Session Detail Modal -- Session Type Explanations:

The Session Detail modal includes a one-line type explanation below the type badge, providing just-in-time context for new students:

This explanation appears in 13pt body text, muted foreground, directly below the session type badge in the modal header. After the student's third visit to Schedule (tracked locally), the explanation collapses to show only on tap of a small info icon next to the type badge -- progressive disclosure that serves Week 1 students without patronizing Week 8 students.

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), Learn tab (from deadline card tap)

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 section
  • Session reminder: Schedule tab > relevant session
  • Deadline reminder: Learn tab > relevant week > Submission section
  • 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

Screen: Onboarding Flow (First Launch)

Purpose: Orient a new student to the app in under 2 minutes, setting critical defaults and providing essential context.

This is detailed fully in Section 4.8.

4.3.5 Visual Design Language (Shared Across All Screens)

This section defines the shared visual patterns used across all screens. Defining them once ensures visual consistency and prevents the drift that occurs when each screen specification re-describes (or fails to describe) the same patterns.

Rationale: Three rounds of Learn screen implementation revealed that without explicit visual pattern definitions, each screen's implementation diverges from established patterns. This section codifies the patterns established by the Today screen and applied consistently across the app.

Hero Typography Pattern

The dominant visual element on primary screens. Used for week numbers and screen-level anchors.

• Font: Display serif (Fraunces or equivalent), 58pt, font-black weight
• Purpose: Answers "Where am I?" at the largest text size on screen
• Usage: Today screen ("Week 8 of 15"), Learn screen ("Week 8 of 15")
• Squint Test: Must remain identifiable as the dominant element when the screen blurs (WWDC25 Field Guide, Part 4)

Section Header Pattern

Consistent labeling for content sections across all screens.

• Font: 11pt, bold, uppercase, letter-spacing tracked (0.05em+), muted foreground color
• Purpose: Provides structural wayfinding within a screen
• Usage: "THIS WEEK", "TODAY'S SESSIONS", "LESSON", "SUBMISSION", "FEEDBACK"
• Spacing: 2.5pt margin below header, 16pt margin above (except first section)

Card Pattern

The standard content container used across all screens.

• Background: bg-card (warm card surface)
• Border: rounded-xl corners, border with 60% opacity (border-border/60)
• Internal padding: 16pt horizontal, 12-16pt vertical
• Variants:
  • Standard card: Default treatment for status indicators, info blocks, session cards
  • Grouped card: Multiple rows within one card, separated by subtle dividers (1px, border-border/40). Used for video lists, week rows in "All Weeks", session lists
  • Gradient CTA card: For primary actions (see below)
  • Sacred text card: Warm-tinted background for Quranic text (see Learn screen spec)

Gradient CTA Pattern

The highest-prominence interactive element. Used for the single most important action on a screen.

• Background: Linear gradient with accent colors, subtle warm border
• Shadow: Soft shadow for elevation
• Content structure: Small uppercase category label, display serif heading, body description, prominent CTA button
• Usage: Today's Primary Action Card, Learn's Submission CTA ("Record Your Recitation")
• Rule: Maximum one gradient CTA per screen. If two actions compete for prominence, one must use the standard card pattern.

Status Badge Pattern

Colored pill labels for quick status scanning.

• Shape: Rounded pill (full border-radius), small padding (4pt horizontal, 2pt vertical)
• Font: 10-11pt, semibold, uppercase
• Colors by state:
  • Complete: Green background, dark green text
  • In Progress: Blue/primary background, white text
  • Not Started: Gray/muted background, muted text
  • Feedback Ready: Amber background, dark amber text
  • Behind: Amber background with alert indicator
• Usage: Week status in "All Weeks" view, submission status, session type badges

Progress Ring Pattern

Circular SVG indicator for completion percentage.

• Size: 56pt diameter (hero placement), 40pt (compact placement)
• Stroke: 3-4pt stroke width, primary accent color for filled portion, muted for background track
• Center: Percentage or fraction text (e.g., "53%" or "2/3")
• Usage: Today hero header (semester completion), Learn hero header (lesson completion)

Touch Interaction Pattern

Consistent interaction feedback for all tappable elements.

• Active state: scale(0.97) on press, with touch-manipulation CSS
• Transition: 150ms ease-out for scale animation
• Tap targets: Minimum 44pt per Apple HIG (WWDC25 Field Guide, Part 2)
• Usage: All cards, buttons, list rows, tab bar items

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 (Record Submission on Today > CTA button in Submission section > tap Record) 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: "This Week" view updates to show the new week's content. In "All Weeks" view, journey progress indicator advances by one step. Previous week row 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 progress indicator (in "All Weeks" view): No change until lesson is explicitly marked complete, at which point the week's status dot updates.

Submits a recording:

• Learn tab: Submission section shows "Under Review" compact card with amber icon and 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 section 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 section. 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: Feedback section populates with coach's audio and notes. Hero header shows "Feedback Ready" accent indicator.
• 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: "This Week" view shows a single orientation card: "Your first lesson unlocks on [date]. In the meantime, watch the orientation video to learn how the program works." Orientation video embedded. "All Weeks" view shows journey progress indicator with all 15 weeks as upcoming.

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: "This Week" view shows Week 1 content in workspace layout. Lesson section shows video list with thumbnails. Submission section: Quranic text card displayed, CTA reads "Watch the lesson first, then record your submission" (disabled until lesson complete). Feedback section: "Submit your recording to receive feedback from your Quran Coach."

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 of "This Week" view with distinct styling (gold/amber border, graduation cap icon). In "All Weeks" view, journey progress indicator 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 progress indicator 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 via "All Weeks" view.

4.8 Onboarding Flow

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 progress indicator in Learn's "All Weeks" view.

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 progress indicator: In "All Weeks" view, the EOC is the final node on the progress track, appearing after Week 15. When the student is eligible, this node is highlighted.

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 progress indicator: 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 sections
   • Schedule tab: Includes appointment booking alongside live sessions (new "Appointments" section)
   • Profile tab: Unchanged

   Scope note: Year 2 interaction design (appointment slot display, booking flow, elective selection, 1-on-1 session management) is deferred to a separate Year 2 design phase. This architecture covers the Year 1-to-Year 2 transition experience only. Year 2 tasks (5A.1, 5A.2, 5A.3 from the Capability Map) are not counted as covered by this specification.

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 section)
• 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); dense days with 7+ sessions trigger type-based grouping with collapsed sections; recordings view shows max 7 rows before "Show all" disclosure. PASS.

C2 -- The Squint Test: Today: week header is the dominant element. Learn: week number hero header (58pt) is the dominant element, progress ring is the second, video list card is the third. Schedule: session card stack with colored type badges is the visual structure; "Live Now" green Join button is the single most identifiable element when a session is live; on normal days, the time column and type badges create the rhythm. Profile: profile card is dominant. PASS (each screen has one clear anchor -- Schedule's anchor is the session cards themselves, optimized for scanning rather than emotional anchoring).

C3 -- Week-Grouped History: Week 6 submission and Week 6 feedback are in the same week's content, in vertically adjacent sections (Submission section above, Feedback section below). Visible in the same scroll without tapping. 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).

End of Phase 4 Architecture Specification