Mockup Implementation Plan

QuranFlow Admin Mockup — Implementation Plan

Approach

Build screen-by-screen in dependency order. Each phase produces working, navigable screens committed to git. Complex screens first (they set patterns), simple screens follow fast.

Execution Loop

Each phase below is one iteration of this loop.

Standard Loop (every phase)

1. Read spec — Read the spec section(s) listed in the phase. Full paths are provided in each phase header.
2. Plan components — Before writing code, identify what UI elements the screen needs (tables, cards, modals, tabs, etc.) and search for matching shadcn components:
   • bunx --bun shadcn@latest search -q "..." — find components by keyword
   • bunx --bun shadcn@latest docs <component> — read docs/examples for each component you'll use
   • Use Explore subagents in parallel if the phase uses 3+ new components — one agent per component, each returns docs URLs and API patterns. This avoids serial CLI round-trips.
3. Install — Run the phase's install block (shadcn components, dependencies). Add any additional components discovered in step 2.
4. Build — Build the screen(s) listed in the phase. Use TodoWrite to track items when the phase has 4+ build items.
5. Simplify — Run /simplify on the diff. This launches 3 parallel review agents (reuse, quality, efficiency) and fixes any issues found.
6. Verify — Run all checks:
   • bun run build — no type errors
   • bun run lint — no lint violations
   • Code review against spec — re-read the spec section referenced in the phase. Confirm every column, filter, action, and state listed in the spec is present in the code.
   • Smoke test (pattern-setting phases only: 0, 1, 3, 4) — run bun run dev, open in browser, confirm the page renders and basic navigation works.
7. Commit — Use /commit to create a commit for the phase.

Additional steps for pattern-setting phases (0, 1, 3, 4)

These phases establish patterns that every subsequent phase copies. Errors here propagate everywhere.

• Extra review — After simplify, before committing: re-read all shared components and layout files touched in this phase. Check that naming, prop patterns, and file structure are ones you'd want replicated 30+ times. Fix anything you wouldn't want copied.

Additional steps for complex phases (4, 6, 10)

Student Detail (6 tabs), Semester Hub (Close Workflow), and Billing (6 screens with Stripe data) are high-complexity.

• Think through layout — Before building (before step 4), spend time reasoning about tab layout, data flow between tabs, and interaction patterns. No formal document needed — just think through: what data does each tab show, how do tabs share entity context, what cross-links exist, what states need handling. Write brief notes as comments in the page file if helpful.

Parallel execution for repetitive phases (7, 8, 11, 12)

Content (6 list screens), Scheduling (5 screens), Reporting (5 screens), and Admin (5 screens) are independent screens following established patterns.

• Parallelize with subagents — Launch parallel general-purpose subagents, one per independent screen. Each agent receives: (a) the relevant spec section text, (b) the shared component import paths, (c) the mock data file for that domain, and (d) a reference to an existing list screen (e.g., Students List from Phase 3) as the pattern to follow. Agents build screens independently; results are reviewed together in the simplify step.

Where to use subagents

Loop summary

Design Reference

Principles extracted from Stripe's admin UI (Product Catalog, Billing Overview, Invoices) as structural reference — not to copy visually, but to inform layout decisions per-screen.

• Page hierarchy: Title → contextual navigation → filters → content. Consistent across screens, but the type of contextual navigation (tabs, toggles, segmented controls) should be chosen per-screen based on what data and workflows exist.
• Data density: Tables should be dense and scannable. Inline status badges, no card wrappers around tables. Maximize information per row.
• Filter chips: When filters are applied, show them as removable chips below the filter bar (e.g., "Status: Active ×"). Provides clear affordance for what's filtered.
• Metric cards: Dashboard and Payment Overview use metric cards with trend indicators. Keep compact — value + label + trend arrow, not oversized hero numbers.
• Action placement: Primary actions (Add, Export) right-aligned in page header. Secondary actions in dropdown menus.
• Per-screen filtering: Whether a screen uses horizontal status tabs, toggle buttons, or dropdown filters should be decided when building that screen based on: (a) how many statuses exist, (b) how frequently users switch between them, (c) whether counts per status are useful. Don't default to tabs everywhere.

