Admin Spec — Dashboard

Dashboard

Domain 1 (top-level) of the Enhanced Candidate A navigation structure. Replaces: Current passive dashboard that provides no actionable information. Primary workflow served: WF4 (Daily Monitoring — reduced from 4-5 screens to 1-3 screens) Key enhancement from Candidate B: Promoted to operational nerve center with configurable alert tiles and phase-aware prompts.

1. Screen: Dashboard

1.1 Purpose

Operational nerve center that surfaces exceptions, alerts, and phase-aware prompts so the admin can proactively identify and resolve issues. Replaces the current passive dashboard (weekly submission chart + daily notes + TA stats) that the admin ignores because it provides no actionable information.

Interview evidence (Q7 — "What would a useful dashboard show you?"):

• Student-reported app issues
• Year 2 appointment utilization for the week
• Session attendance numbers
• TA submission response time alerts (flagging >48 hours)
• Failed payment alerts for instalment plan students
• Students falling behind on submissions

Deprecated features (present in current dashboard, intentionally removed):

• Daily Notes: The current dashboard has a daily notes / scratchpad area. This is removed — it provides no operational value and was not mentioned as useful in the interview. Admins who need notes can use external tools.
• Live Session Notifications widget: The current dashboard shows a live session notification area. This is replaced by the Semester Progress tile (Tile 6), which surfaces session attendance data during the Active phase, and by the Calendar View in the Scheduling domain for session management. No standalone notification widget is needed.

Design rationale: Candidate B's hub concept scored highest on dashboard depth. The Enhanced Candidate A design incorporates Candidate B's operational dashboard into Candidate A's domain-first sidebar structure. The dashboard is not a domain — it sits above all domains as the universal entry point, surfacing cross-domain alerts with pre-filtered deep links into the relevant domain screens.

1.2 Entry Points

• Default landing page after login
• Sidebar: Dashboard (top item, above all domains)
• Logo/brand click (returns to dashboard from any screen)

1.3 Layout

Three zones, top to bottom:

Zone 1: Phase Prompt Bar (always visible)

• Full-width bar showing current semester phase and progress
• Links directly to Semester Hub

Zone 2: Alert Tiles Grid (2x3 grid, responsive — collapses to single column on narrow viewports)

• Each tile shows a count, label, optional trend indicator, and links to resolution context
• Tiles with count=0 are collapsed/hidden (except Semester Progress tile during Active phase)
• Uses Alert Tile pattern from 01-global-patterns.md Section 4.4

Zone 3: Quick Actions + Activity (bottom)

• Row of quick action buttons for the most common admin tasks
• Optional: recent activity feed (last 10 system events)

1.4 Phase Prompt Bar

Full-width bar at the top of the dashboard showing the current semester lifecycle phase. Provides contextual awareness and a direct link to the Semester Hub for the active semester.

Data source: semester table — active semester determined by is_current = 1

Phase detection logic (evaluated in order):

1. If no semester has is_current=1 → No Active
2. If NOW() < start_date + 14 days AND setup checklist has incomplete items → Setup
3. If end_date - NOW() < 21 days → Close
4. Otherwise → Active

Visual treatment:

• Setup: blue background, progress bar showing X/Y completion
• Active: neutral/white background, inline stats
• Close: amber background, step indicator (step dots 1-5 with current highlighted)
• No Active: gray background, call-to-action button

1.5 Alert Tiles

Six configurable alert tiles arranged in a 2x3 grid. Each tile follows the Alert Tile pattern defined in 01-global-patterns.md Section 4.4. Tiles with count=0 are hidden to reduce visual noise — the dashboard shows only items that need attention.

Tile 1: Failed Payments

• Icon: Credit card with warning triangle
• Count: Number of records in billing_alerts where type='invoice.payment_failed' AND status='new' AND created_at within last 30 days
• Label: "Failed Payments"
• Color: Red border (when count > 0)
• Trend: vs. previous 30-day window (↑/↓/—)
• Click target: Billing & Payments > Payment Overview, scrolled to Failed Payments alert section (see 08-billing-payments.md Section 2.5)
• Threshold: Show only when count > 0
• Data source: billing_alerts table (webhook-cached, <100ms latency)
• Refresh: Real-time via webhook events; no polling needed

Tile 2: TAs Behind on Reviews

• Icon: Clock with warning triangle
• Count: Number of TAs who have at least one submission pending review for >48 hours
• Label: "TAs Behind on Reviews"
• Count source: For each TA (users where user_type=2), query student_submitted_assessment where assessment_status=0 (under review) AND reviewed_by IS NULL. If NOW() - submitted_at > 48 hours for any submission assigned to that TA, the TA is counted. Count = number of distinct TAs with at least one overdue submission.
• Color: Yellow border
• Click target: Teacher Management > Teaching Assistants, pre-filtered to show only TAs with overdue reviews (filter: has_overdue_reviews=true). If only one TA is flagged, navigate directly to that TA Detail Page > Performance tab.
• Threshold: Show only when count > 0
• Data source: student_submitted_assessment table (local database query)
• Refresh: Computed on dashboard load; cached for 5 minutes

Tile 3: Students Falling Behind

