Admin Spec — Index & Foundations

QuranFlow Admin Backend Redesign -- Specification Index

1. Purpose and Scope

This spec covers the complete redesign of the QuranFlow admin backend navigation and screen structure, based on the Enhanced Candidate A recommendation from Workstream 1 (navigation redesign) converged with Workstream 2 (billing integration). The spec is mockup-ready -- detailed enough for a designer to create wireframes without asking clarifying questions.

Covers: Admin backend navigation, all screen specifications, billing integration, role-based access

Does not cover: Student-facing iOS app, checkout frontend, Stripe API implementation details, mobile responsive design

2. Design Foundations

The Enhanced Candidate A architecture was selected through a structured multi-candidate evaluation in Workstream 1, scoring 30/35 (highest of 3 candidates). It was then augmented with the strongest ideas from Candidates B and C.

Core (from Candidate A -- scored 30/35, highest of 3 candidates)

• 8+1 domain sidebar matching the admin's mental model: Student Management, Semester Management, Content, Scheduling, Teacher Management, Billing & Payments, Reporting, Admin & System + Dashboard
• Rich multi-tab entity pages for Students (6 tabs), Semesters (4 tabs), TAs (4 tabs)
• Billing as first-class dual-level domain -- aggregate domain-level views (Payment Overview, Payment Plans, Coupons, Family Plans, Scholarships & Deferments) plus entity-page-level tabs (Student Detail > Payments tab, Semester Hub > Close Workflow billing step)
• Role-based sidebar filtering for TAs (see only their students, schedule, submissions) and view-only admins (full visibility, no write actions)

Incorporated from Candidate B (dashboard depth)

• Enhanced operational dashboard with configurable alert tiles (failed payments, pending submissions, TA response times)
• Issue Queue for student-to-admin communication, surfaced as a dedicated screen under Admin & System
• Phase-aware dashboard tiles with semester lifecycle prompts (Setup / Active / Close) and progress indicators

Incorporated from Candidate C (search + content integration)

• Global search bar resolving to entity pages from any screen -- type a student name, TA name, or semester label and jump directly to the relevant detail page
• Deeper content status integration on Semester Hub -- inline previews of content readiness, deep links to Content screens with the semester pre-filtered, and a "return to checklist" affordance so the admin never loses context during semester setup

Evidence base

• Interview: The admin proposed a domain-based structure herself (Q4: "I would group things by what they're about -- students, content, scheduling")
• WS1.5 scoring: Enhanced Candidate A scored highest on mental model match (5/5), billing accommodation (5/5), and secondary user learnability (5/5)
• Sensitivity analysis: Robust under all tested weighting scenarios -- remained the top candidate even when individual criteria weights were doubled or halved

3. Master Navigation Tree

Dashboard (NEW -- operational overview with alerts and phase prompts)

Student Management
  Students                                    <- from People
    [Student Detail Page] (NEW -- rich multi-tab profile)
      [Tab: Profile]
      [Tab: Submissions]
      [Tab: Payments] (NEW)
      [Tab: Appointments]
      [Tab: Semester History] (NEW)
      [Tab: Actions]
  Submissions (Assessments)                   <- from Program
  Promoted Students                           <- from Reports
  Failed Sign Ups                             <- from Reports

Semester Management
  Semesters                                   <- from top-level
    [Semester Hub Page] (NEW -- rich multi-tab semester view)
      [Tab: Overview]
      [Tab: Setup Checklist] (NEW)
      [Tab: Enrollment] (NEW)
      [Tab: Close Workflow] (NEW)
  Welcome Package                             <- from Settings
  Email Management                            <- from Settings
  Tags                                        <- from Settings
  Operations (bulk actions)                   <- from Settings

Content
  Video Lessons                               <- from Program
  Resources                                   <- from Program
  Recordings                                  <- from Program
  Tutorials                                   <- from Program
  MCQ Questions                               <- from Program
  Quizzes                                     <- from Program