Phase 0: Shell & Routing -- COMPLETE

Goal: App skeleton — sidebar navigation, routing, page header, breadcrumbs. Every future screen slots into this shell.

Spec reference: docs/admin-spec/01-global-patterns.md Sections 1 (Navigation Shell), 2 (Global Search), 3 (Role-Based Access)

Install:

bun add react-router
bunx --bun shadcn@latest add sidebar-07 breadcrumb scroll-area avatar sonner

sidebar-07 provides the "collapses to icons" sidebar pattern. It installs: sidebar, separator, tooltip, input, skeleton, sheet, use-mobile hook. Theme provider already exists (src/components/theme-provider.tsx).

Build:

• src/components/layout/app-shell.tsx — sidebar + main content area using shadcn Sidebar (sidebar-07 pattern)
• src/components/layout/app-sidebar.tsx — 8+1 domain sidebar with icons per spec Section 1.1, collapsible to icon-only
• src/components/layout/page-header.tsx — title, subtitle, primary action button, breadcrumb
• src/components/layout/breadcrumb-nav.tsx — Domain > Screen > Entity pattern
• src/App.tsx — React Router setup with all routes (pages can be placeholder divs initially)
• Global search bar in sidebar (UI only — no search logic yet)
• Dark mode toggle button in sidebar footer

Routes to define (from docs/admin-spec/00-spec-index.md Section 3 navigation tree):

/                                    → Dashboard
/students                            → Students List
/students/:id                        → Student Detail (tabbed)
/submissions                         → Submissions
/promoted-students                   → Promoted Students
/failed-signups                      → Failed Sign Ups
/semesters                           → Semesters List
/semesters/:id                       → Semester Hub (tabbed)
/welcome-package                     → Welcome Package
/email-management                    → Email Management
/tags                                → Tags
/operations                          → Operations
/content/video-lessons               → Video Lessons
/content/resources                   → Resources
/content/recordings                  → Recordings
/content/tutorials                   → Tutorials
/content/mcq-questions               → MCQ Questions
/content/quizzes                     → Quizzes
/scheduling/calendar                 → Calendar View
/scheduling/live-sessions            → Live Sessions
/scheduling/appointments             → Upcoming Appointments
/scheduling/ta-schedules             → TA Schedules
/scheduling/holidays                 → Holidays
/teachers                            → Teaching Assistants List
/teachers/:id                        → TA Detail (tabbed)
/teacher-criteria                    → Teacher Assignment Criteria
/ta-reports                          → TA Reports
/student-groups                      → Student Groups
/billing/overview                    → Payment Overview
/billing/payments                    → Payments
/billing/plans                       → Payment Plans
/billing/coupons                     → Coupons
/billing/family-plans                → Family Plans
/billing/scholarships                → Scholarships & Deferments
/reporting/student-report            → Student Report
/reporting/referrals                 → Referrals
/reporting/specific-reports          → Specific Reports
/reporting/composition               → Student Composition
/reporting/logs                      → Logs
/admin/admins                        → Admins
/admin/settings                      → Settings
/admin/notifications                 → Notifications
/admin/support-links                 → Support Links
/admin/issue-queue                   → Issue Queue

Verify: Clicking every sidebar item navigates to the correct route. Breadcrumbs render. Sidebar highlights the active section. Collapse to icons works. Dark mode toggle switches theme.

Phase 0.5: Data Model & Mock Data -- COMPLETE

Goal: Complete type definitions and all mock data files. Getting data right before building components prevents rework — every screen consumes this data.

Spec reference: All spec docs in docs/admin-spec/ for column/field definitions. Legacy backend docs at /Users/kamran/Downloads/QuranFlowDocumentationFiles/BackendDocumentation/ for data model reality.

Step A — Update src/data/types.ts (already done):

• Added 7 entities: Assessment, Elective, LiveSession, TaSchedule, Subscription, EmailTemplate, AuditLog
• Extended 5 entities: Student (+country, groupId, groupName, electiveId, practiceTier), Semester (+contentAvailabilityDate, launchPartyDateTime, launchPartyZoomLink, isRegistration), Teacher (+gender, profilePicture), FamilyGroup (+stripeCustomerId), Submission (+assessmentId)
• Added enums: GenderScope, EmailCategory

