v2 Admin Spec — Teacher Management

Teacher Management

Domain 6 of the Enhanced Candidate A navigation structure. Contains: Teaching Assistants list + TA Detail Page (4 tabs), Teacher Assignment Criteria, TA Reports, Student Groups.

1. Domain Overview

Teacher Management groups everything related to TAs — profiles, schedules (managed in Scheduling domain but visible here), student assignments, and performance. Moving Teacher Assignment Criteria (from Settings) and TA Reports (from Reports) here puts them where they logically belong.

2. Screen: Teaching Assistants List

2.1 Purpose

View all TAs. Entry point to TA Detail Pages. Relocated from People > Teaching Assistants.

2.2 Entry Points

Sidebar: Teacher Management > Teaching Assistants
Dashboard: TA Response Time tile click (filtered to flagged TAs)

2.3 Data Displayed

Column	Source	Sortable
Name	`user_profile.first_name + last_name`	Yes
Email	`users.email`	Yes
Status	`users.user_activation_status`	Yes
Assigned Students	Count from group membership (scoped to selected semester)	Yes
Avg Response Time	Computed from submission review times	Yes
Live Sessions / Week (NEW)	Count of scheduled live sessions per week for this TA in the selected semester	Yes
Session Slots / Week (NEW)	Count of 1:1 appointment slots open per week for this TA in the selected semester	Yes
Groups	Count of groups assigned (scoped to selected semester)	Yes

Filters:

Status: Active / Inactive
Gender: Male / Female
Semester (NEW): dropdown of semesters; defaults to active semester. TA list is automatically copied to each new semester, so per-semester assignment counts differ per selection.

2.4 Actions

View TA (row click → TA Detail Page)
Create TA ("Create TA" button, Admin)
Edit / Delete (Admin)

2.5 States

Standard list. Empty: "No teaching assistants configured."

2.6 Role Visibility

Admin: Full. View-Only: View. TA/Support: Hidden.

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

3.1 Purpose

Consolidated TA view. 4 tabs: Profile, Schedule, Students & Groups, Performance.

3.2 Entry Points

TA list row click, Global search, Student Detail header TA name click, Dashboard TA alert

3.3 Entity Header

Field	Source
Name	`user_profile`
Email	`users.email`
Status	Badge (Active/Inactive)
Timezone	`users.timezone`
Student Count	Derived
Avg Response Time (NEW)	Computed

Breadcrumb: Teacher Management > Teaching Assistants > [TA Name]

3.4 Tab: Profile

Standard TA profile fields: name, email, timezone, status, contact info. Actions: Edit Profile (Admin only)

3.5 Tab: Schedule

Field	Source
Weekly availability grid	From TA Schedules data
Timezone	`users.timezone`
Personal Holidays	TA-specific holidays
Upcoming Appointments	Next 7 days of appointments

Actions:

Edit Availability → navigates to Scheduling > TA Schedules (pre-filtered to this TA)
View in Calendar → Scheduling > Calendar View (filtered to this TA)

3.6 Tab: Students & Groups (NEW)

Assigned Students table:

Column	Source
Student Name	via group_members → users
Level	enrollment level
Submissions	Count this semester
Pending Review	Submissions where assessment_status=0
Last Submission	Date

Groups table:

Column	Source
Group Name	`group_name.name`
Members	Count of `group_members`
Next Appointment	From `appointments`

Actions:

View Student (name click → Student Detail)
Reassign Student (Admin) — move to different TA
Create Group (Admin) — creates group assigned to this TA
Manage Group Members (Admin)

3.7 Tab: Performance (NEW)

Metric	Source	Display
Avg Response Time	Computed: avg(review_date - submission_date) for this TA	"2.1 days" — highlighted red if >2 days (48hrs)
Submissions Received (NEW)	Total count of submissions from this TA's assigned students this semester (includes reviewed + pending + rejected)	Number
Submissions Reviewed	Count of submissions with `assessment_status != 0` this semester (subset of Submissions Received)	Number
Reviews Total	All-time count of reviewed submissions	Number
Pending Reviews	Submissions under review assigned to this TA (`assessment_status = 0`)	Number (highlighted if >0)
Avg Grade Given (NEW)	Mean of numeric grades across reviewed submissions this semester	"82 / 100" (or equivalent scale)
Student Pass Rate	% of assigned students who passed in previous semester	"87%"
Student Fail Rate	Complement	"13%"

Disambiguation notes:

"Submissions Received" counts every submission that landed in this TA's queue this semester, regardless of review state.
"Submissions Reviewed" is a strict subset — those the TA has acted on (approved, rejected, or sent back).
"Pending Reviews" is complementary — Submissions Received minus Submissions Reviewed minus any withdrawn/deleted.

