Architecture Prompt — v6

QuranFlow Architecture Design Process — v6

What This Document Is

This is a guided design process for producing a single, implementation-ready architecture specification for the QuranFlow iOS app redesign. It walks through analysis stages that build on each other, culminating in one deep architecture proposal.

This is NOT an exploration of multiple concepts. We have already explored three architecture proposals (Weekly Rhythm, Dashboard Command Center, Guided Journey), built a mockup of the first, and reviewed it. This process takes everything we've learned and produces the definitive architecture.

Don't skip stages. Each one produces insights the next stage needs.

Execution Instructions

This process is designed to be executed as 5 sequential agents in Claude Code. Each phase is a separate agent with its own context window, maximizing depth and quality.

Directory Structure

/Users/kamran/GitHub/QuranFlow-App-Usability/
├── reviews/                              ← Source documents (READ ONLY)
│   ├── QuranFlow-User-Capability-Map.md
│   ├── PM-Discussion-Dec2-Lejla.md
│   ├── QuranFlow App - Usability & Design Audit - Nov 27.md
│   ├── QuranFlow-Architecture-Proposals.md
│   ├── DESIGN-REVIEW-of-Exploration-A.md
│   └── reference-docs/
│       ├── App-Redesign-Field-Guide-WWDC25.md
│       ├── Quran Flow Program Description (3).md
│       └── Quran Flow - program overview.md
├── reviews/prompts/
│   └── QuranFlow-Architecture-Design-Prompt-v6.md  ← This file
└── reviews/v6-output/                    ← Output directory (WRITE HERE)
    ├── phase-1-problem-brief.md          ← Agent 1 writes here
    ├── phase-2-design-principles.md      ← Agent 2 writes here
    ├── phase-3-learnings.md              ← Agent 3 writes here
    ├── phase-4-architecture.md           ← Agent 4 writes here
    └── phase-5-validation.md             ← Agent 5 writes here

Agent Execution Sequence

Each agent should be run sequentially using the Task tool with subagent_type: "general-purpose".

Agent 1 — Phase 1: Problem Synthesis

• Reads: Source files #1-5 (capability map, PM discussion, audit, program descriptions)
• Writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-1-problem-brief.md
• Instructions: Copy the Phase 1 section from this document into the agent prompt. Include the full Design Philosophy section and Organizing Principle section for context. Tell the agent which files to read (absolute paths) and where to write.

Agent 2 — Phase 2: Design Principles

• Reads: WWDC25 Field Guide + Phase 1 output
• Writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-2-design-principles.md
• Instructions: Copy the Phase 2 section. Tell it to read the Field Guide and the Phase 1 output for context.

Agent 3 — Phase 3: Learnings from Previous Attempt

• Reads: Architecture Proposals, Design Review + Phase 1 and 2 outputs
• Writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-3-learnings.md
• Instructions: Copy the Phase 3 section. Tell it to read the Proposals doc, Design Review, and both previous phase outputs.

Agent 4 — Phase 4: Architecture Specification

• Reads: ALL source files + ALL previous phase outputs
• Writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-4-architecture.md
• Instructions: This is the most important agent. Copy the FULL Phase 4 section (all 9 subsections). Include the Design Philosophy and Organizing Principle sections. Tell it to read all three previous phase outputs first, then design the architecture. Use model: "opus" for maximum quality.

Agent 5 — Phase 5: Validation

• Reads: Phase 4 output + User Capability Map + WWDC25 Field Guide
• Writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-5-validation.md
• Instructions: Copy the Phase 5 section. Tell it to validate the Phase 4 architecture against all criteria.

After All Agents Complete

Assemble the final document from the 5 phase outputs:

• Combine into /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/QuranFlow-Architecture-Specification-v2.md
• Add executive summary
• Follow the Final Deliverable Structure section at the bottom of this document

Quality Notes

• Model: Use opus for Agents 1, 3, and 4 (analysis and architecture). Agents 2 and 5 can use sonnet.
• Review between phases: After each agent completes, briefly review its output before launching the next. Course-correct if needed.
• Context isolation: Each agent starts fresh. It cannot see the conversation history. Everything it needs must be in its prompt or in files it reads.
• File paths must be absolute. Always use the full path starting with /Users/kamran/GitHub/QuranFlow-App-Usability/.

Your Role

You are an iOS product designer with deep expertise in information architecture, learning apps, and accessibility. You are designing a production architecture — not a concept exploration. Your output will be used directly to build high-fidelity mockups.

The Organizing Principle (Locked)

Weekly Rhythm: "The app follows my weekly learning cycle."

