Admin Spec — Semester Management

Semester Management

Domain 3 of the Enhanced Candidate A navigation structure. Contains: Semesters list + Semester Hub Page (4 tabs: Overview, Setup Checklist, Enrollment, Close Workflow), Welcome Package, Email Management, Tags, Operations. Primary workflows served: WF1 (Semester Setup), WF3 (Semester Close)

1. Domain Overview

Semester Management groups everything related to the lifecycle of a semester -- from initial setup through active management to close. Moving Welcome Package, Email Management, Tags, and Operations here from the former Settings section puts them where they logically belong: these are all semester-scoped configuration items.

Key design decisions:

• Semester Hub Page is the centerpiece -- a multi-tab entity page consolidating all semester configuration, enrollment visibility, and close workflow into one place
• Setup Checklist is a borrowed workflow concept (from WS1.3) that tracks completion without enforcing sequence -- the admin can configure items in any order
• Close Workflow is a borrowed workflow concept with GATED steps -- payment setup cannot proceed until promotions are finalized (directly addresses WS2 billing pain point)
• Tags moved here because tags are created per semester (semester-scoped)
• Operations moved here because bulk actions (promotions, registrations) are semester events; absorbs Level 0 promotion from dissolved Students Management grab-bag

Sidebar items:

Semester Management
  Semesters                     <- from top-level
    [Semester Hub Page] (NEW -- rich multi-tab semester view)
      [Tab: Overview]
      [Tab: Setup Checklist] (NEW)
      [Tab: Enrollment] (NEW)
      [Tab: Close Workflow] (NEW)
  Welcome Package               <- from Settings
  Email Management              <- from Settings
  Tags                          <- from Settings
  Operations (bulk actions)     <- from Settings (absorbs Level 0 promotion)

Data tables referenced: semester, user_link_level_tag, lessonsnew, assessment, resources, live_sessions, recordings, tutorials, mcqquestion, quiz, level_tag, users, user_profile, emails, tags, subscriptions, group_members, group_name

Workarounds Eliminated

2. Screen: Semesters List

2.1 Purpose

View all semesters with their status. Entry point to Semester Hub pages.

2.2 Entry Points

• Sidebar: Semester Management > Semesters
• Dashboard: phase prompt click

2.3 Layout

Data table (small dataset, no pagination needed). Uses standard Data Table pattern from 01-global-patterns.md Section 4.1. No filter bar (typically <10 semesters).

2.4 Data Displayed

2.5 Actions

2.6 States

2.7 Role Visibility

• Admin: Full view + Create/Delete actions
• View-Only: View table only (no Create or Delete buttons)
• TA / Support Staff: Hidden (sidebar item not visible, per 01-global-patterns.md Section 3.2)

3. Screen: Semester Hub Page (Rich Entity Page)

3.1 Purpose

Single consolidated view of everything about a semester: configuration, content setup status, enrolled students, and close workflow. This is the second most complex entity page in the system (after Student Detail Page with 6 tabs). Directly addresses WF1 (19+ screens --> 8-10) and WF3 (8+ screens --> 4-6).

3.2 Entry Points

• Semesters list: row click
• Dashboard: phase prompt link (e.g., "Spring 2026 -- Setup Phase" click)
• Global search: semester result click (01-global-patterns.md Section 2.3)
• Student Detail > Semester History tab: semester name click (03-student-management.md)
• Setup Checklist deep link return ("Return to Checklist" affordance from content screens -- see Section 3.6)

3.3 Entity Header

Persistent header visible across all tabs (follows Entity Page pattern from 01-global-patterns.md Section 4.11):

Breadcrumb: Semester Management > Semesters > [Semester Name]

3.4 Tab Structure