States:

Has data: metrics displayed
New TA: "No performance data yet. This TA has not reviewed any submissions."

3.8 Cross-Tab Behaviors

Reassigning student on Students tab updates student count in entity header
Review submission from Students tab updates Performance tab metrics

4. Screen: Teacher Assignment Criteria

4.1 Purpose

Configure how students are auto-assigned to TAs at enrollment. The primary surface is a per-TA matrix where each TA's capacity, level specialization, and new-vs-returning routing are edited in one row. A small set of named rules governs global behavior (gender match, repeat-student rotation, distribution strategy). A read-only preview panel shows the current config's distribution outcome for a sample enrollment count.

Relocated from Settings.

4.2 Entry Points

Sidebar: Teacher Management > Teacher Assignment Criteria
Semester Hub > Setup Checklist: "Configure assignment matrix →" link

4.3 Per-TA Matrix (PRIMARY SURFACE)

Each active TA has one row in the matrix for the selected semester. Inline editing via cell controls.

Column	Type	Source / Behavior
TA Name	Read-only	`user_profile.first_name + last_name` — click → TA Detail
Capacity	Number input	Max students this TA will take this semester. Required. Range: 0-200.
Level Specialization	Checkbox group	Checkboxes for Levels 0, 1, 2, 3, 4. Multi-select. Empty = accepts all levels.
Student Type Routing	Select	"New", "Returning", or "Both". Controls which student pool this TA is eligible for. Default: Both.
Active	Toggle	If off, TA is excluded from auto-assignment this semester (profile remains active in Teachers list).

Matrix actions:

Edit row inline (Admin) — capacity, level checkboxes, student-type, active toggle
Bulk edit (Admin) — select multiple TAs, apply capacity / level / type in batch
Reset row to defaults (Admin)

States:

Populated: one row per TA copied into this semester
Empty: "No TAs configured for this semester yet. TAs are copied automatically when a semester is created."

Validation:

Sum of capacities is displayed as a summary metric at the top of the matrix ("Total capacity: 847 students across 23 TAs").
Warning badge if total capacity < expected enrollment (surfaced from Semester Hub enrollment forecast if available).

4.4 Named Rules (SECONDARY SURFACE)

A small, fixed set of system-level rules sits above the matrix. Not a CRUD catalog — these are hard-coded rule names with per-rule controls.

4.4.1 Gender Match

Behavior: Automatic. Students are assigned only to TAs of the same gender.
Control: None — not toggleable. Displayed as an informational row: "Gender match: Automatic — students assigned only to TAs of matching gender."
Precedence: Applied as a hard filter before matrix constraints.

4.4.2 Repeat-Student Rotation

Policy source (Apr 22 transcript L125): "For repeat students, we will assign them to a different teacher, if at all possible. So that's like our policy and that kind of goes into like assignment criteria as well. That a student, if possible, is assigned to a different teacher for the upcoming semester."

When a student re-enrolls for a new semester, the system attempts to assign them to a TA they have not had previously. This rule is applied before matrix-based distribution.

Logic:

On enrollment, check group_members + group_name for this student's history of TA assignments (all prior user_link_level_tag records).
Filter the pool of eligible TAs to those who pass gender match + capacity + student-type routing constraints (matrix-phase eligibility).
From that eligible pool, exclude any TA the student has had in any prior semester.
If at least one TA remains: auto-assign to one of them (weighted by capacity via the Distribution Strategy).
If no alternative TA remains (all eligible TAs have been previous TAs for this student, or only the previous TA is eligible): fall back to the previous TA rather than leave the student unassigned.
If even the previous TA is unavailable (inactive, at capacity, gender-mismatched): fall through to standard matrix distribution with no rotation constraint.