This principle was selected through systematic evaluation of 6 alternatives. It directly addresses the core disorientation problem and matches the program's actual structure (15-week semesters, weekly submission cycles). You are not re-evaluating this choice. You are designing the best possible architecture around it.

However, you should incorporate the strongest ideas from the other two proposals (Dashboard Command Center and Guided Journey) where they strengthen the Weekly Rhythm architecture.

What the Output Must Be

A single architecture specification document with enough detail that a designer/developer could build mockups directly from it. This means:

• Detailed written descriptions of every screen (content, hierarchy, behaviors, states)
• No ASCII wireframes — describe what the user sees in prose, with enough specificity to implement
• State transitions — what changes when events happen (feedback arrives, new week unlocks, student falls behind)
• Edge cases and empty states — what Week 1 looks like, what "caught up" looks like, what "behind" looks like
• Full student lifecycle — from pre-semester through graduation, not just the weekly cycle
• Architecture only — no visual design direction (colors, fonts, spacing). That's a separate workstream.

Design Philosophy

Before any analysis, establish the frame.

What Success Looks Like

A successful QuranFlow architecture means:

• Week 1 student: Opens app for first time → immediately understands what to do and when the semester starts
• Week 8 student: Opens app → sees "Week 8 of 15" and their current status without scrolling
• Catch-up student: Missed a week → can quickly find what they missed and what's due
• Confused student: Something's wrong → finds help in ≤2 taps
• Pre-semester student: Enrolled but semester hasn't started → sees countdown, orientation content, and their assigned coach
• Graduating student: Completed Week 15 → understands EOC assessment, sees results, knows what's next

The ultimate test: No one should ever need to email asking "when does semester start?" or "what week am I on?" The app answers this instantly.

The Core Trade-off

QuranFlow serves two competing user needs:

The Weekly Rhythm principle leans toward guidance, but the architecture must accommodate flexibility. Be explicit about where you land on this spectrum for each screen.

Key Architectural Decisions

These are the choices that define the architecture. Take a clear stance on each and explain your reasoning:

1. What earns a spot on the tab bar? The skeleton. Wrong choices here can't be fixed with good screens.
2. What dominates the home screen? The first impression. Does the user see their current week? A task list? Status cards?
3. Are submissions and feedback unified or separate? The mockup kept Submit as a standalone tab. The original spec unified it into Learn. What's right?
4. Where does the schedule live? Currently buried. How prominent should it be?
5. How does the app handle "you're behind"? Guilt-inducing? Encouraging? Hidden?
6. Where does feedback history live? Its own tab? Inside the learn flow? A progress section?
7. How does onboarding work? What happens the first time someone opens the app?

How We Validate

An architecture works if it passes these tests:

• Orientation test: New user can state what week it is and what they should do within 10 seconds
• First task test: New user can complete first submission without external help
• Return test: Returning user sees current status without scrolling
• Recovery test: Confused user finds support in ≤2 taps
• Tab bar test: Every tab is a destination, no actions
• 3 Questions test: Home screen answers Where am I? What can I do? Where can I go?
• Lifecycle test: Architecture handles pre-semester, active semester, and end-of-semester states
• Behind test: Student 2 weeks behind can find what they need without shame

Reference Materials

Read these files in order. Each one provides a different lens on the problem.

Base path: /Users/kamran/GitHub/QuranFlow-App-Usability

Phase output files (written during execution, read by subsequent phases):

Phase 1: Synthesize the Problem

Goal: Produce a clear, fresh problem statement and requirements summary by reading the source documents.

Agent reads: Files #1-5 from the reference materials table Agent writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-1-problem-brief.md

Tasks

1. Read files #1-5 from the reference materials table
2. Synthesize into a problem brief in your own words

Output: Problem Brief

Write a concise brief covering:

The Disorientation Problem (2-3 sentences)

• What's the core failure?
• How does it manifest?

The Weekly Rhythm (bullet list)

• What happens each week?
• What's the critical path a student must complete?

Task Inventory Organize all [Core] and [Supporting] tasks from the Capability Map into a table:

Hidden Features Table

Student Lifecycle Phases Identify and briefly describe each phase a student goes through, from enrollment to graduation/Year 2 transition.

Phase 2: Design Principles & Quality Bar

Goal: Internalize the WWDC25 Field Guide principles and establish the quality bar this architecture must meet.

Agent reads: File #6 (WWDC25 Field Guide) + Phase 1 output (P1) Agent writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-2-design-principles.md

Tasks

1. Read file #6 (WWDC25 Field Guide)
2. Read the Phase 1 problem brief for context
3. Apply the diagnostic tests to QuranFlow's current problems (not the current app — you're diagnosing the problems the architecture must solve)
4. Establish specific, testable quality criteria

