v2 Admin Spec — Index & Foundations

QuranFlow Admin Backend Redesign -- Specification Index (v2)

1. Purpose and Scope

This spec covers the complete redesign of the QuranFlow admin backend navigation and screen structure. v2 is the current spec — it extends the v1 Enhanced Candidate A architecture with the 11 decisions captured in the Apr 15, 2026 stakeholder review (see ../v2-review/FRAMEWORK-V2.md). The spec is mockup-ready: detailed enough for a designer to create wireframes without asking clarifying questions.

v1 is preserved in ../admin-spec/ as a reference baseline. v1 cross-references remain valid for any NOT-ADDRESSED section; v2 updates are documented inline with ADR references and HTML comments.

Covers: Admin backend navigation, all screen specifications, billing integration, role-based access, and the new Communication domain.

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. The Apr 15, 2026 stakeholder review extended the architecture with five Accepted Decision Records (ADR-001 through ADR-005) documented in ../v2-review/decisions/.

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

• 9+1 domain sidebar matching the admin's mental model: Student Management, Semester Management, Content, Scheduling, Teacher Management, Billing & Payments, Reporting, Admin & System, Communication (NEW v2) + Dashboard
• Rich multi-tab entity pages for Students (7 tabs, Admin Notes added in v2), Semesters (5 tabs — End Checklist and Onboarding Support added per ADR-001 / Framework v2 §3.2), 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 > End Checklist billing item).
• 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
• 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

v2 Deviations from v1 Core Patterns

• 9-domain IA vs. 8-domain v1 IA: Communication becomes the 9th domain, absorbing Email Management from Semester Management and Notifications from Admin & System, and adding four net-new screens. See ADR-003.
• Flat End Checklist (v2) vs. v1 gated end-of-semester workflow: Semester Hub's end-of-semester tab is a flat End Checklist structurally parallel to Setup Checklist. Automation moves to backend triggers. See ADR-001.
• Hybrid matrix Assignment Criteria vs. v1 rules engine: Per-TA matrix (capacity, level specialization, new-vs-returning) + small named rules + read-only preview. Timezone proximity rule dropped. See ADR-002.
• Registration Tracker dissolved: The proposed Registration Tracker screen is served by a "Registration" filter preset on Semester Hub > Enrollment plus co-located Level 0 bulk-promote. See ADR-005.
• No identity switching: "Send as TA" was rejected. Admins pre-draft; TAs send from their own accounts. See ADR-004.

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
• Apr 15, 2026 stakeholder review: All 11 decisions captured in FRAMEWORK-V2.md; 5 ADRs accepted

3. Master Navigation Tree

Dashboard (operational overview with alerts and phase prompts)

Student Management
  Students
    [Student Detail Page] (multi-tab profile)
      [Tab: Profile]
      [Tab: Submissions]
      [Tab: Payments]
      [Tab: Appointments]
      [Tab: Semester History]
      [Tab: Admin Notes] (NEW v2 — see 03-student-management.md §3.9.5)
      [Tab: Actions]
  Submissions (Assessments)
  Promoted Students
  Failed Sign Ups

Semester Management
  Semesters
    [Semester Hub Page] (multi-tab semester view)
      [Tab: Overview]
      [Tab: Setup Checklist]
      [Tab: Enrollment]                        <!-- v2: gains "Registration" filter preset + co-located Level 0 bulk-promote per ADR-005 -->
      [Tab: End Checklist] (RENAMED v2)        <!-- v2: replaces Close Workflow per ADR-001 -->
      [Tab: Onboarding Support] (NEW v2)       <!-- v2: see Framework v2 §3.2 -->
  Welcome Package
  Tags
  Operations (bulk actions)                    <!-- v2: 4 cards, down from 5 — Level 0 promote moved to Enrollment tab per ADR-005 -->

<!-- v2: Email Management removed from this domain per ADR-003 -->

Content
  Video Lessons
  Resources
  Recordings
  Tutorials
  MCQ Questions
  Quizzes

Scheduling
  Calendar View
  Live Sessions
  Upcoming Appointments
  TA Schedules
  Holidays
  One-to-One Appointment Usability (NEW v2)    <!-- v2: see Framework v2 §3.4 and 06-scheduling.md §7 -->

Teacher Management
  Teaching Assistants
    [TA Detail Page] (multi-tab TA view)
      [Tab: Profile]
      [Tab: Schedule]
      [Tab: Students & Groups]
      [Tab: Performance]
  Teacher Assignment Criteria                   <!-- v2: rewritten as hybrid matrix per ADR-002 -->
  TA Reports
  Student Groups