Control: Single toggle at the top of the Named Rules panel: "Rotate repeat students to a different TA when possible" (default: on). Precedence: Evaluated after gender match, before matrix distribution. Note: Turning this toggle off does NOT revert to "assign to previous TA" — it simply disables the rotation preference, letting repeat students flow through normal matrix distribution with no history-based preference. (If matrix distribution happens to land a repeat student back on their previous TA with the toggle off, that is not a constraint violation — the rotation preference simply doesn't apply.)

4.4.3 Distribution Strategy

Selects how remaining students (those not placed by the repeat-student rule) are distributed across matrix-eligible TAs.

Option	Behavior
Weighted by Capacity (default)	Fill each eligible TA proportional to their capacity percentage. Example: a TA with capacity 10 takes 1 student when a TA with capacity 50 takes 5, matching a 20% fill rate across both. Deterministic — derived from capacity, not separately-tunable weights.
Round Robin	Rotate through eligible TAs one student at a time until capacities are met.
Manual	Auto-assignment is disabled; all students enter a manual placement queue.

Control: Radio-group selector in Named Rules panel. Precedence: Governs matrix-phase distribution only.

4.4.4 Dropped Rule — Timezone Proximity

The v1 Timezone Proximity rule is removed. Stakeholder rejected it during review. No replacement; if timezone constraints are needed in the future, the matrix schema or a new named rule would need to be reintroduced.

4.5 Preview Panel (READ-ONLY)

A read-only panel under the matrix shows the current configuration's distribution outcome for a sample enrollment count.

Layout:

Input: number-stepper "Sample enrollment: [N]" (defaults to current semester's enrollment count if available, else 100)
Output table:

TA	Capacity	Projected Assignments	Fill %
Alia Rahman	50	30	60%
Yusuf Khan	20	12	60%
Fatima Noor	10	6	60%
...	...	...	...
Total	847	N	—

Footnote: "Preview is based on current matrix + named rules. Does not include repeat-student rotation placements (applied before distribution)."
Warning line if N exceeds total capacity: "N students exceeds total capacity of 847. Some students would require manual placement."

Mockup note: Preview numbers are hardcoded in the mockup; no live algorithm computation. Production should run the actual weighted-fill algorithm.

4.6 Precedence Summary

Auto-assignment evaluation order (highest priority first):

Gender match — hard filter; excludes non-matching TAs from eligibility
Repeat-student rotation (if toggle on) — for repeat students, prefers a TA they have not had previously; falls back to previous TA only when no alternative is eligible (see §4.4.2)
Matrix constraints — filter eligible TAs by Level Specialization, Student Type Routing, Active, and remaining Capacity
Distribution Strategy — allocates remaining students across the filtered eligible TAs

4.7 Role Visibility

Admin: Full edit on matrix + named rules. View-Only: View only. TA: Hidden.

4.8 Open Questions (TBD)

Resolved 2026-04-21 per STAKEHOLDER-ANSWERS (defaults #2, #3 + Q8) — Weighted distribution is deterministic from TA capacity; conflict resolution surfaces a manual placement queue; Semester Hub entry point provides sufficient semester context (no explicit semester selector on Assignment Criteria screen).

Weighted distribution determinism: Is the Weighted by Capacity strategy strictly deterministic from capacity percentages (stakeholder's example implies yes), or should admins be able to tune per-TA weights independently of capacity? Default assumption: deterministic. Resolved 2026-04-21 — Deterministic from capacity confirmed per STAKEHOLDER-ANSWERS (default #2).
Conflict resolution: When no TA satisfies all hard constraints for a student (e.g., no female TA handles Level 3 for new students), what is the fallback? Options: (a) route to a manual placement queue, (b) relax lowest-priority matrix constraint (Level → Student Type → Capacity), (c) flag and block enrollment. Resolved 2026-04-21 — Option (a) manual placement queue confirmed per STAKEHOLDER-ANSWERS (default #3).
Semester binding: The matrix is scoped to a semester. Entry points today are sidebar + Semester Hub Setup Checklist. Is an explicit semester selector needed on the screen, or is the Semester Hub context sufficient? Resolved 2026-04-21 — Semester Hub entry point provides sufficient context; no explicit semester selector required per STAKEHOLDER-ANSWERS (Q8).

5. Screen: TA Reports

5.1 Purpose

Track TA performance and their students. Relocated from Reports.

5.2 Entry Points

Sidebar: Teacher Management > TA Reports

5.3 Existing Capabilities (preserved)

View TA performance and their students
Export TA data to CSV
Weekly submissions by teacher

5.4 Role Visibility

Admin: Full + export. View-Only: View only.

6. Screen: Student Groups

6.1 Purpose

Manage student groups and assignments. Previously accessible only via TA detail pages. Now surfaced to nav.

6.2 Entry Points

Sidebar: Teacher Management > Student Groups
TA Detail > Students & Groups tab: group name click

6.3 Data Displayed

Column	Source	Sortable
Group Name	`group_name.name`	Yes
TA	`users.name` via `group_name.teacher_id`	Yes
Members	Count of `group_members`	Yes
Semester	Derived from enrollment	Yes
Protected	`group_name.prevent_delete`	No

6.4 Existing Capabilities (preserved from StudentGroupController)

Create/edit groups
View group details
Add/transfer students between groups
Delete group (blocked if prevent_delete=1)

6.5 Role Visibility

Admin: Full CRUD. View-Only: View only. TA (via "My Groups"): own groups view-only.