Output: Design Principles Summary

The 3 Questions Test (What the Architecture Must Answer)

Tab Worthiness Criteria Establish the rules you'll use to evaluate tab bar candidates.

Content Principles Which WWDC25 principles are most important for QuranFlow and why?

Phase 3: Learn from Previous Attempt

Goal: Extract concrete, actionable learnings from the existing Proposal A and its mockup implementation.

Agent reads: Files #7-8 (Architecture Proposals, Design Review) + Phase 1 and 2 outputs (P1, P2) Agent writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-3-learnings.md

Tasks

1. Read Phase 1 and Phase 2 outputs for context
2. Read file #7 (Architecture Proposals) — focus on Proposal A but note valuable elements from B and C
3. Read file #8 (Design Review of Exploration A)
4. Synthesize what worked, what didn't, and what questions emerged

Output: Learnings Report

What Worked in Proposal A (Preserve These) List the specific design decisions and patterns that proved effective in the mockup.

What Didn't Work (Fix These) List the specific gaps, misalignments, and weaknesses the design review identified.

Elements from Proposals B and C Worth Incorporating What ideas from the rejected proposals should be folded into the architecture?

Open Design Questions List the unresolved questions that emerged from the mockup experience. These are the decisions Phase 4 must make.

Coverage Gaps Note which areas of the User Capability Map are at 0% or low coverage and need to be designed in Phase 4.

Phase 4: Design the Architecture

Goal: Produce the definitive architecture specification for QuranFlow.

Principle: Weekly Rhythm — "The app follows my weekly learning cycle."

Scope: The complete student lifecycle, from pre-semester through graduation.

Agent reads: ALL source files (#1-8) + ALL previous phase outputs (P1, P2, P3) Agent writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-4-architecture.md

IMPORTANT: This is the most critical phase. The agent should read the three previous phase outputs FIRST to absorb the problem synthesis, design principles, and learnings. Then read whichever source files it needs to reference directly. The architecture must resolve all open questions identified in Phase 3.

4.1 Concept & Philosophy (1 page)

Articulate the architecture's organizing principle in plain language:

• What's the mental model?
• Why does this fit QuranFlow's users (busy adults, many older, don't read instructions)?
• How does it solve the disorientation problem?
• Where does it sit on the Guidance ↔ Flexibility spectrum?
• How does it incorporate the strongest ideas from the Dashboard and Guided Journey approaches?

4.2 Navigation Structure

Tab Bar Design:

For each tab:

• What screens/sections live inside it
• The hierarchy (at least two levels deep)
• Why this grouping makes sense given the Weekly Rhythm principle
• What it looks like when empty (pre-semester or no data)

Justify your tab bar against the Tab Worthiness Test.

4.3 Screen Specifications

For EACH screen in the app, provide:

[Screen Name]

Purpose: One sentence — what is this screen for?

Content (top to bottom): Describe what the user sees in the order they'd scan it. Be specific about:

• Headers and labels (exact text where possible)
• Cards, sections, and their content
• Actions available (buttons, taps, swipes)
• Information hierarchy (what's most prominent, what's secondary)

States:

Behaviors:

• What happens when the user taps each interactive element
• What refreshes automatically vs. requires pull-to-refresh
• What notifications surface on this screen

Connection to other screens:

• What screens can the user navigate to from here?
• What screens navigate TO this one?

4.4 Critical User Flows

Walk through these scenarios step-by-step. For each flow:

• List every tap/action
• Count the total taps for the critical path
• Explain why this flow makes sense given the Weekly Rhythm principle

Flow 1: First-time student opens the app (onboarding)

• From app launch to understanding what to do
• Include font selection, coach introduction, semester orientation

Flow 2: Watch this week's lesson

• From wherever the student naturally lands
• Through video playback
• To lesson completion

Flow 3: Submit weekly recording

• From start to confirmed submission
• Include the recording interface, review, confirmation
• Note the submission limit display

Flow 4: Check and respond to feedback

• From notification or in-app indicator
• Through feedback review
• To asking a follow-up question

Flow 5: Find and join a live session

• From any starting point
• Through finding the right session
• To joining the Zoom call
• Note timezone handling

Flow 6: Catch up after missing a week

• Student missed Week 7, now it's Week 8
• How do they find what they missed?
• How do they get back on track?

Flow 7: Pre-semester experience

• Student enrolled, semester hasn't started
• What do they see? What can they do?
• How does the app handle the countdown?

Flow 8: End-of-semester assessment and graduation

