Student check-in request

# Student check-in request

A button on the student writing surface that lets a student raise their hand digitally — either in real time during class, or asynchronously from home. Teachers see a list of students who've requested a check-in, scoped to a course, so the next class period starts with a known list of who needs attention.

## Problem

Students working in Yawp have no native way to signal that they want their teacher's help. In class, they raise their hand or wait awkwardly. At home, they have no signal at all — they get stuck, push through, give up, or wait until the next class to ask, by which point momentum is lost and the question may not get asked.

Teachers, conversely, walk into class without a clear picture of who's stuck. They circulate the room and triage by reading shoulders, which scales poorly past 20 students and not at all for the homework half of the workflow.

A lightweight student-initiated check-in request would close both gaps with the same UI.

## Goals

- A student working on a Document can request a check-in from their teacher with one click.
- The request can include an optional short note ("stuck on the conclusion," "is my thesis okay?").
- Teachers see an aggregated list of pending check-in requests per course, so they can plan the next class around it.
- In-class real-time mode: requests show up immediately to the teacher (live indicator), so a teacher who's actively circulating can route to the student.
- Asynchronous mode: requests submitted outside class hours are queued for the next class session.
- A student can cancel their request if they figure it out on their own.

## Non-goals

- Not a chat product. The teacher doesn't reply in-app to the request — they go talk to the student.
- No AI handling of the request. This is explicitly a request for *human* help, not another AI feedback path.
- No notifications to the teacher's phone or email in v1. The teacher sees the queue when they open Yawp.
- No grading or evaluation of how often a student requests help.
- No public visibility — other students can't see who's requested check-ins.

## Domain notes

Entities involved:
- **Student** initiates the request.
- **Document** the request is scoped to (so the teacher knows which work prompted it).
- **Course** the Document belongs to (bounds the teacher who sees the request).
- **Assignment** (when the Document is tied to one) gives the teacher useful context — "Jordan needs help on the Macbeth essay."

A check-in request is its own lightweight entity — a student/document/course tuple plus state (pending, resolved, canceled), an optional note, and timestamps. It's not a Submission and shouldn't be modeled as one.

Resolution can happen a few ways:
- Teacher marks it resolved after talking with the student.
- Student cancels it.
- It auto-expires after some window (TBD — end of next class day? a week?).

## UX sketch

**Student side — request:**

A small "Ask for a check-in" button on the document page, placed unobtrusively (probably near the existing AI feedback affordance, but visually distinct so students don't confuse the two).

```
+--------------------------------------------------------+
| Macbeth essay              [Ask for check-in] [Submit] |
+--------------------------------------------------------+
| Editor area...                                         |
+--------------------------------------------------------+
```

Click opens a small dialog:

```
+------------------------------------------+
| Ask Mr. Connell for a check-in           |
|                                          |
| What's on your mind? (optional)          |
| +--------------------------------------+ |
| | Stuck on my conclusion — not sure    | |
| | how to land it.                      | |
| +--------------------------------------+ |
|                                          |
|              [Cancel]  [Send request]    |
+------------------------------------------+
```

After submitting, the button changes state:

```
[Check-in requested · cancel]
```

Student can cancel or it stays pending until the teacher resolves it.

**Teacher side — queue:**

Two surfaces:

1. **In-class live indicator** — when the teacher is on the My Classes dashboard for an active period, pending requests for that course surface immediately as a small badge or banner: "3 students have asked for a check-in." Clicking shows the list with student name, document title, optional note, and a "mark as resolved" affordance.

2. **Daily check-in list** — when a teacher opens the dashboard at the start of class, a section near the top shows pending requests across the course. This is where homework-mode requests show up. Same shape: student, document, optional note, resolve button.

Both surfaces share the same component; only the framing differs ("right now" vs. "since you last looked").

## Data model implications

New `CheckInRequest` entity (or whatever Yawp's naming convention prefers):

- `id`
- `studentId` (FK)
- `documentId` (FK, optional — student could request a check-in not tied to a document)
- `courseId` (FK — the course the teacher will see this in)
- `note` (text, optional)
- `state` (enum: `pending`, `resolved`, `canceled`)
- `createdAt`
- `resolvedAt` (nullable)
- `resolvedBy` (FK to user — student or teacher)

Backward compatibility: this is an additive new table. No migrations of existing data. Old clients that don't know about the table simply don't see the feature.

## File paths in `yawp-2.0` likely to change

Best-guess; engineering to confirm:

- `packages/db/` — schema and queries for `CheckInRequest`
- `services/web-app/app/routes/app.documents.$id/` — request button and dialog on the document surface
- `services/web-app/app/routes/app.my-classes.$courseId/` — queue display on the teacher dashboard
- Shared component for the request list (used by both real-time banner and daily list)
- Real-time push channel for in-class live mode (websocket or server-sent events — depends on Yawp's existing infra)

## Open questions

- [ ] Should requests auto-expire? If so, when — end of next class period, end of week? @Kevin
- [ ] Real-time push: does Yawp already have a transport for this, or is this the first feature that needs one? (Bryant)
- [ ] Should the teacher be able to "snooze" a request to a specific class period rather than the immediate next one?
- [ ] Cross-course teachers — if a student is in two courses with the same teacher, how do we route? Probably scope by Document → Course, but worth confirming.
- [ ] Privacy posture — should a student see whether others in the class have pending requests? Default no, but worth deciding.
- [ ] Is the optional note worth it, or does it create a backdoor chat surface we don't want? Lean toward including it but capping length (e.g., 200 chars).

## Edge cases

- Student requests a check-in, then submits the document before the teacher resolves it → request stays pending; submission status is independent.
- Student requests a check-in on a document not tied to any Assignment → still works; teacher sees "Daily writing" or similar context.
- Teacher resolves a request, student isn't in class that day → request is resolved-but-unattended. Teacher should be able to mark "couldn't reach" as a distinct outcome, or just resolve and move on.
- Student spams the button → debounce on the client + soft cap on pending requests per student per course (e.g., one pending at a time; new requests replace or get blocked).
- Student deletes the document the request was tied to → request keeps its reference but shows "(document deleted)" in the teacher's queue.
- Student switches teachers mid-semester → pending requests follow the Course, not the teacher.
- Multiple sections of the same course → request is scoped to the section the student is in.

## Test plan

- Unit:
  - Request state transitions (pending → resolved, pending → canceled, can't go from resolved → pending).
  - Auto-expiry logic (if we land on one).
  - One-pending-per-student rule (if we land on it).
- Integration:
  - Loader returns pending requests scoped to the teacher's course correctly.
  - Real-time channel pushes new requests to a connected teacher client.
- Manual QA:
  - Student requests a check-in → teacher sees it appear (live).
  - Student cancels → it disappears from teacher view.
  - Teacher resolves → student sees the button return to its idle state.
  - Multiple students request simultaneously → queue is stable and ordered.
  - Async flow: student requests at home → teacher sees it on next dashboard load.

## Rollout

Feature flag on. Pilot with the UA professor first since they're the highest-volume user — real stress test for queue display under load. Expand to Washington and Birmingham City after one successful week. The async (homework-mode) value is the same regardless of class size, so it should land well even outside the high-volume case.

## Engineering handoff checklist

- [ ] Domain context covered
- [ ] File paths in `yawp-2.0` listed
- [ ] Data model implications spelled out, including backward-compat plan
- [ ] UX sketch in prose
- [ ] Edge cases enumerated
- [ ] Test plan written
- [ ] Rollout plan decided