Admin Spec — Student Management

Student Management

Domain 2 of the Enhanced Candidate A navigation structure. Contains: Students list, Student Detail Page (6 tabs), Submissions, Promoted Students, Failed Sign Ups. Primary workflows served: WF2 (Student Support), WF3 contribution (Semester Close -- promotion tracking)

1. Domain Overview

Student Management is the most-used domain. It groups everything that affects an individual student -- profile, academic progress, billing, appointments, and lifecycle actions. Moving Submissions, Promoted Students, and Failed Sign Ups here (from Program and Reports respectively) means all student-centric data is accessible under one domain.

Key design decisions:

• Submissions moved here because they are student activity, not passive content
• Promoted Students and Failed Sign Ups moved here because they are student lifecycle reports
• The Student Detail Page consolidates 5+ screens into a single multi-tab view, reducing WF2 (Student Support) from 5-7 screens to 1-2 screens

Sidebar items:

Student Management
  Students                    <- from People > Students
  Submissions (Assessments)   <- from Program > Submissions
  Promoted Students           <- from Reports > Promoted Students
  Failed Sign Ups             <- from Reports > Failed Sign Ups

Data tables referenced: users, user_profile, user_link_level_tag, student_submitted_assessment, appointments, subscriptions, level_tag, semester, group_members, group_name, assessment

2. Screen: Students List

2.1 Purpose

View, filter, and manage all student accounts. Primary entry point to individual student profiles.

2.2 Entry Points

• Sidebar: Student Management > Students
• Dashboard: alert tile clicks (e.g., "Students Falling Behind" -> filtered list)
• Global search: student result click (goes to Student Detail, not list)

2.3 Layout

Filter bar + data table + pagination

Breadcrumb: Student Management > Students

2.4 Data Displayed

2.5 Actions

Add Student modal fields:

On save: creates users record (user_type=3, user_activation_status=1), creates user_profile record, creates user_link_level_tag enrollment record (user_semester_status=1), generates temp_pass (4 chars, lowercase), sends registration email.

2.6 States

2.7 Role Visibility

• Admin: Full table + all actions
• TA: Filtered to assigned students only (via group_members -> group_name.teacher_id matching logged-in TA user_id). No Add Student, no Bulk Deactivate, no Bulk Export
• View-Only: Full table, no action buttons
• Support Staff: Full table, no action buttons

3. Screen: Student Detail Page (Rich Entity Page)

This is the single most important new screen in the redesign. It consolidates data from Students, Submissions, Payments (Stripe), Appointments, and enrollment records into a single multi-tab view.

3.1 Purpose

Provide a complete view of a student -- their profile, academic progress, billing, appointments, semester history, and available actions -- without ever leaving the page. Directly addresses WF2 (Student Support): current state requires 5-7 screens across 3 external tools; Enhanced A requires 1 screen with all data on tabs.

3.2 Entry Points

• Students list: row click
• Global search: student result click
• Dashboard: alert tile link (e.g., failed payment -> Student Detail > Payments tab)
• Promoted Students: student name click
• Failed Sign Ups: student name click
• Submissions list: student name click
• Semester Hub > Enrollment tab: student name click
• Billing > Payment Overview: student name click in alert list
• Billing > Family Plans: member name click
• Direct URL: /students/{user_id} or /students/{user_id}#payments

3.3 Entity Header (persistent across all tabs)

Data displayed:

Always-visible actions:

Breadcrumb: Student Management > Students > [Student Name]

3.4 Tab Structure

Tab behavior follows global pattern (see 01-global-patterns.md section 4.11): lazy-load on first activation, state preserved when switching, URL updates with tab name, tab bar sticky on scroll.

Tab-level loading and error states (applies to ALL tabs unless overridden per-tab):

• Loading: Each tab shows a skeleton layout matching its content structure on first activation. For the Payments tab (which fetches from Stripe), the loading state shows "Loading billing data..." with a spinner; if slow (>3s), updates to "Fetching from Stripe..." per 01-global-patterns.md Section 4.9.
• Error: Each tab shows an inline error message with a "Retry" button if its data fails to load. For the Payments tab specifically, see the Stripe API error state in Section 3.7. For local-data tabs (Profile, Submissions, Appointments, Semester History, Actions), errors show: "Unable to load [tab name] data. Please try again." with a Retry button.

3.5 Tab: Profile

Data Displayed

Personal Information section:

Enrollment section:

Tags section:

System section (collapsed by default):

Actions

States

• Loaded: All sections populated with data
• Minimal profile: Some fields empty (e.g., new student, no picture, no phone) -- show dashes ("--") for empty optional fields
• Inactive student: Status badge shows Inactive in header; profile data still fully visible