• Week 15: EOC assessment flow
• Results delivery
• Graduation and transition to next level (or Year 2)

4.5 Surfacing Strategy

Show how EVERY currently-hidden feature becomes findable:

4.6 State Management

Describe how the app's state changes in response to events:

Temporal Events:

• New week unlocks (Saturday)
• Submission deadline approaches
• Live session about to start
• Semester about to end

User Actions:

• Completes a lesson video
• Submits a recording
• Listens to feedback
• Asks a follow-up question
• RSVPs for a session

External Events:

• Feedback arrives from coach
• Schedule changes
• New announcement posted
• Notification received

For each event, describe: what changes on which screens, what notifications appear, what state indicators update.

4.7 Edge Cases & Empty States

Design for these specific scenarios:

Pre-Semester Student:

• Enrolled but no content yet
• What every screen looks like
• What actions are available

Week 1 Student (First Day):

• Everything is new
• First lesson just unlocked
• No submission history, no feedback

Caught-Up Student:

• All tasks for the week done
• Waiting for feedback
• What does the app show?

Behind Student:

• Missed 1-2 weeks of submissions
• How does the app communicate this?
• How does it encourage without shaming?

End-of-Semester Student:

• Week 15, final assessment
• What's different from a regular week?

Year 2 Transition:

• Level 4 graduate entering Year 2
• How does the architecture accommodate the appointment model (no weekly submissions)?

4.8 Onboarding Flow

Design the complete first-time user experience:

What triggers it: First app launch after enrollment

What it must accomplish:

1. Orient the student (what is QuranFlow, how does it work)
2. Introduce their Quran Coach
3. Set up mushaf font preference (default should be correct, but give option)
4. Show semester timeline and when things start
5. Explain the weekly cycle (briefly)
6. Set notification preferences

Constraints:

• Must be completable in under 2 minutes
• Must not feel like a tutorial — more like a welcome
• Must be skippable (but with graceful defaults if skipped)
• Information presented here must also be findable later

4.9 End-of-Semester & Graduation

Design the experience for the final weeks:

EOC Assessment:

• How is it presented differently from regular weekly submissions?
• What's the flow?

Results:

• How are results communicated?
• What does "passing" look like vs. "not passing"?

Graduation:

• Celebration/acknowledgment
• Transition to next level
• For Level 4: Year 2 information and enrollment path

Phase 5: Validate the Architecture

Goal: Verify the architecture against all quality criteria before finalizing.

Agent reads: Phase 4 output (P4) + File #1 (User Capability Map) + File #6 (WWDC25 Field Guide) Agent writes: /Users/kamran/GitHub/QuranFlow-App-Usability/reviews/v6-output/phase-5-validation.md

Tasks

1. Read the Phase 4 architecture specification thoroughly
2. Read the User Capability Map for the [Core] task checklist
3. Read the WWDC25 Field Guide for the validation tests
4. Run the validation checklist
5. Verify [Core] task coverage
6. Check P0 issue resolution
7. Audit tap counts

Output: Validation Report

Validation Checklist

[Core] Task Coverage

P0 Issues Resolution

Tap Count Audit

Final Deliverable Structure

The complete output should be organized as:

# QuranFlow Architecture Specification v2

## Executive Summary
[1 page: the architecture at a glance — tab bar, organizing principle, how it solves disorientation]

## Problem Brief
[Output from Phase 1]

## Design Principles
[Output from Phase 2]

## Learnings from Previous Attempt
[Output from Phase 3]

## Architecture Specification

### Concept & Philosophy
[Section 4.1]

### Navigation Structure
[Section 4.2]

### Screen Specifications
[Section 4.3 — this will be the longest section]

### Critical User Flows
[Section 4.4]

### Surfacing Strategy
[Section 4.5]

### State Management
[Section 4.6]

### Edge Cases & Empty States
[Section 4.7]

### Onboarding
[Section 4.8]

### End-of-Semester & Graduation
[Section 4.9]

## Validation Report
[Output from Phase 5]

## Appendix: Source Material Key Extracts
[Brief reference to key data points from each source document]

Process Checklist

• Phase 1 complete: Problem brief written from fresh reading of source documents
• Phase 2 complete: Design principles established and quality bar set
• Phase 3 complete: Learnings from Proposal A and mockup extracted
• Phase 4 complete: Full architecture specification written
• Phase 5 complete: Validation passed
• All [Core] tasks from capability map have a home
• All hidden features have a new, findable location
• All P0 issues addressed
• Pre-semester, active semester, and end-of-semester states designed
• Onboarding flow designed
• Edge cases and empty states covered
• Every screen has state descriptions
• Trade-offs honestly articulated