Billing & Payments
  Payment Overview
  Payments (transaction history)
  Payment Plans                                 <!-- v2: grouped presentation (Standard / Family / Scholarships / Discounts) per Decision #8 -->
  Coupons
  Family Plans
  Scholarships & Deferments

Reporting
  Student Report
  Referrals
  Specific Reports
  Student Composition
  Active Semester Enrollment      <!-- v2 NEW per Apr 22 -->
  Revenue Breakdown               <!-- v2 NEW per Apr 22 -->
  Installment→One-Time Conversion <!-- v2 nice-to-have stub per Apr 22 -->
  Notification/Email Impact       <!-- v2 nice-to-have stub per Apr 22 -->
  Logs

Admin & System
  Admins
  Settings (General)
  Support Links
  Issue Queue

<!-- v2: Notifications removed from this domain per ADR-003 — redirect preserved in 10-admin-system.md §4 for cross-ref traceability -->

Communication (NEW DOMAIN — v2)                 <!-- v2: 9th top-level domain per ADR-003 -->
  Automation Emails                              <!-- absorbed from Semester Management > Email Management, enhanced with Sequence View -->
  Blast Emails (NEW v2)
  Push Notifications                             <!-- absorbed from Admin & System > Notifications, enhanced with recipient filtering -->
  Announcement Board (NEW v2)
  Private Messages (NEW v2)
  Communication Logs (NEW v2)

Screen counts (v2): 9 top-level domains + Dashboard, 39 screens total.

• v1 total: 35 screens across 8+1 domains
• Removed from v1 IA: Email Management (-1, absorbed), Notifications (-1, absorbed); Dissolved grab-bag Students Management (already removed in v1 reshuffle)
• Added in v2: Communication domain (6 screens: Automation Emails counts as absorbed not new; Blast Emails, Announcement Board, Private Messages, Communication Logs = 4 net-new; Push Notifications absorbed). Net-new from Communication: +4.
• Added in v2 under Scheduling: One-to-One Appointment Usability = +1
• Added in v2 as tabs (not sidebar items, not counted as screens): Admin Notes tab, Onboarding Support tab
• Net change v1→v2: +4 screens (35 → 39). Math: 35 − 1 (Email Management moved) − 1 (Notifications moved) + 2 (same two relocated into Communication as absorbed screens) + 4 (Communication net-new) + 1 (One-to-One Usability) = 40. Subtract 1 for the net effect of Operations losing Level 0 promote card (no screen removed; only card count in §7) → 39 screens.

4. Screen Placement Map

Complete mapping of all v1 screens to their v2 locations, plus v2 additions. Where a screen is unchanged from v1, the "Change Type" column lists the v1 status (MOVED/ENHANCED/MERGED/REBUILT); v2 changes are flagged separately.