3.6 Tab: Submissions

Data Displayed

Table of all submissions across all semesters (default filtered to current semester):

Filter: Semester dropdown populated from distinct semester.name values across this student's user_link_level_tag records. Default: current semester. Option: "All Semesters".

Summary bar (above table): "X submissions this semester | Y reviewed | Z under review | Average grade: N.N"

• X = count of student_submitted_assessment for current user_link_level_tag_id
• Y = count where assessment_status = 1
• Z = count where assessment_status = 0
• Average grade = mean of reviewed submission grades

Actions

States

• Has submissions: Table populated, summary bar shows counts
• No submissions this semester: "No submissions for [Semester Name]." + "View All Semesters" link (changes filter to "All Semesters")
• No submissions ever: "This student has not submitted any recordings yet."

3.7 Tab: Payments (NEW -- cornerstone billing integration)

This tab eliminates the need to visit Stripe Dashboard or Google Sheets for individual student billing. Addresses workarounds W1 (Stripe dependency), W5 (support staff access), W8 (linked deactivation).

Data fetching: Real-time Stripe API call on tab activation (see 01-global-patterns.md section 5.1). Customer resolved via users.stripe_customer_id -> Stripe Customer API, following the resolution chain in 01-global-patterns.md section 5.2.

Data Displayed

Subscription Status section (source: Stripe GET /v1/subscriptions?customer={stripe_customer_id}&limit=1&status=all):

Payment Method section (source: Stripe GET /v1/customers/{id}/payment_methods?type=card&limit=1):

Payment History section (source: Stripe GET /v1/invoices?customer={stripe_customer_id}&limit=12):

Pagination: "Show More" button loads next 12 invoices (starting_after cursor).

Special Flags section (source: local DB tables -- NEW):

Upcoming Payment section (source: Stripe GET /v1/invoices/upcoming?customer={stripe_customer_id}):

Actions

States

Support Staff View

• All data sections visible (subscription status, payment method [last 4 only], payment history, special flags, upcoming payment)
• NO action buttons visible (Cancel, Pause, Resume, Apply Discount, Assign Scholarship, Link Family, Send Payment Link, Retry Payment -- all hidden)
• "View in Stripe" link hidden (assumption per OQ9: support staff do not have Stripe access)

3.8 Tab: Appointments

Data Displayed

Table of all appointments (past and upcoming) for this student:

Status derivation logic:

Filter: upcoming / past / all (default: upcoming)

Summary: "X upcoming appointments | Y completed this semester"

• X = count where apt_time > NOW() and student_id = user_id
• Y = count where apt_time < NOW() and completed, filtered to current semester date range

Actions

States

• Has upcoming: Table with upcoming appointments highlighted (blue left border on rows)
• No upcoming: "No upcoming appointments." + "Schedule Appointment" button (Admin only)
• No appointments ever: "No appointment history for this student."

3.9 Tab: Semester History (NEW)

Data Displayed

Table of all semesters the student has been enrolled in, derived from all user_link_level_tag records for this user_id:

Summary: "Enrolled in X semesters | Current level: [Level] | Student since: [earliest semester name]"

Actions

States

• Multi-semester student: Full table with history, summary bar shows total count
• First-semester student: Single row. Message below table: "This is [first_name]'s first semester."
• No completed semesters: Shows current enrollment row only (status = Enrolled)

3.10 Tab: Actions

Contains lifecycle actions that affect the student's account or academic status. These are separated into their own tab because they are infrequent, consequential, and need clear visibility.

Layout

Actions displayed as a vertical list of action cards, each with:

• Action name (bold)
• Description (1-2 sentences explaining what the action does)
• Button (right-aligned)
• Availability indicator (enabled/disabled with reason)

Actions grouped into two sections: Academic Actions and Account Actions.

Academic Actions

Account Actions

Deactivate Account -- context-dependent confirmation:

• No active subscription: Simple destructive confirmation: "Deactivate [first_name last_name]'s account? They will lose access to all content."
• Active subscription exists: Dual-option confirmation dialog:
  • Title: "This student has an active subscription"
  • Body: "[first_name last_name] has an active [plan name] subscription (next billing: [date])."
  • Option 1 button: "Deactivate Only" -- sets user_activation_status = 0, leaves subscription active (student stops accessing content but billing continues until separate cancellation)
  • Option 2 button (recommended): "Cancel & Deactivate" -- cancels Stripe subscription (cancel_at_period_end=true) + sets user_activation_status = 0 in single transaction (linked deactivation per business rule #11)
  • Cancel button: "Never mind"

States

• Active student: All applicable actions shown based on availability rules
• Inactive student: Only "Reactivate Account" and "Resend Registration Email" shown in Account Actions. Academic Actions section hidden (cannot modify academic status while inactive).
• View-Only / Support Staff: Tab hidden entirely (no actions available for these roles, so tab is not rendered in the tab bar)

3.11 Cross-Tab Behaviors

When an action on one tab changes data that is visible on other tabs or the entity header, the UI must update without requiring a full page reload.

Implementation note: Cross-tab updates should use local state management (e.g., React context or Redux) to propagate changes without re-fetching all tab data. Stripe-dependent data (Payments tab) should re-fetch from Stripe API when the tab is re-activated after a billing action.

4. Screen: Submissions (Assessments)

4.1 Purpose

Cross-student view of all submissions (assessments). This is the assessment management screen -- creating/editing the recording prompts that students respond to, plus viewing all submitted recordings across all students.

Note: This differs from the Student Detail Page's Submissions tab, which shows one student's submissions. This screen shows ALL submissions across ALL students, and also manages the assessment definitions themselves.

4.2 Entry Points

• Sidebar: Student Management > Submissions
• Dashboard: via alert tile (e.g., "12 Submissions Under Review")
• Semester Hub > Setup Checklist: deep link to create assessments for new semester

4.3 Layout

Two views toggled via segmented control at top of page:

• Assessments view (default): List of assessment definitions (prompts)
• Submissions view: List of student-submitted recordings

Breadcrumb: Student Management > Submissions

4.4 Data Displayed -- Assessments View

Filters: Semester (dropdown), Level (dropdown)

4.5 Data Displayed -- Submissions View

Filters: Semester (dropdown), Level (dropdown), Status (dropdown: Under Review / Reviewed / All), TA (dropdown: filters to submissions from students assigned to selected TA)

4.6 Actions

Assessments view actions:

Submissions view actions:

4.7 States

• Assessments view loaded: Assessment list with data
• Assessments view empty: "No assessments created for this semester." + "Create Assessment" button
• Submissions view loaded: Submissions list with data
• Submissions view empty: "No submissions yet for this semester."
• Loading: Skeleton table (see 01-global-patterns.md section 4.9)
• Error: "Unable to load data. Please try again." + "Retry" button

4.8 Role Visibility

• Admin: Full CRUD on both views (create/edit/delete assessments, review/delete submissions)
• TA: Submissions view only, filtered to their assigned students. Can review submissions (set grade, approve/reject). Cannot create/edit/delete assessments. Cannot access Assessments view.
• View-Only: Read-only on both views, no action buttons

5. Screen: Promoted Students

5.1 Purpose

View students who have been promoted to the next level. Used during and after semester close (WF3) to track promotion outcomes and identify repeat signups.

5.2 Entry Points

• Sidebar: Student Management > Promoted Students
• Semester Hub > Close Workflow > Step 2 (Confirm Promotions): link to this screen filtered to that semester

5.3 Layout

Filter bar + data table

Breadcrumb: Student Management > Promoted Students

5.4 Data Displayed

Filters: Semester (dropdown, default: current semester), Level From (dropdown), Level To (dropdown)

Summary bar: "X students promoted this semester | Y repeat signups"

5.5 Actions

5.6 States

• Has promotions: Table populated, summary bar shows counts
• No promotions: "No students have been promoted for [semester name]." (expected state before semester close workflow runs)
• Loading: Skeleton table
• Error: Standard error pattern

5.7 Role Visibility

• Admin: Full view + export
• View-Only: Full view + export
• TA / Support Staff: Hidden from sidebar (not in their navigation per role matrix)

6. Screen: Failed Sign Ups

6.1 Purpose

View incomplete student registrations (users.user_type = 4) for troubleshooting and follow-up. These are accounts where the registration process started but was not completed.

6.2 Entry Points

• Sidebar: Student Management > Failed Sign Ups

6.3 Layout

Filter bar + data table

Breadcrumb: Student Management > Failed Sign Ups

6.4 Data Displayed

Filters: Date range (registration date), Device type (dropdown)

6.5 Actions

6.6 States

• Has records: Table populated
• Empty: "No failed sign ups recorded."
• Loading: Skeleton table
• Error: Standard error pattern

6.7 Role Visibility

• Admin: Full view + all actions
• View-Only: View only, no action buttons
• TA / Support Staff: Hidden from sidebar

7. Cross-Domain Navigation Summary

This section documents how Student Management screens link to and from other domains.

7.1 Outbound Links (from Student Management to other domains)

7.2 Inbound Links (from other domains to Student Management)

8. Data Dependencies and API Calls

Summary of data sources required for each screen in this domain.