v2 Admin Spec — Reporting
Reporting
Domain 8 of the Enhanced Candidate A navigation structure. Contains: Student Report, Referrals, Specific Reports, Student Composition (NEW), Active Semester Enrollment (NEW, v2), Revenue Breakdown (NEW, v2), Installment→One-Time Conversion (nice-to-have stub), Notification/Email Impact (nice-to-have stub), Logs.
v2 status (partially resolved 2026-04-22): This domain was Category E — Deferred as of Apr 15. The Apr 22 working session (see
STAKEHOLDER-ANSWERS-2026-04-22.md§A) locked in directional commitments: (1) two primary reports are additive this cycle (Active Semester Enrollment, Revenue Breakdown). (2) Two nice-to-have reports are specified as stubs (Installment→One-Time Conversion, Notification/Email Impact) — their layouts are deferred to a dedicated reporting working session still owed. (3) v1 reports (Student Report, Referrals, Specific Reports, Student Composition, Logs) are preserved unchanged. Full report catalog remains a pending working session item.
Global reporting conventions (Apr 22)
- Export format: CSV only. PDF and Excel are not required per Lejla (Apr 22 L63).
- Delivery: Live dashboards + on-demand CSV export. No scheduled email sends for reports. (Note: scheduled sends for Communication > Blast Emails and Automation Emails are unrelated and unaffected — those live in the Communication domain per ADR-003.)
- Analysis vs reporting: Per the Apr 22 session (Kamran L56, Lejla L59), reports deliver raw data; analysis is a separate downstream activity. New reports in this spec prioritize comprehensive slices over pre-computed analytics.
1. Domain Overview
Reporting consolidates all analytics and system logs. Most screens are relocated from the current Reports section. Logs moved here from Settings (system activity logs belong with analytics). TA Reports moved to Teacher Management domain. Payments report moved to Billing & Payments domain.
2. Screen: Student Report
2.1 Purpose
Track student performance metrics.
2.2 Entry Points
- Sidebar: Reporting > Student Report
- Dashboard: "Students Behind" tile click (pre-filtered)
2.3 Existing Capabilities (preserved)
- View student performance metrics
- Export selected students to CSV
- Export full student report
2.4 Key Changes
- Can now be accessed from Dashboard with pre-applied filters
- Row click → Student Detail Page (new navigation target)
2.5 Role Visibility
Admin: Full + export. View-Only: View + export.
3. Screen: Referrals
3.1 Purpose
Track referral program performance. Relocated from Reports.
3.2 Existing Capabilities (preserved)
- View referral data
3.3 Role Visibility
Admin: Full. View-Only: View only.
4. Screen: Specific Reports
4.1 Purpose
Run custom queries and edge-case reports. Relocated from Reports.
4.2 Existing Capabilities (preserved)
- Custom report generator
- Active students not in active semester
- Repeat students with email status
4.3 Role Visibility
Admin: Full. View-Only: View only.
5. Screen: Student Composition (NEW)
5.1 Purpose
Student body breakdown by type. Addresses interview need for "student body composition (new vs. repeat vs. graduating)."
5.2 Entry Points
- Sidebar: Reporting > Student Composition
5.3 Layout
Summary cards + detail table
5.4 Data Displayed
Summary cards:
| Card | Source | Format |
|---|---|---|
| Total Students | Count of active students (user_type=3, activation=1) | Number |
| New Students | Students in their first semester (one enrollment record) | Number + % |
| Returning Students | Students with 2+ enrollment records | Number + % |
| Graduating (Year 2 Complete) | Year 2 students with pass status | Number + % |
Detail table:
| Column | Source | Sortable |
|---|---|---|
| Level | level_tag.name | Yes |
| Total | Count per level | Yes |
| New | First-semester count per level | Yes |
| Returning | Multi-semester count per level | Yes |
| Retention Rate | Returning / (previous semester total at this level) | Yes |
Filters: Semester (default: current)
5.5 Actions
| Action | Trigger | Permission |
|---|---|---|
| Export | "Export" button | Admin |
| View Level Detail | Level click | All — expands to show student list for that level |
5.6 States
- Has data: Summary cards + table
- No data: "No enrollment data for [semester]."
5.7 Role Visibility
Admin: Full + export. View-Only: View only.
6. Screen: Active Semester Enrollment Report (NEW, v2)
6.1 Purpose
Single-surface view of every student enrolled in a chosen semester, with the slices Lejla needs for semester-health assessment (Apr 22 L47, L55): enrollment type × level × elective × gender × payment status. Complements Student Composition (§5): Composition is a summary of body breakdown by level; this report is the detail list and supports per-slice filtering. Primary entry-point for "show me who is signing up for the new semester" and "how many have graduated and moved to Year 2."
6.2 Entry Points
- Sidebar: Reporting > Active Semester Enrollment
- Dashboard: Enrollment-oriented tiles may deep-link here with pre-applied filters (future addition, not required in v1 of this screen)
6.3 Layout
Semester selector (dropdown at top) + filter bar + summary metric cards + data table.
6.4 Data Displayed
Summary cards (above the table, recomputed as filters change):
| Card | Source | Format |
|---|---|---|
| Total Enrolled | Count of user_link_level_tag for selected semester |
Number |
| New | Count where enrollment_type='New' |
Number + % |
| Returning | Sum of Continuing + Repeat + Year 2 | Number + % |
| Repeat | Count where enrollment_type='Repeat' |
Number + % |
| Year 2 | Count where enrollment_type='Year 2' |
Number + % |
Detail table:
| Column | Source | Sortable | Filterable |
|---|---|---|---|
| Name | user_profile.first_name + last_name |
Yes | Yes (search) |
users.email |
Yes | Yes (search) | |
| Level | level_tag.name via user_link_level_tag.level_tag_id |
Yes | Yes (dropdown: Level 0–4, Year 2) |
| Enrollment Type | user_link_level_tag.enrollment_type |
Yes | Yes (dropdown: Continuing / New / Repeat / Year 2) |
| Elective | user_link_level_tag.elective_id → elective name (Year 2 only; "—" otherwise) |
Yes | Yes (dropdown of electives) |
| Gender | user_profile.gender |
Yes | Yes (dropdown: Male/Female) |
| TA | Derived via group_members → group_name.teacher_id → users |
Yes | Yes (dropdown) |
| Semester Status | user_link_level_tag.user_semester_status |
Yes | Yes (dropdown: Enrolled / Pass / Fail) |
| Payment Status | Derived from Stripe subscription for this enrollment (subscriptions.status) |
Yes | Yes (dropdown: Active / Past Due / Cancelled / None / Scholarship / Family-Plan) |
| Final Status | user_link_level_tag.final_status |
Yes | Yes (dropdown: Pass / Fail / Mastery Passed / Not Set) |
Filter bar (applies to table AND to summary cards):
- Semester (required, defaults to active semester)
- Enrollment Type (multi-select dropdown)
- Level (multi-select)
- Elective (multi-select)
- Gender (single-select)
- Payment Status (multi-select)
- TA (multi-select)
6.5 Actions
| Action | Trigger | Permission | Behavior |
|---|---|---|---|
| Export CSV | "Export" button | Admin, View-Only | Downloads the current filtered view as CSV (one row per student). Filename: active-enrollment-[semester-slug]-[YYYY-MM-DD].csv. |
| View Student | Row click on Name | All roles | → Student Detail Page (Profile tab) |
| View TA | TA column click | All roles | → TA Detail Page |
| Apply Dashboard Preset | Arriving from Dashboard with query string | — | Filters pre-applied; "Clear Filters" link restores default. |
6.6 States
- Loaded with data: metric cards + filtered table
- Loaded, filtered empty: "No students match your filters." + "Clear filters" link
- No enrolled students for selected semester: "No enrollment for [Semester Name]."
- Loading: skeleton cards + skeleton table
- Error: standard error pattern
6.7 Role Visibility
- Admin: Full view + export
- View-Only: Full view + export
- Support Staff: Full view, no export
- TA: Filtered to their own assigned students only (via
group_members)
7. Screen: Revenue Breakdown Report (NEW, v2)
7.1 Purpose
Per-semester revenue snapshot sliced by pricing tier and payment cadence (Apr 22 L55). Answers Lejla's question: "what percentage of students and at what amount has signed up for repeat for family pricing" and "what the revenue stream is looking like… if all students remain and all four payments go through for the installment payment ones." A financial counterpart to the Active Semester Enrollment Report.
7.2 Entry Points
- Sidebar: Reporting > Revenue Breakdown
7.3 Layout
Semester selector (defaults to active semester) + metric tiles + pricing-tier breakdown table + projection panel.
7.4 Data Displayed
Top-line tiles:
| Tile | Computation |
|---|---|
| Collected So Far | Sum of payments.amount where status=succeeded and payment_date ≤ NOW and linked to this semester's subscriptions |
| Projected Total | Sum across all active subscriptions of (remaining installments × installment amount) + already-collected |
| Projected Shortfall | Projected Total − Stripe realized amount assuming no installment defaults (transparent math — see §7.7) |
| Active Student Count | Count of enrolled students with user_link_level_tag.user_semester_status = 1 |
Pricing-tier breakdown table:
| Column | Source |
|---|---|
| Pricing Tier | Derived: Full Tuition / Family Plan / Repeat-Discount (50%) / Scholarship (from student_scholarships) / Other Discount (from coupons) |
| Students | Count of subscriptions at this tier for the selected semester |
| % of Student Body | Students / Active Student Count |
| Installment Subs | Count where payment_plans.sub_type = 'Installment' |
| One-Time Subs | Count where payment_plans.sub_type = 'OneTime' |
| Realized Revenue | Sum of collected payments at this tier |
| Projected Revenue | Realized + (remaining installments × installment amount) |
Projection panel (lower section):
Shows two sub-scenarios, both computed from current subscription state:
- Best case (all installments complete, no cancellations): sums across all active subscriptions.
- Current trajectory (applies an admin-adjustable default failure rate — 0% initially): same sum minus an attrition factor.
Admin can toggle the attrition % slider (0–30%) to see sensitivity. The slider does not persist — it is a view-only exploration control.
7.5 Filter Bar
- Semester (required, defaults to active)
- Pricing Tier (multi-select)
- Payment Cadence (Installment / One-Time / All)
7.6 Actions
| Action | Trigger | Permission | Behavior |
|---|---|---|---|
| Export CSV | "Export" button | Admin only | Exports both top-line tiles and the pricing-tier breakdown as a single CSV with section separators. |
| Drill into Tier | Row click on pricing-tier row | Admin, View-Only | Opens the Payments screen (§3) pre-filtered to this pricing tier + semester. |
7.7 Math Transparency
Each tile has a ? info icon that expands to show the exact formula, so admin can reason about the number. Per the Apr 22 Kamran-Lejla exchange (L56): the report is base data; analysis is downstream.
7.8 States
- Has data: tiles + breakdown + projection
- No subscriptions for this semester: "No revenue data for [Semester Name]." + helper link to Payment Plans
- Loading / Error: standard patterns
7.9 Role Visibility
- Admin: Full view + export + drill-down
- View-Only: Full view + drill-down. No export.
- Support Staff / TA: Hidden (revenue figures are admin-restricted).
8. Screen: Installment → One-Time Conversion Report (NICE-TO-HAVE STUB)
8.1 Purpose
Measure uptake of the "convert to one-time payment for a discount" offer among prior-semester installment-paying students. Referenced Apr 22 L55. Not fully specified — placeholder until the reporting working session defines the full slicing.
8.2 Minimum required data (placeholder)
- Count of students who were on installment in the previous semester
- Count who were offered the one-time conversion
- Count who accepted
- Aggregate discount applied
- Revenue impact (net gain after discount)
8.3 Status
Stub. Do NOT build in the current v2 mockup phase. Create the route and a V2TodoPanel placeholder referencing this section. Full design in a future iteration.
9. Screen: Notification / Email Impact Report (NICE-TO-HAVE STUB)
9.1 Purpose
Measure whether notifications and emails correlate with desired student behavior (attendance at live classes, submission catch-up). Referenced Apr 22 L55. Intended as analytics support for Communication domain ROI, not a routing/operational screen.
9.2 Minimum required data (placeholder)
- Campaign (automation email template / push-notification batch / blast email)
- Recipients count
- Engagement measures over a window after send (live-class attendance delta, submission catch-up delta — definitions TBD)
9.3 Status
Stub. Do NOT build in the current v2 mockup phase. Create the route and a V2TodoPanel placeholder referencing this section. Full design in a future iteration.
10. Screen: Logs
10.1 Purpose
View system activity logs. Relocated from Settings.
10.2 Entry Points
- Sidebar: Reporting > Logs
v2 note: Communication Logs is a separate screen in the new Communication domain (per ADR-003). It tracks messaging activity (emails sent, notifications delivered, etc.). This Logs screen is distinct — it covers system activity logs (admin actions, data changes, login events, etc.) and remains in the Reporting domain.
10.3 Existing Capabilities (preserved)
- View system logs
10.4 Role Visibility
Admin only.