Step B — Create mock data files (build in dependency order):

Cross-referencing: All mock data must be internally consistent. Student.taId references a real Teacher.id. Submission.studentId references a real Student.id. Dashboard alert counts match the actual data (e.g., students with subscriptionStatus "Failed" = Failed Payments tile count).

Verify: bun run build passes. Every data file exports typed arrays. Import a few in a scratch component to confirm no circular deps.

Phase 1: Shared Components -- COMPLETE

Goal: Reusable building blocks that every screen needs. Create once, use everywhere.

Spec reference: docs/admin-spec/01-global-patterns.md Sections 4 (Component Patterns)

Install:

bun add @tanstack/react-table
bunx --bun shadcn@latest add table badge card dialog alert-dialog select dropdown-menu checkbox tabs collapsible pagination

Build shared components:

• src/components/shared/data-table.tsx — wraps shadcn Table + TanStack Table. Supports: column sorting (▲/▼), row hover, row click navigation, checkbox bulk selection, pagination ("1-25 of 342"). Per spec Section 4.1.
• src/components/shared/filter-bar.tsx — search input + dropdown filters + active filter chips with × (removable). Per spec Section 4.2.
• src/components/shared/status-badge.tsx — maps all status strings to badge colors per spec Section 4.3. Single component, one source of truth for all status styling.
• src/components/shared/alert-tile.tsx — icon, count, label, trend, color border, clickable. Per spec Section 4.4.
• src/components/shared/metric-card.tsx — label, value, optional trend. Compact layout. Per spec Section 4.5.
• Empty state — uses shadcn's @shadcn/empty component directly (no custom empty-state.tsx needed). Per spec Section 4.8.
• src/components/shared/confirm-dialog.tsx — standard and destructive variants with optional typed confirmation. Per spec Section 4.6.
• src/components/shared/section-header.tsx — title, optional action link, optional count. Per spec Section 4.12.

Verify: Import shared components into a scratch page. Render a DataTable with student mock data. Render StatusBadges for every status type. Render alert tiles. Confirm visual consistency.

Phase 2: Dashboard -- COMPLETE

Goal: The landing page — operational nerve center with alert tiles, phase prompt, quick actions.

Spec reference: docs/admin-spec/02-dashboard.md (all sections)

Build:

• src/pages/dashboard/index.tsx — three-zone layout per spec Section 1.3
• Phase Prompt Bar — full-width, semester-aware, color-coded by phase (Setup=blue, Active=neutral, Close=amber). Per spec Section 1.4. All 4 states implemented (Setup, Active, Close, NoActive).
• Alert Tiles Grid — 2x3 grid using AlertTile component. 6 tiles per spec Section 1.5 (Failed Payments, TAs Behind, Students Behind, Y2 Appointments, App Issues, Semester Progress).
• Quick Actions row — 4 shortcut buttons per spec Section 1.6.
• States: normal (has alerts), all-clear, no-semester. Per spec Section 1.7. Route wired in App.tsx.

Verify: Dashboard renders with mock alert data. Phase prompt shows "Active" state. Tile clicks navigate to target screens. Quick actions navigate. Skeleton state renders on initial load.

Phase 3: Student Management — Students List -- COMPLETE

Goal: The most-used list screen. Sets the pattern for all other list screens.

Spec reference: docs/admin-spec/03-student-management.md Sections 1-2

Build:

• src/pages/student-management/students.tsx — filter bar + data table + pagination
• Columns per spec Section 2.4: Name, Email, Level, Semester, TA, Status, Subscription, Submissions, Last Submission
• Filters: search (name/email), semester dropdown, level dropdown, status dropdown, subscription status dropdown
• Actions: row click → student detail, "Add Student" button (opens modal shell), bulk export, bulk deactivate
• Add Student modal with fields per spec Section 2.5
• All states per spec Section 2.6

