Requirements & Use Cases
SHS Digital Wellness Passport — CSUB Student Health Services (DxHub 2026)
Companion to architecture-plan.md. This is an initial set — a working draft to confirm with SHS
(Erika, Lauren) and ITS (Brian, Ydalia). Each requirement has a stable ID for traceability; each
use case maps back to the requirements it satisfies.
Priority: M = MVP / must-have for the camp demo · S = should-have · C = could-have / stretch.
1. Actors
| Actor |
Description |
| Student |
CSU student who opts into a wellness challenge; primary end user. |
| SHS Staff (Admin) |
Health Services staff who author challenges, run events, and report. Erika (Director), Lauren (Health Ed Coordinator). |
| Event Attendant |
Staff/volunteer stationed at an event who displays/scans QR codes (may be the same person as Admin). |
| Campus IdP |
SAML identity provider that authenticates users and asserts current-student attributes. |
| AI Wellness Guide |
System actor: Claude-backed assistant for education, conversation, and scoring. |
| Reporting Consumer |
SHS leadership / CSU stakeholders who read participation & outcome reports. |
2. Functional Requirements
2.1 Identity & Access (FR-A)
| ID |
Requirement |
Pri |
| FR-A1 |
Users authenticate via campus SAML SSO; no manual ID/9-digit entry. |
M |
| FR-A2 |
System stores only an opaque SSO subject + affiliation attributes (no PHI, no password). |
M |
| FR-A3 |
Participation may be gated on current-student attributes from the SAML assertion. |
S |
| FR-A4 |
Admin access is role-restricted (student role cannot reach builder/reports). |
M |
| FR-A5 |
Every record is scoped by campus_id to support multi-campus (CSU-wide) deployment. |
S |
2.2 Challenge Authoring (FR-B) — Admin
| ID |
Requirement |
Pri |
| FR-B1 |
Admin creates a challenge with name, semester, start/end, and an ordered list of weekly tasks. |
M |
| FR-B2 |
Each task has: title, caption, activity type, location, date window, prize, required flag. |
M |
| FR-B3 |
Admin attaches assessment items (MCQ and/or reflection) to a task, each tagged to a learning outcome. |
S |
| FR-B4 |
Admin selects/edits a theme (palette, logo, hero art, copy tone) applied to the student app. |
S |
| FR-B5 |
(Retired by PASS-379.) Admin could AI-import a source document (Word/PDF) to auto-draft weeks, tasks, captions, and quiz items for editing. Retired so the deployed application holds no AI vendor SDK and makes no model call of any kind; staff-authored challenges (ChallengeBuilder.tsx) are the only way a challenge is created. |
S |
| FR-B6 |
Admin can duplicate a prior challenge as a starting point. |
C |
| FR-B7 |
Staff review every proposed notification and explicitly send, edit, or skip it before it reaches a student; staff can also compose a broadcast (title, body, audience, send-now or schedule-for) from scratch. Gated by Challenge.notifications_enabled and the global push kill switch; every decision is audited. |
S |
2.3 Enrollment & Passport (FR-C) — Student
| ID |
Requirement |
Pri |
| FR-C1 |
Student enrolls in the active challenge for their campus. |
M |
| FR-C2 |
Student views all weeks/tasks with status (locked / available / complete / missed). |
M |
| FR-C3 |
Student sees a progress countdown ("3 of 7 complete, 4 remaining"). |
M |
| FR-C4 |
App is mobile-first / installable (PWA) and usable offline for viewing progress. |
M |
| FR-C5 |
Student sees prize eligibility status derived from required-task completion. |
S |
| FR-C6 |
A week's status is gated by its own date window, not by completion of earlier weeks: a missed week stays open for catch-up instead of locking, and a week whose window hasn't opened yet stays locked. |
M |
| FR-C7 |
Student can register a device for push reminders (Web Push subscription storage) and choose per-category opt-in preferences, gated by a global kill switch so the feature can ship dark. The send path honors the app-level preference independently of the browser permission. |
S |
| FR-C8 |
A scheduled worker proposes draft reminders from challenge/task data (new-week, expiring) and dispatches whatever staff moved to scheduled, fanning out over each student's registered devices filtered by category preference, exactly once per device. |
S |
2.4 Check-In (FR-D)
| ID |
Requirement |
Pri |
| FR-D1 |
Student marks a task complete by scanning an event QR in-app. |
M |
| FR-D2 |
Backend validates the scan (task active, student eligible, not duplicate) before recording. |
M |
| FR-D3 |
Alternative: Event Attendant scans the student's passport QR for higher-assurance events. |
S |
| FR-D4 |
Each check-in records student, task, timestamp, and method (event_qr / staff / manual). |
M |
| FR-D5 |
Production: event QR is a signed, short-lived rotating token to prevent off-site sharing. |
C |
| FR-D6 |
Admin can manually add/override a completion with an audit trail. |
S |
| FR-D7 |
A student's own check-in requires scanning the live event QR — no self-service completion path. |
M |
2.5 AI Education, Guide & Assessment (FR-E)
| ID |
Requirement |
Pri |
| FR-E1 |
On check-in, the student receives a personalized tip/resource grounded in SHS content. |
M |
| FR-E2 |
Student can converse with a themed wellness guide grounded in SHS content. Ships flag-disabled for the pilot (PASS-378, PATH B) — the guide answers from a static corpus, never a model, so this was a product decision, not a data-processing one. |
M |
| FR-E3 |
Guide has guardrails: educational only, no diagnosis, crisis routing to real resources. Crisis resources stay reachable regardless of FR-E2's pilot flag (PASS-378). |
M |
| FR-E4 |
MCQ knowledge checks are auto-scored instantly; an admin may correct a score by hand should the answer key prove wrong (narrowed from FR-E5 by PASS-378). |
S |
| FR-E5 |
(Retired by PASS-378.) Free-text reflections are no longer AI-scored — reflections are stored and staff review them read-only ("mark reviewed"), never scored. The human-override mechanism this requirement introduced survives, narrowed to MCQ responses under FR-E4. See FR-E6. |
S |
| FR-E6 |
No student-authored text reaches a third-party model (strengthened by PASS-378 — see docs/retire-student-ai-model-paths-plan.md). Model calls that do occur are server-side and staff-facing only (challenge import); no PHI sent; conversations minimally logged. The same no-FERPA-scoped-egress rule covers the Web Push path (US-73): a push payload leaves the cluster to a browser vendor's push service, so an automatically-proposed notification carries no student name, campus, challenge name, or task detail. |
M |
2.6 Reporting (FR-F) — Admin
| ID |
Requirement |
Pri |
| FR-F1 |
Report on participation and per-week completion funnel. |
M |
| FR-F2 |
Report auto-captured vs. manual attendance counts. |
S |
| FR-F3 |
Report engagement (content views, guide usage). |
S |
| FR-F4 |
Report aggregated learning-outcome scores by outcome tag. |
S |
| FR-F5 |
Export prize-eligible students (CSV) for the drawing. |
M |
| FR-F6 |
Reports are aggregated/privacy-aware; optionally surfaced in QuickSight. |
C |
| FR-F7 |
Report data is exportable as CSV at per-student, per-event, and aggregate grain — not only the prize list. |
M |
3. Non-Functional Requirements
| ID |
Requirement |
| NFR-1 |
Privacy: no PHI; FERPA-aware handling of participation records; minimal identity. |
| NFR-2 |
Security: SAML SSO, role-based access, encryption at rest (S3/RDS) and in transit (TLS). |
| NFR-3 |
Supportability: production stack is C# / ASP.NET Core + Microsoft SQL Server for CSU teams. |
| NFR-4 |
Portability / multi-tenant: single codebase deploys per CSU campus via campus↔IdP mapping. |
| NFR-5 |
Usability: mobile-first, low-friction; QR scan-to-complete in a few taps. |
| NFR-6 |
Themeability: semester re-skin is a config change, not a code change. |
| NFR-7 |
Availability/scale: handle event-time bursts for ~hundreds of concurrent students; low steady load. |
| NFR-8 |
AI safety: grounded responses, refusal on out-of-scope, hard-coded crisis escalation. |
| NFR-9 |
Standalone: no dependency on the EHR ("Point and Click"); no external clinical integration. |
| NFR-10 |
Observability: check-ins, scores, and errors are logged for reporting and audit. |
4. Use Cases
UC-1 — Student authenticates and enrolls
- Actor: Student · Pri: M · Satisfies: FR-A1, FR-A2, FR-A3, FR-C1
- Precondition: An active challenge exists for the student's campus.
- Main flow:
- Student opens the PWA and taps "Sign in with campus SSO."
- System redirects to the campus IdP; student authenticates.
- IdP returns an assertion with subject + current-student attributes.
- System provisions/loads the student record (SSO subject only) and confirms eligibility.
- Student taps "Join the [Theme] Challenge"; enrollment is created.
- Alt / exceptions: Not a current student → enrollment blocked with a friendly message (FR-A3).
First-time login → student record created on the fly.
UC-2 — Student views passport & progress
- Actor: Student · Pri: M · Satisfies: FR-C2, FR-C3, FR-C4, FR-C5, FR-C6
- Main flow: Student opens passport → sees themed week tiles with status, a progress countdown,
and prize-eligibility indicator. Available weeks are highlighted; future weeks are locked.
- Alt: Offline → last-synced progress is shown from cache (FR-C4).
UC-3 — Student checks in at an event via QR (core loop)
- Actor: Student, Event Attendant · Pri: M · Satisfies: FR-D1, FR-D2, FR-D4, FR-D7, FR-E1
- Precondition: Student authenticated & enrolled; the task's event is active.
- Main flow:
- Attendant displays the event QR (per-event code; rotating token in production).
- Student taps "Scan" → app opens camera → captures the QR.
- App posts
{token, student, task} to the API.
- API validates: task active, student eligible, no duplicate check-in.
- API records the check-in; the week flips to complete and the countdown updates.
- Student is shown a personalized tip/resource for that task (UC-6).
- Alt / exceptions:
- Duplicate scan → "Already completed this week" (no double count).
- Expired/invalid token → "This code is no longer valid, ask the attendant" (FR-D5).
- Wrong week/date window → rejected with reason (FR-D2).
UC-4 — Staff verifies a student directly (high-assurance option)
- Actor: Event Attendant · Pri: S · Satisfies: FR-D3, FR-D4
- Main flow: Attendant opens staff mode → scans the student's personal passport QR → confirms
the task → check-in recorded with
method = staff.
UC-5 — Admin builds/edits a challenge
- Actor: SHS Staff (Admin) · Pri: M · Satisfies: FR-B1, FR-B2, FR-B3, FR-B4
- Main flow: Admin creates a challenge, adds ordered weekly tasks (title, caption, dates,
location, prize, required flag), attaches assessment items with outcome tags, and selects a theme.
- Alt: Duplicate a prior challenge as a template (FR-B6).
UC-6 — Student receives personalized health education
- Actor: Student · Pri: M · Satisfies: FR-E1, FR-E6
- Trigger: A successful check-in (UC-3), or opening a week.
- Main flow: System requests a tailored tip from the guide (personalized by task, progress, and
interests), grounded in SHS content, and displays it with a resource/short video and next step.
(Post-check-in tips are SHS-authored template text, not model output — the "AI Wellness Guide"
actor this use case listed pre-PASS-378 was never accurate for this flow.)
UC-7 — Student consults the wellness guide (flag-disabled for the pilot — PASS-378)
- Actor: Student · Pri: M · Satisfies: FR-E2, FR-E3, FR-E6
- Main flow: Student opens the themed guide chat and asks a wellness question; the guide answers
from SHS-grounded content, nudges the next task, and links campus resources. The guide has never
called a model — it answers by quoting a static, clinician-cleared excerpt table
(
services/guide_corpus.py) — so "AI Wellness Guide" never described this use case's actual
implementation; PASS-378 corrects the label and additionally ships the whole flow
flag-disabled (WP_GUIDE_ENABLED) for the pilot, a product decision independent of that
correction.
- Alt / exceptions:
- Out-of-scope / medical-advice request → guide declines and redirects to SHS/clinician (FR-E3).
- Crisis signal detected → guide immediately surfaces crisis resources (988/campus counseling)
and SHS contact (FR-E3, NFR-8).
- Guide flag off (pilot default) → chat is unreachable (404); the crisis-resources affordance
(
GET /api/guide/crisis-resources) stays available regardless (FR-E3, PASS-378).
UC-8 — Student completes an assessment (knowledge check / reflection)
- Actor: Student · Pri: S · Satisfies: FR-E4, FR-E6
- Main flow: Student answers MCQs (auto-scored, FR-E4) and/or writes a reflection. A reflection
is stored, never scored (PASS-378 / FR-E6 retired the auto-scoring FR-E5 originally specified —
no student-authored reflection text reaches a model). Scores are stored against the
learning-outcome tag; unscored reflections are excluded from that aggregate.
- Alt: Staff review a reflection read-only and mark it reviewed (no score control, FR-E6); an
admin may correct an MCQ score by hand (
scored_by = human, FR-E4).
UC-9 — Admin AI-imports a challenge from a document (retired by PASS-379)
- Actor: SHS Staff (Admin), AI Wellness Guide · Pri: S · Satisfies: FR-B5 (retired)
- Main flow. (Historical.) Admin uploaded the challenge Word/PDF (e.g.
Stranger Things Challenge.docx); the AI drafted structured weeks, tasks, date windows,
prizes, themed captions, and starter quiz items; admin reviewed and edited before publishing.
Retired by PASS-379 — a sleeper feature never adopted by real staff, retired rather than
reimplemented over raw HTTP once it became the last application-code consumer of the
anthropic SDK. Staff author challenges by hand (ChallengeBuilder.tsx) instead.
UC-10 — Admin runs reports & exports prize list
- Actor: SHS Staff (Admin), Reporting Consumer · Pri: M · Satisfies: FR-F1, FR-F2, FR-F3, FR-F4, FR-F5, FR-F7
- Main flow: Admin opens the dashboard → views participation, per-week completion funnel,
attendance auto-vs-manual, engagement, and learning-outcome aggregates → exports prize-eligible
students to CSV for the drawing.
UC-11 — Admin manages a live event
- Actor: SHS Staff (Admin), Event Attendant · Pri: S · Satisfies: FR-D4, FR-D6
- Main flow: Admin generates the event QR, watches real-time check-in counts, and manually
adds/overrides completions with an audit trail where needed.
UC-12 — Deploy to another CSU campus (stretch)
- Actor: ITS · Pri: C · Satisfies: FR-A5, NFR-4
- Main flow: ITS registers the campus IdP (SAML), sets
campus_id mapping, and deploys the same
codebase; the campus authors its own challenges with no code change.
UC-21 — Student registers a device for push reminders
- Actor: Student, SHS Staff (Admin), Ops Engineer · Pri: S · Satisfies: FR-C7, FR-C8, FR-B7
- Precondition: Push notifications are enabled for the deployment (
WP_PUSH_ENABLED); the
student is signed in.
- Main flow: The PWA asks the browser for a Web Push subscription (endpoint + keys) and posts it
to the API, which stores it against the student's own id — the same device re-registering updates
the stored row rather than duplicating it. Separately, on its own ~15-minute k8s CronJob cadence, a
scheduled worker proposes draft reminders from challenge/task data (a week opening, a challenge
ending soon). Nothing reaches a student from a proposal alone: an admin works a queue of
draft
rows and explicitly sends (scheduled), edits the copy before sending, or skips each one — or
composes a broadcast from scratch, targeting the whole challenge or only students with an
incomplete current week. Dispatch then fans a scheduled row out over every opted-in enrolled
device exactly once.
- Alt / exceptions: Push disabled by configuration → the request is refused and nothing is
stored (the feature ships dark); the same kill switch also stops dispatch from sending. A single
challenge can also be muted via
Challenge.notifications_enabled, independent of the global
switch. A student can only remove their own subscription, never another student's. A device the
push service reports gone (404/410) is deleted — the only garbage collection an uninstalled app
gets. A student calling the staff queue endpoints directly is rejected as unauthorized. Every send
decision is audited: who approved it, and when.
5. Traceability (use case → requirements)
| Use case |
Requirements |
| UC-1 Auth & enroll |
FR-A1, FR-A2, FR-A3, FR-C1 |
| UC-2 View passport |
FR-C2, FR-C3, FR-C4, FR-C5, FR-C6 |
| UC-3 QR check-in |
FR-D1, FR-D2, FR-D4, FR-D7, FR-E1 |
| UC-4 Staff verify |
FR-D3, FR-D4 |
| UC-5 Build challenge |
FR-B1, FR-B2, FR-B3, FR-B4 |
| UC-6 Personalized education |
FR-E1, FR-E6 |
| UC-7 Wellness guide |
FR-E2, FR-E3, FR-E6 |
| UC-8 Assessment |
FR-E4, FR-E6 |
| UC-9 AI doc import |
FR-B5 |
| UC-10 Reporting/export |
FR-F1–FR-F7 |
| UC-11 Live event |
FR-D4, FR-D6 |
| UC-12 Multi-campus |
FR-A5, NFR-4 |
| UC-21 Push notifications |
FR-C7, FR-C8, FR-B7 |
6. Out of scope (confirmed by discovery call)
- EHR / "Point and Click" integration — proprietary, non-integrating (NFR-9).
- Storing or processing any PHI / clinical results.
- Native iOS/Android apps (PWA covers the need).
- Payment/prize fulfillment logistics (system only determines eligibility).
7. Assumptions to confirm with SHS / ITS
- CSUB test IdP/SP available for the demo, or SAML mocked for Friday.
- Amazon Bedrock (Claude) enabled in the account/region on the landing zone.
- Which SHS wellness materials are cleared to ground the guide/tips (RAG corpus).
- Exact crisis-routing resources (988, campus counseling, SHS front desk).
- "Good faith" check-in is acceptable for MVP; rotating signed QR deferred to production.
- Prototype stack confirmed as .NET/SQL Server (recommended) vs. Python.