Total v2 screens: 39 (rows 1–13 and 15–40; #14 dissolved).

Dissolved Screen #14 Redistribution (v1)

The former Students Management screen's contents were redistributed in v1:

• Level 0 promotion → Semester Management > Operations (v1). v2 update: Level 0 promote is further co-located onto Semester Hub > Enrollment tab per ADR-005; Operations retains the action for now but the primary entry point is Enrollment.
• Live Session Holidays → Scheduling > Holidays
• Support Links → Admin & System > Support Links

5. New Screens Inventory

Preserved from v1 (unchanged entries)

Modified in v2

NEW in v2

6. Cross-Domain Workflow Index

These are the core admin workflows mapped to their screen sequences. Workflow improvement metrics measured against the v1 baseline; v2 deltas noted where applicable.

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

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

Screen sequence (v2):

1. Dashboard — phase prompt shows "Semester Setup" with progress bar
2. Semester Management > Semesters — create new semester or clone from previous (v2: auto-clone on create; manual Clone-from-Previous retained)
3. Semester Hub > Setup Checklist tab — guided checklist with completion status
4. Content > Video Lessons — deep link from checklist, semester pre-filtered
5. Click "return to checklist" → Semester Hub > Setup Checklist tab
6. Content > Resources — deep link, semester pre-filtered
7. Click "return to checklist" → Semester Hub > Setup Checklist tab
8. Semester Hub > Enrollment tab — review counts, assign students; v2 adds "Registration" filter preset + Level 0 bulk-promote here per ADR-005
9. Teacher Management > Teaching Assistants — assign TAs; v2: configure via hybrid matrix on Teacher Assignment Criteria per ADR-002
10. Semester Management > Welcome Package — configure welcome email content
11. Communication > Automation Emails (filtered to this semester via Setup Checklist deep link) — schedule enrollment confirmation and lifecycle emails
12. Semester Hub > Onboarding Support tab (NEW v2) — configure Telegram/WhatsApp links, welcome videos, countdown timer

WF2: Student Support (frequent, ad-hoc)

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

Screen sequence (v2):

1. Global Search — type student name from any screen
2. Student Management > Students > [Student Detail Page] — direct landing
3. All information available via tabs:
   • Profile tab: contact info, enrollment status, level, TA assignment
   • Submissions tab: audio submissions with grades and feedback (v2: reject-under-review action; bulk delete; per-week exception UI)
   • Payments tab: Stripe subscription status, payment history, failed payments (inline, no Stripe dashboard needed)
   • Appointments tab: upcoming and past 1:1 sessions (v2: semester filter)
   • Semester History tab: progression across semesters
   • Admin Notes tab (NEW v2): private admin-only notes
   • Actions tab: lifecycle actions including v2 "Enroll in Mastery Course"
4. If conversational follow-up needed → Communication > Private Messages (cross-domain deep link from Profile tab "Message" action)

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

Current state (v1 baseline): 8+ screens, 40-70 clicks, 3 external tools (Google Sheets, Stripe dashboard, manual tracking)

v2 target: flat 5-step End Checklist with automatic + semi-automatic steps plus optional custom items. Screen and click counts are TBD — see §10 for measurement caveat; expected similar to or better than v1 given automation.

Screen sequence (v2):

1. Dashboard — phase prompt shows "Semester End" with End Checklist progress (e.g., "3 of 5 steps complete").
2. Semester Management > Semesters > [Semester Hub > End Checklist tab] — flat list of the 5 canonical steps plus any custom items; each row shows status and an "Open" link to the step's detail view. See 04-semester-management.md §3.8 for the full definition.
3. Step-level work — each step either auto-completes via backend trigger or surfaces a manual fallback view when clicked:
   • Step 1 — All Submissions Reviewed auto-completes after the submission close date when no pending submissions remain; "Open" deep-links to Submissions (03-student §3) filtered to pending.
   • Step 2 — Pass/Fail auto-completes when all Level 1–4 students have final_status assigned (Mastery auto-passed at Step 5). "Open" deep-links to Students list (03-student §2) filtered to L1–4 without status; TAs can set status for their own students, admins for any.
   • Step 3 — Send Pass/Fail Emails auto-completes when every student has been sent the appropriate template (pass / fail-with-opt-in / mastery-elective). "Open" surfaces unsent students with a per-student "Send Now" fallback (templates live in 11-communication §2 Automation Emails).
   • Step 4 — Set Up Automatic Payments auto-completes when all passing L1–4 students have Stripe next-semester subscriptions created. "Open" deep-links to the End Checklist Payment Setup Queue (08-billing §2.9) with per-student manual setup buttons; Mastery and failing students are excluded by scope.
   • Step 5 — Semester Close fires fully automatically at midnight EST on semester.end_date; no admin action.
4. Cross-domain jumps as needed (driven by deep links from the steps above):
   • Students with pending submissions → 03-student §3 Submissions
   • L1–4 students awaiting Pass/Fail → 03-student §2 Students list
   • Unsent end-of-semester emails → 03-student §2 Students list (filtered by email status) via 11-communication
   • Passing students needing payment setup → 08-billing §2.9 End Checklist Payment Setup Queue
   • Student departures → Student Detail > Actions tab (linked deactivation preserved; leavers need no checklist step per STAKEHOLDER-ANSWERS-2026-04-21)
   • End-of-semester announcements → optionally 11-communication > Announcement Board

What's different from v1:

• No gated sequence — the 5 steps complete independently as their trigger conditions are met.
• W4 risk (payment setup before promotion finalized) is mitigated by scope rather than a UI gate: Step 4's scope is "L1–L4 passing students only", so it depends on Step 2 setting final_status before any student becomes eligible.
• Leavers are no longer a checklist item (they stay inactive; no admin action required).
• Mastery students are handled on a distinct track (auto-pass at Step 5, elective-prompt email in Step 3, self-enroll rather than auto payment setup).

WF4: Daily Monitoring (every session)

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

Screen sequence (v2):

Path A — Failed payments:

1. Dashboard — alert tile "3 Failed Payments"
2. Billing & Payments > Payment Overview — filtered to failed
3. Student Detail > Payments tab — full history, retry or contact

Path B — TA performance:

1. Dashboard — alert tile "2 TAs: Response Time > 48h"
2. Teacher Management > Teaching Assistants — filtered
3. TA Detail > Performance tab — response time trends, submission backlog (v2: avg-grade-given metric added)

Path C — Communication monitoring (NEW v2):

1. Dashboard — communication tiles: "Unread Private Messages (5)" or "Scheduled Blast: sending in 2h"
2. Click tile → Communication > Private Messages (filtered to Unread) or Communication > Blast Emails (scheduled queue)
3. Triage or reschedule as needed

Path D — App issues:

1. Dashboard — "App Issues" tile
2. Admin & System > Issue Queue — triage new issues
3. Optional follow-up → Communication > Private Messages (cross-domain via Issue Detail "Start Message" action — boundary preserved per ADR-003 §1.1)

WF5: Scheduling / Appointments (regular)

Current state: 4-6 screens, 12-20 clicks, 2 external tools v2: 1-2 screens, 5-8 clicks, 0 external tools (plus optional usability review via new One-to-One Usability screen)

Screen sequence (v2):

Path A — Calendar management:

1. Scheduling > Calendar View — unified view; v2 adds cancel-session, mark-inactive, reassign actions
2. Filter by TA, gender, or level
3. Click to create/edit directly

Path B — TA availability:

1. Scheduling > TA Schedules — date-bound slots (v2), bulk-add (v2)

Path C — Usability review (NEW v2):

1. Scheduling > One-to-One Appointment Usability — gender-split fill rates, underutilized slots
2. Drill down → Calendar View filtered to the underutilized slots
3. Remove-slot action directly from usability dashboard

WF6: TA Onboarding (per-semester)

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

Screen sequence (v2):

1. Teacher Management > Teaching Assistants — "Add TA"; v2 filter adds semester scope + per-week session/slot metrics
2. TA Detail > Profile tab — personal info, credentials, role permissions
3. TA Detail > Schedule tab — weekly availability (v2: date-bound slots + bulk-add)
4. TA Detail > Students & Groups tab — assign students/groups
5. Teacher Management > Teacher Assignment Criteria (v2: hybrid matrix) — set capacity, level specialization, new-vs-returning routing for the new TA; review weighted-distribution preview

WF7: Outbound Communication (NEW v2)

Current state: No dedicated workflow — blast email required mail merge outside the system; push notifications had no recipient filtering; 1:1 messaging happened in WhatsApp/email. v2: Dedicated Communication domain consolidates all outbound messaging.

Screen sequence — Blast Email (typical):

1. Dashboard — "Send Blast Email" quick action, or direct sidebar entry
2. Communication > Blast Emails > Compose view — recipient filter or manual selection; compose message
3. Preview modal → Test Send to self → Schedule or Send Now
4. Optional: Draft for TA — select TA; draft goes to TA's outbox; TA sends from own account (production flow per ADR-004)
5. Communication > Communication Logs — verify delivery status, retry failures if any

Screen sequence — Pre-drafted 1:1 Message (ADR-004 flow):

1. Admin composes on Communication > Private Messages > New Message or from Student Detail > Profile > "Message" or Teacher Detail > "Pre-draft for [TA]"
2. Select TA as sender identity → save draft
3. TA reviews in their own account (production-only queue), edits if desired, sends
4. Thread visible to student as originating from their TA; reply-to correctly routes to TA

7. Open Questions (with Best-Guess Defaults)

These questions remain unanswered from stakeholder interviews, workstream analysis, and the Apr 15 review. Each has a documented assumption sufficient for mockup creation; all require validation before production.

Preserved from v1

v2 additions — ADR-001 (End Checklist)

All ADR-001 questions (OQ-E1 through OQ-E5) are resolved 2026-04-21 per docs/v2-review/STAKEHOLDER-ANSWERS-2026-04-21.md §1. See that document for the canonical 5-step End Checklist definition (All Submissions Reviewed, Pass/Fail, Send Pass/Fail Emails, Set Up Automatic Payments, Semester Close). The resolved statuses below cite Lejla's verbatim definitions.

v2 additions — ADR-002 (Assignment Criteria)

All ADR-002 questions (OQ-A1, OQ-A2, OQ-A3) are resolved 2026-04-21 per docs/v2-review/STAKEHOLDER-ANSWERS-2026-04-21.md §2 (defaults #2, #3 + Q8) — deterministic distribution, manual fallback queue, Semester Hub entry point confirmed sufficient.

v2 additions — ADR-003 (Communication domain)

v2 additions — ADR-004 (Pre-drafted messaging)

v2 additions — ADR-005 (Registration Tracker integration)

v2 additions — Framework v2 TBDs (ambiguities carried forward from gap analyses)

8. Glossary

| Phase prompt | Dashboard element showing current semester phase (Setup / Active / End) with progress indicator. | | Entity page | Rich multi-tab detail page consolidating information about a student, semester, or TA into a single view. | | Domain | Top-level navigation section organized around an area of responsibility (e.g., Student Management, Communication). | | Family Plan | A billing arrangement where multiple students share a single Stripe subscription with a family discount. | | Scholarship | A reduced-rate billing arrangement with defined tiers (Full, 50%, 25%). | | Deferment | A temporary pause on billing via Stripe's pause_collection, typically one semester. | | Issue Queue | Centralized screen for student-reported issues and admin tickets. Remains in Admin & System per ADR-003 §1.1. Not a messaging channel — see Private Messages. | | Global search | Search bar resolving student/TA/semester names to entity pages from any screen. | | Alert tile | Dashboard component surfacing an operational metric (e.g., failed payments count) with click-through. | | Assignment Matrix (v2) | Per-TA configuration table on Teacher Assignment Criteria with columns for capacity, level specialization, new-vs-returning routing. Complemented by a small set of named rules (gender match, repeat-student auto-assign, distribution strategy) and a read-only preview of the weighted-distribution outcome. | | Rules Engine (v1 term — superseded) | See Assignment Matrix. v1 used a generic prioritized rule catalog; v2 replaces it with a per-TA matrix + named rules per ADR-002. | | Blast Email (v2) | Admin-initiated, multi-recipient, one-time email send. Distinct from Automation Emails (event-triggered, per-student). Supports recipient filtering, manual selection, scheduling, template library, and pre-draft for TA. | | Announcement Board (v2) | In-app one-way admin→users channel for non-urgent program updates. Replaces the community board concept. Supports audience filtering, expiry, optional read receipts. | | Private Message (v2) | Bidirectional thread-based message between a student and a teacher/admin. Replaces ad-hoc WhatsApp/email for student support. Admins can view all threads for moderation but cannot impersonate participants. | | Pre-drafted Message (v2) | A message composed by an admin and assigned as a draft to a TA; the TA reviews in their own account and sends from their own identity. No impersonation, single sender identity. Available on Private Messages and Blast Emails. | | Registration filter preset (v2) | Saved filter on Semester Hub > Enrollment showing all new + returning enrollees to the current semester (students with user_link_level_tag.created_at within the semester's registration window), sorted by enrollment date (newest first). An optional sub-filter toggle "New This Semester Only" narrows to new Level 0 first-time enrollees. Replaces the proposed standalone Registration Tracker screen. Co-located with Level 0 bulk-promote action (target: Level 2). | | Onboarding Support tab (v2) | Semester Hub tab grouping student-facing onboarding affordances: Telegram/WhatsApp group links, welcome videos, countdown timer to next semester. | | Admin Notes tab (v2) | Student Detail tab for private admin-only notes on a student. Not visible to student or TA. |

9. Document Index

10. Workflow Improvement Summary

Quantified impact of the redesign across the core admin workflows.

External tool reduction: 15+ dependencies → 1 (Vimeo for video URLs). Google Sheets eliminated. Stripe dashboard eliminated. External mail merge eliminated (new in v2 via Blast Emails). WhatsApp eliminated (new in v2 via Private Messages).

v2-specific workflow improvements beyond v1

• Communication unification (WF7): previously no unified outbound messaging — v2 consolidates five channels (automation email, blast email, push, announcement, private message) into one domain with a shared recipient filter, unified audit trail, and pre-draft pattern replacing identity switching.
• Registration Tracker integration (WF1): enrollment visibility during the registration window is now served by a filter preset + co-located Level 0 bulk-promote on Semester Hub > Enrollment, avoiding a separate screen and duplicated student-list logic per ADR-005.
• Assignment configuration clarity (WF6): the hybrid matrix per ADR-002 aligns the configuration surface with how the stakeholder actually configures assignments (per-TA constraints) rather than abstract rules, reducing cognitive overhead during TA onboarding.
• Onboarding affordances (WF1): the new Onboarding Support tab groups student-facing onboarding tools (group links, videos, countdown) that previously required cross-domain navigation or did not exist.