Also completed: Refactored all Card-based shared components (MetricCard, AlertTile, PhasePromptBar, QuickAction) to use proper shadcn Card composition (CardHeader/CardTitle/CardAction/CardContent/CardFooter).

Verify: Table renders 20 students. Sorting works on all sortable columns. Filters narrow results. Row click navigates to /students/:id. "Add Student" opens modal. Pagination shows "1-20 of 20".

Phase 4: Student Management — Student Detail Page -- COMPLETE

Goal: The single most important new screen. 6-tab entity page. Sets the entity page pattern for Semester Hub and TA Detail.

Spec reference: docs/admin-spec/03-student-management.md Sections 3.1-3.11

Build:

• src/pages/student-management/student-detail/index.tsx — entity header + 6 tabs
• Entity header: name, email, level badge, semester, TA (clickable → TA Detail), status badge, subscription badge. Per spec Section 3.3.
• Tab: Profile — personal info (incl. country, phone, timezone), enrollment, tags, system info (collapsible) sections. Per spec Section 3.5.
• Tab: Submissions — table with semester filter, summary bar (total/reviewed/under review/avg grade). Per spec Section 3.6.
• Tab: Payments — subscription card (status, plan, next billing), action buttons (Cancel/Pause/Retry contextual), payment history table, special flags (family/scholarship/deferment with links), past due/paused banners. Per spec Section 3.7. Uses static mock Stripe data.
• Tab: Appointments — table with upcoming/past/all filter, status badges, Schedule + Calendar View buttons, TA links. Per spec Section 3.8.
• Tab: Semester History — enrollment history table with level progression, clickable semester links, summary bar, first-semester message. Per spec Section 3.9.
• Tab: Actions — action cards grouped into Academic + Account sections. Promote (disabled when not Pass), Register for Year 2 (Level 4 only), Reset Progress (destructive with typed confirmation), Deactivate (subscription-aware). Inactive state shows only Reactivate + Resend. Per spec Section 3.10.

