v2 Admin Spec — Student Management

Student Management

Domain 2 of the Enhanced Candidate A navigation structure. Contains: Students list, Student Detail Page (7 tabs), Submissions, Promoted Students, Failed Sign Ups. Primary workflows served: WF2 (Student Support), WF3 contribution (Semester End -- 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)
• End Checklist Step 2 (Pass/Fail) deep-links here with ?from=end-checklist&semester=[id]&level=1,2,3,4&final_status=null — see 04-semester-management.md §3.8. When ?from=end-checklist is present, the screen shows a persistent "← Return to End Checklist for [Semester Name]" banner at top; clicking returns to the End Checklist tab with scroll position preserved.

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. Can use Set Pass/Fail and bulk Set Pass/Fail for Selected, but only for their own assigned students.
• 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, admin notes, 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, Admin Notes, 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 | R rejected | 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
• R = count where assessment_status = 2
• Average grade = mean of reviewed submission grades

Per-Week Submission Exception section (above table, collapsible panel labeled "Weekly Submission Overrides"):

Displays the allowed number of submissions per week for this student for the current semester, plus any per-week overrides.

Per-week override table:

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."
• No weekly exceptions set: Weekly Submission Overrides panel shows "No week-level exceptions. Student follows the semester default of [N] submissions per week." + "Add Exception" button
• Bulk-select mode: When ≥1 row selected, a sticky action bar appears at the top of the table: "[N] selected" + "Delete Selected" button + "Clear selection" link

3.7 Tab: Payments (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):

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:

Filters:

• Time window: upcoming / past / all (default: upcoming)
• Semester: dropdown populated from distinct semester.name values across this student's user_link_level_tag records, plus "All Semesters". Default: current semester. Filters appointments to those falling within the selected semester's date range.

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."
• No appointments in selected semester: "No appointments for [Semester Name]." + "View All Semesters" link (changes semester filter to "All Semesters")

3.9 Tab: Semester History

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.9.5 Tab: Admin Notes

Purpose

Admin-only private notes about a student. Used for tracking special circumstances, support ticket references, communication history outside the app, family context, academic accommodations, or any context that helps admins manage the student's account. Notes are never visible to the student and are never visible to TAs.

Layout

Vertical feed of note cards, newest first. Each card shows:

• Note body (rich text or plain text with preserved line breaks)
• Author name and avatar
• Timestamp (creation date + last edited date if edited)
• Action menu (Edit / Delete) visible only on notes authored by the current user

Above the feed: "Add Note" button (prominent, top-right) + search/filter controls.

Data Displayed

Feed of admin_notes records (NEW table) filtered to this user_id and not soft-deleted, sorted by created_at descending.

Per-note fields:

Data model (NEW tables):

Search / Filter controls (above feed):

• Text search: free-text match against note body (case-insensitive)
• Author filter: dropdown of admins who have authored notes on this student; default "All authors"
• Date range filter: created-date range picker

Summary bar: "N notes | Last updated [date]" -- or "No notes" if feed is empty.

Actions

Edit/Delete constraints:

• An admin can edit or delete only notes they authored. A note's action menu is hidden entirely on notes authored by other admins.
• Deleted notes are soft-deleted — retained in admin_notes with deleted_at set, but not displayed in the feed. No UI to restore a deleted note in v2.

States

Role Visibility

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
• Semester Hub > End Checklist > Step 1 ("All Submissions Reviewed"): deep link to Submissions view filtered to this semester with assessment_status = 0 (pending); URL format ?from=end-checklist&semester=[id]&status=pending. When ?from=end-checklist is present, the screen shows a persistent "← Return to End Checklist for [Semester Name]" banner at top; clicking returns to the End Checklist tab with scroll position preserved.

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

Submissions Close Date control (page-level bar, above the table, visible to Admin only):

Caption text below: "Students cannot submit new recordings after this date. Default is computed from the semester end date but can be overridden."

Student Name search (filter bar): Free-text search input at top of filter bar. Matches against user_profile.first_name + last_name via student_submitted_assessment.owner_id. Case-insensitive, partial match. Placeholder: "Search by student name..."

Filters: Semester (dropdown), Level (dropdown), Status (dropdown: Under Review / Reviewed / Rejected / Late Response / All), TA (dropdown: filters to submissions from students assigned to selected TA), Gender (dropdown: Male / Female / All)

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."
• Submissions view empty (filtered by student name): "No submissions match "[query]"." + "Clear search" link
• Late Response filter active: Submissions view filtered to only late-response entries. Empty sub-state: "No late-response submissions. All under-review submissions are within the 48 working-hour window."
• 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/reassign/delete submissions), Submissions Close Date control visible
• TA: Submissions view only, filtered to their assigned students. Can review submissions (set grade, approve/reject). Cannot create/edit/delete assessments, cannot reassign. Cannot access Assessments view. Submissions Close Date control hidden.
• View-Only: Read-only on both views, no action buttons. Submissions Close Date control visible as read-only.

5. Screen: Promoted Students

5.1 Purpose

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

5.2 Entry Points

• Sidebar: Student Management > Promoted Students
• Semester Hub > End Checklist > Step 2 (Pass/Fail): after passing students are marked, their promotions surface here. Admins can review the resulting promoted-student list filtered to the closing 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 End Checklist Step 2 (Pass/Fail) has been completed for this semester)
• 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 (including Activate Account)
• 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.