• Icon: User silhouette with downward arrow
• Count: Number of students whose submission count is below expected pace for the current semester week
• Label: "Students Behind"
• Count source: Expected pace = 1 submission per week. Current week number = FLOOR((NOW() - semester.start_date) / 7). A student falls behind when their total student_submitted_assessment count for the active semester is less than current_week_number - 2 (2-week grace period). Only counts students with user_status=1 (active) in the current semester.
• Color: Yellow border
• Click target: Reporting > Student Report, pre-filtered to behind-pace students (filter: pace=behind). Alternative: Student Management > Students with same filter.
• Threshold: Show only when count > 0
• Data source: student_submitted_assessment + user_link_level_tag + semester tables (local database query)
• Refresh: Computed on dashboard load; cached for 15 minutes (pace changes slowly)

Tile 4: Appointment Utilization (Year 2)

• Icon: Calendar with percentage overlay
• Count: Ratio display — booked appointments vs. available slots for the current week, scoped to Year 2 students
• Label: "Y2 Appointments: X/Y booked"
• Format: "12/20 booked" (not a single number — shows ratio)
• Color: Blue border (informational)
• Click target: Scheduling > Calendar View, pre-filtered to Year 2 appointments for the current week
• Threshold: Always show during Active phase (Year 2 appointment visibility is a standing concern per interview Q7). Hidden during Setup, Close, and No Active phases.
• Data source: appointments table, filtered by level_tag for Year 2 and date range for current week
• Refresh: Computed on dashboard load; cached for 15 minutes

Tile 5: App Issues

• Icon: Bug/alert icon
• Count: Number of student-reported issues in Issue Queue with status='open'
• Label: "App Issues"
• Color: Yellow border when count > 0; hidden when count = 0
• Click target: Admin & System > Issue Queue, pre-filtered to status=open
• Threshold: Show only when count > 0
• Data source: Issue Queue table (to be defined in 10-admin-system.md)
• Refresh: Computed on dashboard load; cached for 5 minutes

Tile 6: Semester Progress (contextual)

This tile adapts its content based on the current semester phase, providing a summary view that complements the Phase Prompt Bar.

• Color: Blue border (informational)
• Click target: Semester Hub > relevant tab based on current phase (Setup Checklist, Overview, or Close Workflow)
• Data source: Setup — semester_setup_checklist (new table, see 04-semester-management.md). Active — student_submitted_assessment + live session attendance records. Close — close workflow state (see 04-semester-management.md).
• Refresh: Computed on dashboard load; cached for 15 minutes

1.6 Quick Actions

Row of shortcut buttons below the alert tiles grid. Provides one-click access to the most common admin tasks without navigating through the sidebar.

Layout: Horizontal row, equally spaced. Each button has an icon above the label. Subtle border/card style, not primary-button style (these are shortcuts, not primary actions).

1.7 States

1.8 Role Variants

The dashboard adapts its content based on the logged-in user's role. See 01-global-patterns.md Section 3 for role definitions.

Admin Dashboard

Full dashboard as described in Sections 1.3–1.7 above. All tiles, all quick actions, Phase Prompt Bar visible.

TA Dashboard

TAs see a personalized dashboard scoped to their own students and schedule.

View-Only Dashboard

Same layout and tiles as Admin Dashboard with the following differences:

• Quick action "Send Notification" is hidden (view-only users cannot create notifications)
• All tile click-throughs link to view-only versions of target screens (action buttons hidden on destination screens, per 01-global-patterns.md Section 3.4)
• All other tiles and data visible — view-only users need full operational awareness

Support Staff Dashboard

Same as View-Only Dashboard:

• Quick action "Send Notification" is hidden
• All tile click-throughs link to view-only versions of target screens
• Billing tiles (Failed Payments) visible but link to view-only Payment Overview (no action buttons)

1.9 Data Dependencies

Summary of all data sources the dashboard requires, for implementation planning.

Performance target: Dashboard should fully render (all tiles loaded) within 2 seconds on a standard connection. Skeleton loading state (Section 1.7) appears within 200ms.

Partial failure handling: Each tile fetches data independently. A failure in one tile (e.g., Stripe timeout for Failed Payments) does not block other tiles from loading. See Partial failure state in Section 1.7.

1.10 Accessibility and Responsiveness

Accessibility:

• All tiles are keyboard-navigable (Tab to move between tiles, Enter to activate)
• Tile counts are announced by screen readers with context (e.g., "3 Failed Payments, alert")
• Color is never the sole indicator — count numbers, labels, and icons provide information independent of color
• Phase Prompt Bar progress indicators have ARIA labels (e.g., "Setup progress: 5 of 8 items configured")

Responsiveness:

• Desktop (>1200px): 2x3 tile grid, full Phase Prompt Bar, horizontal quick actions
• Tablet (768-1200px): 2x3 grid maintained, sidebar collapsed to icons
• Narrow (< 768px): Single-column tile stack, Phase Prompt Bar wraps, quick actions stack vertically

1.11 Empty State

When the dashboard has no active semester and all alert tiles would be hidden:

• Icon: Dashboard illustration (neutral)
• Message: "Welcome to QuranFlow Admin. No active semester is configured."
• Suggested action: "Create a semester" button (→ Semester Management > Semesters) or "Activate an existing semester" link
• Quick actions: Search Student and Send Notification remain available even in this state

2. Cross-References