Tab behavior follows 01-global-patterns.md Section 4.11: lazy-load on first activation, state preserved when switching, URL updates with tab name (e.g., /semesters/123#setup-checklist), sticky tab bar on scroll.

3.5 Tab: Overview

Data Displayed

Dates section (card layout with inline documentation -- info icon tooltips on each field, per 01-global-patterns.md Section 6.1):

Status Controls section (toggle switches with inline documentation):

Automation section (NEW -- read-only summary cards):

Actions

States

3.6 Tab: Setup Checklist (NEW)

Borrowed from Workflow framework (WS1.3): tracks completion without enforcing sequence. The admin can configure items in any order. Enhanced with Candidate C elements: deep links to content screens with semester pre-filtered, inline content previews, and "return to checklist" affordance.

Layout

Grouped checklist with overall progress bar at top. Each group is a collapsible section. Each item shows status, count, and action link.

Overall Progress

Top of tab: progress summary card.

Checklist Structure

Items grouped by content type. Within each group, one item per level (where applicable) or one aggregate item (where content is not level-scoped).

Group: Video Lessons

Group: Assessments (Submissions)

Group: Resources

Group: Live Sessions

Group: Recordings

Group: Tutorials

Group: Quizzes

Group: MCQ Questions

Group: Configuration

Inline Content Preview (from Candidate C)

Each item with "Configured" status includes an expandable preview:

• Collapsed (default): Shows status badge + count only (e.g., "12 videos")
• Expanded (click to expand): Shows the first 3 items inline without navigating away:
  • Video Lessons: thumbnail + title for the first 3 videos
  • Resources: file icon + title for the first 3 resources
  • Assessments: prompt title for the first 3 assessment prompts
  • Email Templates: template name + trigger for the first 3 templates
  • Other content types: title/name for the first 3 items
• "View all X items -->" link at bottom of expanded preview: navigates to the full content screen with semester pre-filtered (same as "Configure -->" link)

"Return to Checklist" Affordance (from Candidate C)

When navigating from a checklist deep link to a content screen:

Actions

States

3.7 Tab: Enrollment (NEW)

Purpose

View and manage all students enrolled in this semester. Provides at-a-glance enrollment visibility without navigating to Student Management.

Data Displayed

Summary bar (horizontal bar above table): "X students enrolled | Y in Level 0 | Z in Level 1 | ... | W in Year 2"

Source: counts from user_link_level_tag grouped by level_tag_id where semester_id = this semester.

Filter bar (standard pattern from 01-global-patterns.md Section 4.2):

Data table:

Pagination: Standard pagination (01-global-patterns.md Section 4.1): 25 records per page.

Actions

States

3.8 Tab: Close Workflow (NEW)

Gated workflow -- each step must complete before the next unlocks. Directly addresses the semester close pain point where payments were set up before promotions were finalized (WS2 billing discovery finding). Reduces WF3 from 8+ screens / 40-70 clicks / 3 external tools to 4-6 screens / 15-25 clicks / 0 external tools.

Layout

Vertical stepper with 5 steps. Each step is a collapsible section:

• Completed steps: green checkmark icon, collapsed with summary visible, expandable to review
• Current step: expanded with full content, blue active indicator
• Locked steps: lock icon, collapsed, gray text, not expandable until prerequisite met
• Step numbers shown in circles (1-5) connected by a vertical line

Inline Documentation Block (01-global-patterns.md Section 6.3)

Collapsible "How does this work?" block at top of tab:

"This workflow guides you through end-of-semester tasks in order. Each step must be completed before the next becomes available. Steps 3 and 4 can run in parallel after Step 2 is complete. You can override gates if needed by clicking the lock icon on a locked step."

Step 1: Review EOC Assessments

Prerequisite: None (always available when Close Workflow tab is accessed) Purpose: Review end-of-course assessment results for all students and determine pass/fail.

Data table:

Filter bar:

Actions:

Completion criteria: All enrolled students have an EOC result of Pass, Fail, or Override. No "Pending" results remain.

Gate: Step 2 unlocked when Step 1 marked complete.

Step 2: Confirm Promotions

Prerequisite: Step 1 complete Purpose: Confirm which passed students will continue to the next semester and assign their next level.

Data table (shows only students who passed in Step 1):

Filter bar:

Actions:

Completion criteria: All passed students have a Continuing or Leaving decision. No "Pending" decisions remain.

Gate: Step 3 AND Step 4 unlocked when Step 2 marked complete. This is the promotion gate from WS2 -- billing cannot proceed until promotions are finalized. This directly prevents the current pain point where payments are set up before promotion decisions are finalized.

Step 3: Bulk Payment Setup

Prerequisite: Step 2 complete (promotions finalized) Purpose: Create or renew Stripe subscriptions for continuing students. Gated behind Step 2 to prevent the current pain point of setting up payments before knowing who is continuing.

Data table (shows only students marked as Continuing in Step 2):

Actions:

Completion criteria: All continuing students have an active or scheduled subscription, or are marked as "Skipped" with a reason.

Step 4: Handle Leavers

Prerequisite: Step 2 complete (can run in parallel with Step 3) Purpose: Deactivate accounts and cancel subscriptions for non-continuing students.

Data table (shows only students marked as Leaving in Step 2):

Actions:

Completion criteria: All leaving students are deactivated and have subscriptions cancelled (or are marked as "Already Handled").

Step 5: Verify

Prerequisite: Steps 3 AND 4 complete Purpose: Summary dashboard confirming all semester close tasks are complete. Final checkpoint before marking the semester as closed.

Summary display (read-only dashboard):

Exception Details (expandable section, shown only if exceptions > 0):

Actions:

Completion: Semester status updated. Close Workflow tab shows "Completed on [date]" summary header. All steps shown in read-only mode with green checkmarks.

Gate Override

For exceptional situations where the admin needs to bypass the normal gating sequence:

Close Workflow States

4. Screen: Welcome Package

4.1 Purpose

Manage resources included in the new student welcome package for each semester. These are files (PDFs, documents, media) sent or made available to students upon enrollment. Relocated from Settings to Semester Management because welcome packages are semester-scoped.

Transition hint (01-global-patterns.md Section 6.4): "Formerly under Settings" -- shown for first 30 days after launch.

4.2 Entry Points

• Sidebar: Semester Management > Welcome Package
• Semester Hub > Setup Checklist: "Configure -->" link (with ?from=checklist&semester=[id] for return affordance)

4.3 Layout

Semester selector (dropdown at top, defaults to current/active semester) + resource list with upload capability. Uses standard Data Table pattern for the resource list.

4.4 Data Displayed

4.5 Actions

4.6 States

4.7 Role Visibility

• Admin: Full CRUD (Upload, Edit, Delete, Reorder, Clone)
• View-Only: View list + Preview/Download. No Upload, Edit, Delete, Reorder, or Clone buttons.
• TA / Support Staff: Hidden (sidebar item not visible)

5. Screen: Email Management

5.1 Purpose

Configure automated email templates for the semester. Templates define both content and trigger conditions for automated student communications (welcome emails, reminders, promotion notifications, etc.). Relocated from Settings.

Transition hint: "Formerly under Settings" -- shown for first 30 days.

5.2 Entry Points

• Sidebar: Semester Management > Email Management
• Semester Hub > Setup Checklist: "Configure -->" link (with return affordance)
• Semester Hub > Overview: "View All Emails" link in Automation section

5.3 Layout

Semester selector (dropdown at top, defaults to current/active semester) + email template list. Uses standard Data Table pattern (01-global-patterns.md Section 4.1).

5.4 Data Displayed

5.5 Actions

5.6 States

5.7 Role Visibility

• Admin: Full CRUD (Create, Edit, Delete, Preview, Test Send, Clone)
• View-Only: View list + Preview only. No Create, Edit, Delete, Test Send, or Clone buttons.
• TA / Support Staff: Hidden (sidebar item not visible)

6. Screen: Tags

6.1 Purpose

Create and manage tags for user segmentation. Tags are semester-scoped and sync bidirectionally with InfusionSoft (CRM). Used for marketing segmentation, student categorization, and automated workflow triggers. Relocated from Settings.

Transition hint: "Formerly under Settings" -- shown for first 30 days.

6.2 Entry Points

• Sidebar: Semester Management > Tags
• Semester Hub > Setup Checklist: "Configure -->" link (with return affordance)

6.3 Layout

Semester selector (dropdown at top, defaults to current/active semester) + tags list. Uses standard Data Table pattern. No filter bar needed (typically <30 tags per semester).

6.4 Data Displayed

6.5 Actions

6.6 States

6.7 Role Visibility

• Admin: Full CRUD (Create, Edit, Delete, Retry Sync)
• View-Only: View list only. No Create, Edit, Delete, or Retry buttons.
• TA / Support Staff: Hidden (sidebar item not visible)

7. Screen: Operations (Bulk Actions)

7.1 Purpose

Perform bulk data operations that are semester-scoped. Provides a centralized place for high-volume administrative actions that would be tedious to perform one-by-one. Relocated from Settings. Now also includes Level 0 promotion (absorbed from dissolved Students Management screen #14 -- see 00-spec-index.md Section 4, Dissolved Screen #14 Redistribution).

Transition hint: "Formerly under Settings" -- shown for first 30 days.

7.2 Entry Points

• Sidebar: Semester Management > Operations

7.3 Layout

Action cards -- each bulk operation is a card with icon, title, description, and action button. Cards arranged in a responsive grid (2 columns on desktop, 1 on narrow screens). No data table -- this is a launcher page.

7.4 Available Operations

Card 1: Bulk Year 1 --> Year 2 Promotion

Card 2: Bulk User Registration

Card 3: Upload Backend Resources

Card 4: Data Migration

Card 5: Level 0 Promotion (NEW -- from dissolved #14)

7.5 States

7.6 Role Visibility

• Admin: All operation cards visible and actionable
• View-Only / TA / Support Staff: Hidden (sidebar item not visible -- bulk operations are admin-only)

8. Cross-Domain Integration Points

This section documents how Semester Management connects to other domains. Each integration is specified in detail in the target domain's spec document; this section provides a summary for reference.

8.1 Dashboard (02-dashboard.md)

8.2 Student Detail Page (03-student-management.md)

8.3 Content Domain (05-content.md)

8.4 Scheduling Domain (06-scheduling.md)

8.5 Teacher Management Domain (07-teacher-management.md)

8.6 Billing & Payments Domain (08-billing-payments.md)

9. Assumptions and Open Questions

This domain relies on several assumptions documented in 00-spec-index.md. Summary of semester-management-specific assumptions:

New questions raised by this spec (to be logged in 00-spec-index.md if not already covered):

• SQ1: How many checklist items per semester are typically applicable? If many items are consistently N/A, consider configurable templates per semester type. Assumed: all items applicable by default.
• SQ2: Should the Close Workflow allow partial re-opening after completion (e.g., to handle a late-arriving student)? Assumed: no -- once complete, the workflow is locked. Individual student adjustments can be made via Student Detail Page.
• SQ3: Should the auto-transition feature (Overview tab) support registration auto-close in addition to semester activation/deactivation? Assumed: no -- registration close is a separate manual decision.
• SQ4: How should the Setup Checklist handle content that spans multiple levels (e.g., a resource available to all levels)? Assumed: content appears under each applicable level item (may result in some double-counting in progress, but avoids missing items).
• SQ5: Should the Close Workflow Step 1 "Meets Criteria" computation be configurable (e.g., different thresholds per level or semester)? Assumed: fixed at submissions >= 12 AND grade >= 3.5 per current business rules. Configuration would add complexity.