Verify: Navigate from Students list → Student Detail. All 6 tabs render with data. Tab URL updates (#profile, #submissions, etc.). Entity header stays fixed across tabs. Action confirmations show correct dialog types.

Phase 5: Student Management — Remaining Screens

Spec reference: docs/admin-spec/03-student-management.md Sections 4-7

Build:

• src/pages/student-management/submissions.tsx — dual-view (Assessments / Submissions toggle). Per spec Sections 4.3-4.5.
• src/pages/student-management/promoted-students.tsx — list screen. Per spec Section 5.
• src/pages/student-management/failed-signups.tsx — list screen. Per spec Section 6.

Verify: All three screens render. Student name clicks navigate to Student Detail. Submissions dual-view toggle works.

Phase 6: Semester Management

Goal: Semester Hub with 4 tabs including Setup Checklist and Close Workflow — the two most complex workflow UIs.

Spec reference: docs/admin-spec/04-semester-management.md (all sections)

Install:

bunx --bun shadcn@latest add progress switch accordion

Build:

• src/pages/semester-management/semesters.tsx — semester list with status badges, active indicator
• src/pages/semester-management/semester-hub/index.tsx — entity header + 4 tabs
• Tab: Overview — key metrics, status, dates (incl. contentAvailabilityDate, launchPartyDateTime), configuration summary
• Tab: Setup Checklist — checklist items with completion status, "Configure →" deep links, progress tracking. Non-gated (any order). Deep links pass ?semester={id}&level={id}&from=checklist to content screens.
• Tab: Enrollment — enrollment stats, student list by level, enrollment management
• Tab: Close Workflow — gated 5-step sequential wizard:
  • Step 1: Review EOC — summary table of end-of-cycle assessment results by level. Columns: Student Name, Level, EOC Score, Pass/Fail. Pass threshold: 3.5.
  • Step 2: Confirm Promotions — students who passed, grouped by current level → next level. Level progression: L0→L1→L2→L3→L4→Year 2. Bulk "Confirm All" or individual confirm/override. Year 2 students flagged separately.
  • Step 3: Bulk Payment Setup — SIMPLIFIED: summary of promoted students needing subscription updates (count, plan changes, estimated billing impact). Single "Confirm Payment Setup" button. Note: full billing patterns built in Phase 10; can revisit for richer data after.
  • Step 4: Handle Leavers — students not continuing (failed, didn't re-enroll, cancelled). Linked deactivation action (deactivate + cancel Stripe sub). Uses destructive ConfirmDialog.
  • Step 5: Verify & Close — checklist showing all 4 previous steps complete (green checks). "Close Semester" button (destructive, requires confirmation). On confirm: show success toast.
  • Gating: Steps 2-5 show locked state (gray, non-interactive) until prior step marked complete. Simple boolean state array.
• src/pages/semester-management/welcome-package.tsx — welcome video/PDF management per level
• src/pages/semester-management/email-management.tsx — email template list using EmailTemplate data
• src/pages/semester-management/tags.tsx — tag management (performance, welcome, level tags)
• src/pages/semester-management/operations.tsx — bulk operations (mass email, export, etc.)

Verify: Semester list → Semester Hub navigation. Setup Checklist items show completion. Close Workflow shows gated steps (Step 3 locked until Step 2 complete). "Configure →" links navigate with query params.

Phase 7: Content

Spec reference: docs/admin-spec/05-content.md

Build:

• 6 list screens (Video Lessons, Resources, Recordings, Tutorials, MCQ Questions, Quizzes) — all use DataTable + FilterBar pattern
• Filtering: All screens support semester + level filters EXCEPT Recordings (semester only, no level filter per spec)
• Setup Checklist integration: ?semester={id}&level={id}&from=checklist pre-filters and shows "← Return to Setup Checklist" banner at top of page
• Each screen is lightweight — reuse the list screen pattern from Phase 3

Verify: All 6 screens render. Deep links from Setup Checklist pre-filter correctly. Return banner appears and navigates back. Recordings screen has no level filter.

Phase 8: Scheduling

Spec reference: docs/admin-spec/06-scheduling.md

Build:

• src/pages/scheduling/calendar.tsx — custom Tailwind CSS grid with week/month toggle. No external calendar library. Color-coded events by type. Filter by TA, gender, level, event type.
• src/pages/scheduling/live-sessions.tsx — list screen using LiveSession data. Shows level tags, gender scope, timezone.
• src/pages/scheduling/appointments.tsx — list screen with status derivation using Appointment data
• src/pages/scheduling/ta-schedules.tsx — TA selector + weekly availability grid using TaSchedule data
• src/pages/scheduling/holidays.tsx — list/calendar toggle, merged holiday types

Verify: Calendar shows mock events in week view. Filters narrow visible events. TA Schedules shows availability grid for selected TA. Live Sessions shows gender/level scoping.

Phase 9: Teacher Management

Spec reference: docs/admin-spec/07-teacher-management.md

Build:

• src/pages/teacher-management/teachers.tsx — TA list with avg response time column, gender
• src/pages/teacher-management/teacher-detail/index.tsx — entity header + 4 tabs (Profile, Schedule, Students & Groups, Performance)
• src/pages/teacher-management/assignment-criteria.tsx — rules list + repeat student toggle
• src/pages/teacher-management/ta-reports.tsx — TA performance reports
• src/pages/teacher-management/student-groups.tsx — groups list

Verify: TA list → TA Detail navigation. Performance tab shows metrics with threshold highlighting (>48h = red). Student names on Students & Groups tab link to Student Detail.

Phase 10: Billing & Payments

Spec reference: docs/admin-spec/08-billing-payments.md

Build:

• src/pages/billing/overview.tsx — metrics bar (5 cards) + 6 expandable alert sections using Collapsible (Failed Payments, Past Due, Missing Subscriptions, Expiring Scholarships, Deferment Resume Due, Recently Cancelled). Per spec Sections 2.1-2.8.
• src/pages/billing/payments.tsx — transaction history table. Date range filter uses two <Input type="date" /> fields.
• src/pages/billing/plans.tsx — payment plans table with Stripe sync status column, using PaymentPlan + Subscription data
• src/pages/billing/coupons.tsx — coupons table with redemption counts
• src/pages/billing/family-plans.tsx — family list view + family detail view (two-level navigation). Shows shared stripeCustomerId.
• src/pages/billing/scholarships.tsx — tabbed screen (Scholarships tab with Programs/Students toggle + Deferments tab)

Verify: Payment Overview alert sections expand/collapse. Student name clicks navigate to Student Detail > Payments tab. Family Plans list → detail navigation works.

Phase 11: Reporting

Spec reference: docs/admin-spec/09-reporting.md

Build:

• src/pages/reporting/student-report.tsx — DataTable report
• src/pages/reporting/referrals.tsx — referrals tracking
• src/pages/reporting/specific-reports.tsx — specific report types
• src/pages/reporting/composition.tsx — summary cards + detail table per level. Per spec Section 5. Retention rates shown as static percentages.
• src/pages/reporting/logs.tsx — audit log table using AuditLog data

Verify: Student Composition summary cards render. Level click expands student list. Logs screen shows audit entries.

Phase 12: Admin & System

Spec reference: docs/admin-spec/10-admin-system.md

Build:

• src/pages/admin-system/admins.tsx — admin user list
• src/pages/admin-system/settings.tsx — general settings (placeholder)
• src/pages/admin-system/notifications.tsx — notification send form
• src/pages/admin-system/support-links.tsx — ordered links list with edit modal (no drag-reorder)
• src/pages/admin-system/issue-queue.tsx — issue list with status/priority filters, detail view

Verify: Issue Queue filters work. Status changes via dropdown. All screens accessible from sidebar.

Phase 13: Polish & Cross-Cutting

Goal: Wire up cross-screen navigation, global search, and final consistency pass.

Spec reference: docs/admin-spec/00-spec-index.md Section 6 (Workflows WF1-WF6), docs/admin-spec/01-global-patterns.md Section 2 (Global Search)

Install:

bunx --bun shadcn@latest add command

Build:

• Global search (Cmd+K):
  • Command component inside Dialog (standard shadcn pattern)
  • Searches: students (by name/email), TAs (by name), semesters (by name)
  • Result format: "Name · Level · Semester · Status badge" (students), "Name · Assigned students" (TAs), "Name · Status badge" (semesters)
  • Group by entity type, max 5 results per type
  • Click result → navigate to entity page
• All cross-domain click-throughs verified (Dashboard tile → Payment Overview, Student Detail TA name → TA Detail, etc.)
• "Formerly under [Section]" transition hints on relocated screens
• Loading skeletons on every screen
• Empty states on every screen
• Responsive: sidebar collapses at tablet breakpoint, tiles stack at narrow
• Final visual consistency audit — every table, every badge, every header looks the same

Verify: Full walkthrough of all 6 workflows from docs/admin-spec/00-spec-index.md Section 6 (WF1-WF6). Each workflow's screen sequence navigates correctly end to end.

Deferred Items

Spec-defined features deferred for production implementation. Noted here for completeness:

1. Stripe real-time fetch — Payments tab shows static mock data. No latency simulation, staleness indicators, or customer ID resolution chain. (01-global-patterns.md §5)
2. Recent search persistence — Global search doesn't persist last 5 searches across session. (01-global-patterns.md §2.4)
3. Scroll position on checklist return — Return banner navigates back but doesn't restore scroll position. (04-semester-management.md §3.6)
4. Role-based sidebar — Mockup shows Admin view only. No TA/View-Only/Support Staff toggle. (01-global-patterns.md §3)
5. Webhook simulation — Billing alerts use static data, no webhook event flow. (08-billing-payments.md §9)
6. Retention rate computation — Student Composition shows static percentages, not computed from cross-semester enrollment data. (09-reporting.md §5.4)
7. Support Links drag-reorder — Ordered list with edit modal instead. (10-admin-system.md §5)
8. Setup Checklist dynamic status — Static completion states, not dynamically computed from content counts. (04-semester-management.md §3.6)
9. InfusionSoft/CRM sync — Legacy integration not represented in new admin. (Backend docs)
10. Coupon token system — Individual redeemable tokens. Mockup shows coupon-level data only. (Backend docs)
11. Performance tags — Auto-computed Low/Mid/High Performer tags shown as static badges. (Backend docs)

Summary