Scheduling
  Calendar View (NEW)
  Live Sessions                               <- from Program
  Upcoming Appointments                       <- from Appointments
  TA Schedules                                <- from Appointments
  Holidays                                    <- from Appointments (merged with Live Session Holidays)

Teacher Management
  Teaching Assistants                         <- from People
    [TA Detail Page] (NEW -- rich multi-tab TA view)
      [Tab: Profile]
      [Tab: Schedule]
      [Tab: Students & Groups] (NEW)
      [Tab: Performance] (NEW)
  Teacher Assignment Criteria                 <- from Settings
  TA Reports                                  <- from Reports
  Student Groups (NEW -- surfaced to nav)

Billing & Payments (NEW section)
  Payment Overview (NEW)
  Payments (transaction history)              <- from Reports
  Payment Plans                               <- from Settings
  Coupons                                     <- from Settings
  Family Plans (NEW)
  Scholarships & Deferments (NEW)

Reporting
  Student Report                              <- from Reports
  Referrals                                   <- from Reports
  Specific Reports                            <- from Reports
  Student Composition (NEW)
  Logs                                        <- from Settings

Admin & System
  Admins                                      <- from People
  Settings (General)                          <- from Settings
  Notifications                               <- from Settings
  Support Links                               <- from Students Management
  Issue Queue (NEW -- from Candidate B)

Screen counts: 9 domains, 35 existing screens (all placed), 13 new screens/views, 1 dissolved screen (Students Management grab-bag).

4. Screen Placement Map

Complete mapping of all 35 current screens to their new locations in the redesigned navigation.

Dissolved Screen #14 Redistribution

The current "Students Management" screen under People is a grab-bag of unrelated tools. Its contents are redistributed as follows:

• Level 0 promotion --> Semester Management > Operations (absorbed into bulk actions)
• Live Session Holidays --> Scheduling > Holidays (merged with Appointments > Holidays into a single unified holidays screen)
• Support Links --> Admin & System > Support Links (standalone screen)

5. New Screens Inventory

6. Cross-Domain Workflow Index

These are the 6 core admin workflows mapped to their screen sequences under the new navigation structure. Each workflow shows the specific screens visited and how cross-domain navigation flows work.

WF1: Semester Setup (2-3x/year, Critical)

Current state: 19+ screens, 50-80 clicks, 3 external tools (Google Sheets, Vimeo, manual checklists) Enhanced A: 8-10 screens, 20-35 clicks, 1 external tool (Vimeo for video URLs)

Screen sequence:

1. Dashboard -- phase prompt shows "Semester Setup" with progress bar
2. Semester Management > Semesters -- create new semester or clone from previous
3. Semester Hub > Setup Checklist tab -- guided checklist of all setup tasks with completion status
4. Content > Video Lessons -- deep link from checklist, semester pre-filtered. Upload/assign video lessons.
5. Click "return to checklist" affordance --> Semester Hub > Setup Checklist tab
6. Content > Resources -- deep link from checklist, semester pre-filtered. Upload supplementary materials.
7. Click "return to checklist" --> Semester Hub > Setup Checklist tab
8. Semester Hub > Enrollment tab -- review enrollment numbers, assign students to levels
9. Teacher Management > Teaching Assistants -- assign TAs to groups/levels for this semester
10. Semester Management > Welcome Package -- configure welcome email content
11. Semester Management > Email Management -- schedule enrollment confirmation emails

WF2: Student Support (frequent, ad-hoc)

Current state: 5-7 screens, 15-25 clicks, 3 external tools (Stripe dashboard, Google Sheets, WhatsApp) Enhanced A: 1-2 screens, 4-7 clicks, 0 external tools

Screen sequence:

1. Global Search -- type student name from any screen
2. Student Management > Students > [Student Detail Page] -- land directly on the student's profile
3. All information available via tabs without leaving the page:
   • Profile tab: contact info, enrollment status, level, TA assignment
   • Submissions tab: all audio submissions with grades and feedback
   • Payments tab: Stripe subscription status, payment history, failed payments (inline, no Stripe dashboard needed)
   • Appointments tab: upcoming and past 1:1 sessions
   • Semester History tab: progression across semesters, promotion/retention record

WF3: Semester Close (2-3x/year, Critical)

Current state: 8+ screens, 40-70 clicks, 3 external tools (Google Sheets, Stripe dashboard, manual tracking) Enhanced A: 4-6 screens, 15-25 clicks, 0 external tools

Screen sequence:

1. Semester Management > Semesters > [Semester Hub > Close Workflow tab] -- gated multi-step process
2. Step 1: Review EOC -- view end-of-course assessment results, identify students above/below 3.5 threshold
3. Step 2: Confirm Promotions -- approve promotion list, handle edge cases (manual overrides with reason)
4. Step 3: Bulk Payment Setup -- gated behind Step 2 completion. Create/update Stripe subscriptions for promoted students. Handle plan changes for level transitions.
5. Step 4: Handle Leavers -- linked deactivation: deactivate student account + cancel Stripe subscription in one action. Record leave reason.
6. Step 5: Verify -- summary view confirming all close tasks completed. Show any unresolved items.

WF4: Daily Monitoring (every session)

Current state: 4-5 screens, 12-18 clicks, 3 external tools (Stripe dashboard, Google Sheets, email) Enhanced A: 1-3 screens, 3-8 clicks, 0 external tools

Screen sequence:

Path A -- Failed payments:

1. Dashboard -- alert tile shows "3 Failed Payments"
2. Click tile --> Billing & Payments > Payment Overview -- filtered to failed payments
3. Click student name --> Student Management > Students > [Student Detail Page > Payments tab] -- see full payment history, retry or contact

Path B -- TA performance:

1. Dashboard -- alert tile shows "2 TAs: Response Time > 48h"
2. Click tile --> Teacher Management > Teaching Assistants -- filtered to flagged TAs
3. Click TA name --> [TA Detail Page > Performance tab] -- see response time trends, submission backlog

WF5: Scheduling / Appointments (regular)

Current state: 4-6 screens, 12-20 clicks, 2 external tools (Google Sheets, email) Enhanced A: 1-2 screens, 5-8 clicks, 0 external tools

Screen sequence:

Path A -- Calendar management:

1. Scheduling > Calendar View -- unified view of live sessions and 1:1 appointments
2. Filter by TA, gender, or level
3. Click to create or edit a session/appointment directly on the calendar

Path B -- TA availability:

1. Scheduling > TA Schedules -- view all TA availability slots
2. Edit availability directly in the schedule grid

WF6: TA Onboarding (per-semester)

Current state: 6-8 screens, 20-35 clicks, 1 external tool (Google Sheets) Enhanced A: 2-3 screens, 8-12 clicks, 0 external tools

Screen sequence:

1. Teacher Management > Teaching Assistants -- click "Add TA" to create new TA record
2. [TA Detail Page > Profile tab] -- enter personal info, credentials, set role permissions
3. [TA Detail Page > Schedule tab] -- set weekly availability slots
4. [TA Detail Page > Students & Groups tab] -- assign students and/or groups to this TA

7. Open Questions (with Best-Guess Defaults)

These questions remain unanswered from stakeholder interviews and workstream analysis. Each has a documented assumption that the spec uses as a default. These assumptions should be validated before development begins but are sufficient for mockup creation.

8. Glossary

9. Document Index

10. Workflow Improvement Summary

Quantified impact of the Enhanced Candidate A redesign across all 6 core admin workflows, based on WS1.5 analysis.

External tool reduction: 15 dependencies --> 1 (Vimeo for video URLs). Google Sheets eliminated entirely. Stripe dashboard eliminated entirely.