QR self-enrollment, multi-photo attendance, reject-and-rematch reinforcement, and enrollment reliability fixes

- Add start_enrollment_session.py: pairs the local Flask server (now
threaded, for concurrent enrollments) with a cloudflared tunnel so
students can self-enroll via a QR code over their own mobile data,
not just the teacher's Wi-Fi
- Mark attendance now accepts multiple photos in one submission; a
student counts present if confidently matched in any one of them
- Suspicious matches: "Show face" reveal, and rejecting a match now
re-checks the embedding against the rest of the roster (excluding
the rejected student) instead of just discarding it - it lands in
Present/Suspicious/Unknown depending on what that re-match finds,
and the wrongly-suggested student drops to Absent
- Unknown faces can be assigned directly to an enrolled student from
a dropdown, reinforcing their gallery
- Guided camera recording now speaks the "arm's length" framing
instruction (previously text-only) and requests a real capture
resolution instead of trusting the browser default - both were
found to be causing near-total face-detection failure on some
enrollment recordings
- Swap the demo classroom photo for a higher-resolution one and fix
the enrollment-QR/demo pipeline to use full resolution rather than
a downscaled copy
- Add scipy, deepface, onnxruntime, qrcode to requirements.txt (all
were either missing or only present transitively)
- Rewrite README to reflect the current AdaFace-based pipeline,
per-classroom rosters, and all of the above

README.md

@@ -10,7 +10,7 @@ pinned: false
 
 # PRISM AI — Classroom Monitoring System
 
-An AI-powered classroom engagement and attendance monitoring system with a browser-based dashboard.
+An AI-powered classroom attendance and engagement monitoring system with a browser-based dashboard, designed to run on a teacher's own laptop.
 
 ---
 
@@ -18,60 +18,71 @@ An AI-powered classroom engagement and attendance monitoring system with a brows
 
 | Tab | Function |
 |---|---|
-| **Classroom Monitoring** | Upload a classroom video → detect and track every student → classify engagement using EAR, MAR, YOLO-pose, gaze and emotion signals → per-student timeline with clips |
-| **Attendance** | Enroll students from photos/videos → mark attendance from a classroom photo using face recognition |
+| **Attendance** | Mark attendance from one or more classroom photos using face recognition, per classroom (CSE 1–8) |
+| **Enroll Student** | Students self-enroll (upload, folder path, or guided camera recording) — includes a QR-code flow so a whole class can enroll from their own phones |
+| **Classroom Monitoring** | Upload a classroom video → detect and track every student → classify engagement per window → per-student timeline with clips |
+| **How it Works** | In-app explanation of both pipelines, kept in sync with the actual thresholds/behavior below |
 
 ---
 
-## Classroom Monitoring — Pipeline
+## Attendance — Face Recognition System
 
-The **Classroom pipeline** (`CLASSROOM PIPELINE/classroom_pipeline.py`) uses the following signals per student per window:
+### Detection & recognition model
+**InsightFace SCRFD** (1280×1280 detection) for face detection + landmarks, **AdaFace IR-101** (WebFace12M, 512-d L2-normalised embeddings) for recognition. AdaFace replaced the previous glintr100/antelopev2 backbone after an offline evaluation showed cleaner separation between genuine and impostor matches on real classroom photos.
 
-| Signal | How |
-|---|---|
-| **EAR** (Eye Aspect Ratio) | dlib 68-pt landmarks → eyes open/closed, blink detection |
-| **MAR** (Mouth Aspect Ratio) | dlib 68-pt landmarks → talking detection |
-| **Head pose / gaze** | solvePnP on dlib landmarks → looking centre / left / right / up / down |
-| **Body keypoints** | YOLOv8-pose → head state, posture, motion |
-| **Phone detection** | YOLO → on phone → immediately low engagement |
-| **Emotion** | DeepFace → happy / neutral / surprise / sad / angry |
-| **Face re-ID** | InsightFace embeddings + seat-position tracking across windows |
+### Per-classroom rosters
+Each of the 8 classrooms (`cse1`–`cse8`) has its own independent JSON store — enrolling into one classroom never affects another, and a teacher picks a classroom before enrolling or marking attendance.
 
-Actions classified per student: **Attentive / Writing / Talking / On Phone / Sleeping / Distracted**
+### How enrollment works
+1. Provide a face sample — upload photo(s)/video, point at a local folder of clips, or record directly in the browser (see below).
+2. Up to **30 frames** are sampled evenly across the clip (sequential decode, never seeking — seeking is unreliable for live-recorded webm from a browser's `MediaRecorder`).
+3. **Anchor-based tracking**: the first accepted frame is the identity anchor; later frames are kept only if cosine similarity ≥ **0.35** against it, so a multi-person video can't mix identities.
+4. Each accepted frame contributes its full-quality embedding plus **2 degraded copies** (downscaled to 50% / 30% then upscaled back) so the gallery also matches small, distant classroom faces, not just close-up enrollment shots.
+5. Embeddings are capped at **128 per student** (oldest evicted first) with a weighted-mean prototype recomputed on every change; outliers more than **0.50** cosine distance from the running centroid are dropped before the prototype is built.
 
----
+### Guided camera recording
+The in-browser recorder walks a student through a ~37-second sequence with **spoken** (not just written) instructions — including holding the phone at arm's length so the whole face fits in the on-screen oval, since a face filling the whole frame is a common cause of the detector missing it entirely. It also requests a real capture resolution (1280×720 ideal) rather than trusting the browser's default, which on some phones can be as low as 480×640.
 
-## Attendance — Face Recognition System
+### Self-enrollment via QR code
+A teacher can generate a QR code (Attendance tab → **Show enrollment QR**) that points students straight at their classroom's enroll page — no manual classroom picking, no need to be on the same Wi-Fi. This works by pairing the local server with a `cloudflared` quick tunnel:
 
-### Detection & recognition model
-**InsightFace `antelopev2`** — SCRFD-10G face detector + GLinT-R100 recogniser (ResNet-100, Glint360K, 512-d L2-normalised embeddings), running at det_size=1280×1280
+```bash
+python start_enrollment_session.py
+```
 
-> `utils/retinaface_detector.py` also contains a **SAHI + MTCNN + buffalo_l** wrapper used by the classroom and cognitive pipelines for better small-face recall.
+This starts the Flask app (threaded, so a burst of students enrolling at once doesn't serialize into a queue) and the tunnel together, and prints the public URL once it's live. Requires `cloudflared` installed once (`brew install cloudflared` on macOS). The tunnel is ephemeral — a fresh random URL every time the script (re)starts, and it self-heals if the tunnel reconnects mid-session with a new hostname.
 
-### How enrollment works
+### How attendance marking works
+1. Upload **one or more** classroom photos at once — a student only needs to be clearly caught in *any one* of them to count present, so someone missed or turned away in one shot can still be caught by another.
+2. Every detected face across all photos is matched by cosine similarity against every enrolled student's prototype and individual stored embeddings; each student's *best* match across all photos wins.
+3. Three-tier result:
+   - **< 0.28** similarity → no name candidate at all → **Unknown** (red box).
+   - **0.28–0.30** → a real candidate, not confident enough to auto-confirm → **Suspicious** (amber box, for a teacher to review).
+   - **≥ 0.30** → **Present** (green box). Confidence ≥ 0.60 also auto-grows that student's gallery.
+   - Anyone enrolled but not matched at either tier → **Absent**.
+4. Face crops (Present, Suspicious, and Unknown) stay hidden by default and reveal on demand via a **"Show face"** button, cropped from the pre-annotation photo so the reveal isn't obscured by a box/label.
+
+### Reinforcement — teachers correcting the model
+- **Confirming** a Suspicious match adds that embedding to the student's gallery and marks them present.
+- **Rejecting** a Suspicious match doesn't just discard it — the same face gets re-matched against the roster *excluding* the rejected student, and lands wherever that turns up: a confident hit → straight to Present, a borderline one → a fresh Suspicious entry for the new candidate, nothing left → into the Unknown pool. The wrongly-suggested student drops to Absent unless already seen elsewhere in the same result.
+- **Unknown faces** can be directly assigned to any enrolled student via a dropdown on each face card — reinforces that student's gallery and marks them present, since a teacher pointing at a photo and naming someone is direct evidence they were there.
 
-1. Upload a close-up photo/video (or paste a local folder path for multiple clips)
-2. Sample **1 frame per second** (up to 30 frames)
-3. **Anchor-based tracking** — first detected face is the identity anchor; subsequent frames accepted only if cosine similarity ≥ 0.35 (prevents multi-person videos from mixing identities)
-4. For each accepted frame, generate **4 embeddings**:
-   - Original quality
-   - Degraded to **28 px** (INTER_AREA → Gaussian σ=1 → JPEG q50 → bicubic up)
-   - Degraded to **36 px**
-   - Degraded to **44 px**
-5. All embeddings stored + weighted-mean prototype computed
+---
 
-> Degraded variants bridge the domain gap between close-up enrollment (140–230 px face) and distant classroom faces (14–50 px).
+## Classroom Monitoring — Pipeline
 
-### How attendance marking works
+The **Classroom pipeline** (`CLASSROOM PIPELINE/classroom_pipeline.py`) processes a lecture video in 30-second, 24-frame bursts rather than every frame:
 
-1. Upload a classroom photo
-2. Detect all faces (SCRFD 1280×1280)
-3. For each face: `similarity = max(cosine vs prototype, max cosine vs all stored embeddings)`
-4. If best similarity ≥ **0.38** → recognized
-5. Only the highest-scoring face per student gets the name label
+| Step | How |
+|---|---|
+| **Detection & tracking** | YOLOv8-pose for body/keypoints, InsightFace (SCRFD) for faces + 106-point landmarks, linked into per-student tracks by IoU overlap within a burst |
+| **Re-identification** | AdaFace IR-101 embeddings, resolved as a one-to-one assignment per burst (≥ 0.35 similarity) — two different people in the same burst can't collapse into one identity |
+| **Roster recognition** | The same embedding is checked read-only against the enrolled Attendance roster (≥ 0.35, with a margin over the runner-up) — a confident match shows the real name instead of an anonymous `student_00N` label |
+| **Signal extraction** | 106-point landmarks drive mouth open/closed + head yaw/pitch; YOLO for phone detection; optical flow for motion; DeepFace for dominant emotion |
+| **Action classification** | Priority ruleset: On Phone → Sleeping → Writing → Talking → Attentive → otherwise Distracted. "Attentive" is driven by mouth-closed percentage (≥ 80%) — a calibration pass against a labeled reference dataset found eye-openness (EAR) had no measurable correlation with attentiveness, while mouth state separated attentive/non-attentive far more cleanly |
+| **Engagement rollup** | Fraction of attentive windows → High (≥ 70%) / Medium (≥ 40%) / Low, plus a short saved clip per window |
 
-### Re-enrollment
-Re-enrolling the same name **adds** embeddings to the existing gallery — does not overwrite.
+**Known limitations**: phone detection is a generic, un-fine-tuned COCO model and currently finds close to none of the real phones in testing — needs replacing, not re-tuning. Attentive/not-attentive classification runs at roughly 67–70% accuracy against a 156-clip labeled reference set — a real improvement over the previous EAR-based approach, but not a solved problem.
 
 ---
 
@@ -83,11 +94,18 @@ pip install -r requirements.txt
 
 # Download YOLO model weights (Git LFS pointers — run once after cloning)
 python download_models.py
+```
+
+> `deepface` (emotion detection) pulls in `tensorflow`, which only ships wheels for Python 3.9–3.12 — create the venv with one of those versions, not whatever newest Python happens to be installed. The Docker image (below) already uses `python:3.10-slim`.
 
-# macOS — always include OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
-OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES PORT=8080 \
-  .venv/bin/gunicorn --bind 0.0.0.0:8080 --timeout 600 --workers 1 \
-  activity_web.backend.app:app
+**Just the dashboard**, no QR/tunnel:
+```bash
+OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES python -m activity_web.backend.app
+```
+
+**Dashboard + QR self-enrollment** (starts the tunnel too):
+```bash
+python start_enrollment_session.py
 ```
 
 Open **http://localhost:8080**
@@ -98,17 +116,20 @@ Open **http://localhost:8080**
 
 See [`deployment/README.md`](deployment/README.md) for full Railway deployment instructions.
 
+> The Hugging Face Space build (this repo's `Dockerfile`) has no persistent storage — enrolled rosters don't survive a rebuild there. For a real classroom, run this locally on the teacher's own machine (see above) so attendance data persists between sessions; the Space is a demo/showcase deployment, not where you'd actually enroll students.
+
 ---
 
 ## Repository Structure
 
 ```
-CLASSROOM PIPELINE/                  Main classroom analysis pipeline (EAR/MAR/YOLO/emotion)
+CLASSROOM PIPELINE/                  Main classroom analysis pipeline (mouth/gaze/YOLO/emotion, AdaFace re-ID)
 ENGAGEMENT PIPELINE/                 YOLOv8-pose engagement signals
 COGNITIVE PIPELINE/                  EAR / gaze / emotion (dlib + DeepFace)
 COMBINED PIPELINE/                   Merged engagement + cognitive
-activity_web/                        Flask web app (2 tabs: Classroom + Attendance)
-utils/                               SAHI + MTCNN + buffalo_l face detection wrapper
+activity_web/backend/                Flask web app — app.py, attendance_service.py, templates, static (incl. camera-recorder.js, enroll.js)
+utils/                               adaface_backbone.py (recognition), roster_match.py, retinaface_detector.py (SAHI + MTCNN + buffalo_l)
 Activity monitoring/models/          Trained model weights
 deployment/                          Self-contained Railway deployment build
+start_enrollment_session.py          One-command launcher: threaded Flask server + cloudflared tunnel for QR self-enrollment
 ```

activity_web/backend/app.py

@@ -21,6 +21,7 @@ from .config import (
     ATTENDANCE_DIR,
     ALLOWED_EXTENSIONS,
     ALLOWED_IMAGE_EXTENSIONS,
+    TUNNEL_URL_PATH,
 )
 from .startup import check_ffmpeg_available
 from .transcode import transcode_clips_async
@@ -103,6 +104,50 @@ def attendance_classrooms():
     })
 
 
+def _read_tunnel_url() -> str | None:
+    """The public tunnel URL, written by start_enrollment_session.py once
+    cloudflared reports it's connected. None if no session is running."""
+    try:
+        url = TUNNEL_URL_PATH.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        return None
+    return url or None
+
+
+@app.get("/api/enroll-url")
+def enroll_url():
+    classroom_id = request.args.get("classroom", "")
+    if (error := _require_classroom(classroom_id)) is not None:
+        return error
+    tunnel_url = _read_tunnel_url()
+    if not tunnel_url:
+        return jsonify({
+            "ok": False,
+            "error": "No enrollment session is running. Start it with start_enrollment_session.py on the teacher's laptop.",
+        }), 404
+    return jsonify({"ok": True, "url": f"{tunnel_url}/enroll?classroom={classroom_id}"})
+
+
+@app.get("/api/enroll-qr")
+def enroll_qr():
+    classroom_id = request.args.get("classroom", "")
+    if (error := _require_classroom(classroom_id)) is not None:
+        return error
+    tunnel_url = _read_tunnel_url()
+    if not tunnel_url:
+        return jsonify({"ok": False, "error": "No enrollment session is running."}), 404
+
+    import io
+    import qrcode
+
+    target = f"{tunnel_url}/enroll?classroom={classroom_id}"
+    img = qrcode.make(target, box_size=8, border=2)
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    buf.seek(0)
+    return send_file(buf, mimetype="image/png")
+
+
 @app.get("/api/health")
 def health():
     return jsonify({"ok": True})
@@ -159,6 +204,29 @@ def attendance_resolve_suspicious():
     return jsonify({"ok": True, **result})
 
 
+@app.post("/api/attendance/unknown/assign")
+def attendance_assign_unknown():
+    data = request.get_json(silent=True) or {}
+    classroom_id = data.get("classroom", "")
+    if (error := _require_classroom(classroom_id)) is not None:
+        return error
+
+    review_id = str(data.get("review_id", "")).strip()
+    student_id = str(data.get("student_id", "")).strip()
+    if not review_id or not student_id:
+        return jsonify({"ok": False, "error": "Missing review_id or student_id."}), 400
+
+    service = get_attendance_service(classroom_id)
+    try:
+        result = service.assign_unknown_face(review_id, student_id)
+    except KeyError as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 404
+    except Exception as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 500
+
+    return jsonify({"ok": True, **result})
+
+
 @app.post("/api/attendance/enroll")
 def attendance_enroll():
     classroom_id = request.form.get("classroom", "")
@@ -241,26 +309,34 @@ def attendance_mark():
     if (error := _require_classroom(classroom_id)) is not None:
         return error
 
-    uploaded_file = request.files.get("photo")
-    if uploaded_file is None or not uploaded_file.filename:
-        return jsonify({"ok": False, "error": "Upload a classroom photo first."}), 400
+    # "photos" (plural) lets a teacher mark attendance from several photos of
+    # the same classroom in one go — someone missed or turned away in one
+    # shot may be clearly caught in another, so a student only needs to be
+    # confidently matched in ANY one of them to count as present.
+    uploaded_files = request.files.getlist("photos")
+    if not uploaded_files or not uploaded_files[0].filename:
+        return jsonify({"ok": False, "error": "Upload at least one classroom photo first."}), 400
 
-    if not allowed_media(uploaded_file.filename):
-        return jsonify({"ok": False, "error": "Use an image or video file for attendance marking."}), 400
+    for f in uploaded_files:
+        if not allowed_media(f.filename):
+            return jsonify({"ok": False, "error": f"'{f.filename}' isn't a supported image/video file."}), 400
 
     service = get_attendance_service(classroom_id)
-    photo_name = secure_filename(uploaded_file.filename)
-    photo_path = ATTENDANCE_DIR / "uploads" / f"{uuid.uuid4().hex[:12]}_{photo_name}"
-    photo_path.parent.mkdir(parents=True, exist_ok=True)
-    uploaded_file.save(photo_path)
+    photo_paths: list[Path] = []
+    upload_dir = ATTENDANCE_DIR / "uploads"
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    for f in uploaded_files:
+        photo_name = secure_filename(f.filename)
+        photo_path = upload_dir / f"{uuid.uuid4().hex[:12]}_{photo_name}"
+        f.save(photo_path)
+        photo_paths.append(photo_path)
 
     try:
-        result = service.mark_attendance(photo_path)
+        result = service.mark_attendance_multi(photo_paths)
     except Exception as exc:
         traceback.print_exc()
         return jsonify({"ok": False, "error": str(exc)}), 500
 
-    result["marked_url"] = attendance_artifact_url(Path(result["marked_url"]).name)
     return jsonify({"ok": True, **result})
 
 
@@ -287,6 +363,7 @@ def attendance_demo():
         return jsonify({"ok": False, "error": str(exc)}), 500
 
     result["marked_url"] = attendance_artifact_url(Path(result["marked_url"]).name)
+    result["clean_url"] = attendance_artifact_url(Path(result["clean_url"]).name)
     return jsonify({"ok": True, **result})
 
 
@@ -699,4 +776,10 @@ def handle_unhandled_exception(exc):
 
 
 if __name__ == "__main__":
-    app.run(host="0.0.0.0", port=8080, debug=True, use_reloader=False)
+    # threaded=True so a burst of concurrent enrollment uploads (e.g. a
+    # class scanning the QR code at once) get processed in parallel rather
+    # than queued one-at-a-time. debug=False because this is the entrypoint
+    # used when exposing the server via a public tunnel for QR enrollment —
+    # Werkzeug's interactive debugger is a real RCE risk on anything
+    # internet-reachable.
+    app.run(host="0.0.0.0", port=8080, debug=False, use_reloader=False, threaded=True)

activity_web/backend/attendance_service.py

@@ -180,14 +180,15 @@ class AttendanceService:
 
     def _read_store(self) -> dict:
         if not self.store_path.exists():
-            return {"students": [], "attendance": [], "pending_reviews": []}
+            return {"students": [], "attendance": [], "pending_reviews": [], "pending_unknown_faces": []}
         try:
             data = json.loads(self.store_path.read_text())
         except Exception:
-            return {"students": [], "attendance": [], "pending_reviews": []}
+            return {"students": [], "attendance": [], "pending_reviews": [], "pending_unknown_faces": []}
         data.setdefault("students", [])
         data.setdefault("attendance", [])
         data.setdefault("pending_reviews", [])
+        data.setdefault("pending_unknown_faces", [])
         return data
 
     def _write_store(self, data: dict) -> None:
@@ -547,8 +548,10 @@ class AttendanceService:
             "updated_at": student.get("updated_at"),
         }
 
-    def match_student(self, embedding: np.ndarray) -> dict:
+    def match_student(self, embedding: np.ndarray, exclude_student_id: str | None = None) -> dict:
         students = self.list_students()
+        if exclude_student_id is not None:
+            students = [s for s in students if s.get("student_id") != exclude_student_id]
         if not students:
             return {"match": None, "similarity": -1.0}
 
@@ -606,9 +609,16 @@ class AttendanceService:
         mark_attendance. Confirming reinforces the model — the embedding that
         triggered the suspicious match gets added to that student's gallery,
         the same way a high-confidence classroom match already does — and
-        records the student as present. Rejecting just discards the pending
-        review; nothing is added anywhere, since a wrong name is worse to
-        learn from than a merely uncertain one."""
+        records the student as present.
+
+        Rejecting doesn't just discard the face — a wrong suggestion doesn't
+        mean the face has no identity, only that it isn't THIS student. The
+        embedding gets re-matched against the roster excluding the rejected
+        student, and lands wherever that re-match says: a confident hit
+        (>=PRESENT_SIMILARITY_THRESHOLD) becomes present, a borderline one
+        (still >=FACE_SIMILARITY_THRESHOLD) becomes a fresh suspicious entry
+        for the new candidate, and no remaining candidate at all drops it
+        into the unknown-faces pool (assignable from there)."""
         store = self._read_store()
         pending = store.get("pending_reviews", [])
 
@@ -617,6 +627,8 @@ class AttendanceService:
             raise KeyError(f"No pending review: {review_id}")
         store["pending_reviews"] = [r for r in pending if r.get("review_id") != review_id]
 
+        result: dict = {"confirmed": confirmed, "student_name": review["student_name"]}
+
         if confirmed:
             embedding = np.asarray(review["embedding"], dtype=np.float32)
             self._add_embedding_to_gallery(store, review["student_id"], embedding)
@@ -626,13 +638,101 @@ class AttendanceService:
                 "source": "classroom_photo_confirmed",
                 "confidence": review["similarity"],
             })
+            result["outcome"] = "present"
+        else:
+            embedding = np.asarray(review["embedding"], dtype=np.float32)
+            bbox = review.get("bbox")
+            photo_index = review.get("photo_index", 0)
+            rematch = self.match_student(embedding, exclude_student_id=review["student_id"])
+
+            if rematch["match"] is not None and rematch["similarity"] >= PRESENT_SIMILARITY_THRESHOLD:
+                new_student = rematch["match"]
+                if rematch["similarity"] >= 0.60:
+                    self._add_embedding_to_gallery(store, new_student["student_id"], embedding)
+                store["attendance"].append({
+                    "student_name": new_student["name"],
+                    "recognized_at": _now_iso(),
+                    "source": "classroom_photo_rematch",
+                    "confidence": round(float(rematch["similarity"]), 4),
+                })
+                result["outcome"] = "present"
+                result["new_match"] = {
+                    "student": new_student,
+                    "confidence": round(float(rematch["similarity"]), 4),
+                    "bbox": bbox,
+                    "photo_index": photo_index,
+                }
+            elif rematch["match"] is not None and rematch["similarity"] >= FACE_SIMILARITY_THRESHOLD:
+                new_review_id = uuid.uuid4().hex
+                store.setdefault("pending_reviews", []).append({
+                    "review_id": new_review_id,
+                    "student_id": rematch["match"]["student_id"],
+                    "student_name": rematch["match"]["name"],
+                    "similarity": round(float(rematch["similarity"]), 4),
+                    "embedding": review["embedding"],
+                    "bbox": bbox,
+                    "photo_index": photo_index,
+                    "created_at": _now_iso(),
+                })
+                result["outcome"] = "suspicious"
+                result["new_suspicious"] = {
+                    "review_id": new_review_id,
+                    "student": rematch["match"],
+                    "confidence": round(float(rematch["similarity"]), 4),
+                    "bbox": bbox,
+                    "photo_index": photo_index,
+                }
+            else:
+                new_review_id = uuid.uuid4().hex
+                store.setdefault("pending_unknown_faces", []).append({
+                    "review_id": new_review_id,
+                    "embedding": review["embedding"],
+                    "bbox": bbox,
+                    "photo_index": photo_index,
+                    "created_at": _now_iso(),
+                })
+                result["outcome"] = "unknown"
+                result["new_unknown"] = {
+                    "review_id": new_review_id,
+                    "similarity": round(float(rematch["similarity"]), 4) if rematch["match"] else -1.0,
+                    "bbox": bbox,
+                    "photo_index": photo_index,
+                }
 
         self._write_store(store)
-        return {
-            "confirmed": confirmed,
-            "student_name": review["student_name"],
-            "roster": self.list_students(),
-        }
+        result["roster"] = self.list_students()
+        return result
+
+    def assign_unknown_face(self, review_id: str, student_id: str) -> dict:
+        """A teacher identifying an 'Unknown' face crop (below the match
+        threshold entirely) as a specific enrolled student. Unlike a
+        suspicious-match confirmation, there's no name attached yet — the
+        teacher is supplying it — so this both reinforces that student's
+        gallery with the embedding and marks them present, since a teacher
+        pointing at a photo and naming someone is direct evidence they were
+        there."""
+        store = self._read_store()
+        pending = store.get("pending_unknown_faces", [])
+
+        entry = next((f for f in pending if f.get("review_id") == review_id), None)
+        if entry is None:
+            raise KeyError(f"No pending unknown face: {review_id}")
+        store["pending_unknown_faces"] = [f for f in pending if f.get("review_id") != review_id]
+
+        student = next((s for s in store.get("students", []) if s.get("student_id") == student_id), None)
+        if student is None:
+            raise KeyError(f"No such student: {student_id}")
+
+        embedding = np.asarray(entry["embedding"], dtype=np.float32)
+        self._add_embedding_to_gallery(store, student_id, embedding)
+        store["attendance"].append({
+            "student_name": student["name"],
+            "recognized_at": _now_iso(),
+            "source": "unknown_face_assigned",
+        })
+
+        self._write_store(store)
+        return {"student_name": student["name"], "roster": self.list_students()}
 
     def mark_attendance(self, media_path: Path) -> dict:
         if not media_path.exists():
@@ -718,6 +818,8 @@ class AttendanceService:
                             "student_name": student["name"],
                             "similarity": round(float(similarity), 4),
                             "embedding": _normalize(det.embedding).tolist(),
+                            "bbox": [x1, y1, x2, y2],
+                            "photo_index": 0,
                             "created_at": _now_iso(),
                         })
                         entry["review_id"] = review_id
@@ -727,9 +829,16 @@ class AttendanceService:
                 color = (0, 0, 255)
                 sim = match["similarity"]
                 label = f"Unknown {sim:.2f}"
+                review_id = uuid.uuid4().hex
+                store.setdefault("pending_unknown_faces", []).append({
+                    "review_id": review_id,
+                    "embedding": _normalize(det.embedding).tolist(),
+                    "created_at": _now_iso(),
+                })
                 unknown_faces_detail.append({
                     "bbox": [x1, y1, x2, y2],
                     "similarity": round(float(sim), 4),
+                    "review_id": review_id,
                 })
 
             cv2.rectangle(marked_frame, (x1, y1), (x2, y2), color, 2)
@@ -753,6 +862,14 @@ class AttendanceService:
         marked_path = MARKED_DIR / marked_name
         cv2.imwrite(str(marked_path), marked_frame)
 
+        # Also save the pre-annotation frame — the frontend crops individual
+        # faces (Present "Show face", unknown-faces grid) from this instead
+        # of the boxed/labelled image, so the revealed face isn't covered by
+        # a bounding-box border or confidence text.
+        clean_name = f"{media_path.stem}_clean.jpg"
+        clean_path = MARKED_DIR / clean_name
+        cv2.imwrite(str(clean_path), frame)
+
         return {
             "present": present,
             "suspicious": suspicious,
@@ -761,6 +878,170 @@ class AttendanceService:
             "unknown_faces_detail": unknown_faces_detail,
             "marked_path": str(marked_path),
             "marked_url": f"/api/attendance/artifacts/{marked_name}",
+            "clean_path": str(clean_path),
+            "clean_url": f"/api/attendance/artifacts/{clean_name}",
+            "roster": self.list_students(),
+        }
+
+    def mark_attendance_multi(self, media_paths: list[Path]) -> dict:
+        """Same idea as mark_attendance, but across several photos of the
+        same classroom taken back to back (different angles/moments catch
+        people a single photo misses — someone turned away or blocked in
+        one shot may be clearly visible in another). A student is Present/
+        Suspicious based on their single BEST match across all the photos,
+        not per-photo — so being missed in one photo doesn't hurt them if
+        they were caught clearly in another. Absent = never matched (at
+        either tier) in any of the photos."""
+        if not media_paths:
+            raise ValueError("No photos provided")
+
+        store = self._read_store()
+        attendance_log = store["attendance"]
+
+        best_by_student: dict[str, dict] = {}
+        seen_any_student_ids: set[str] = set()
+        unknown_faces = 0
+        unknown_faces_detail: list[dict] = []
+        photos_out: list[dict] = []
+
+        for photo_index, media_path in enumerate(media_paths):
+            if not media_path.exists():
+                raise FileNotFoundError(f"File not found: {media_path}")
+
+            suffix = media_path.suffix.lower()
+            if suffix in {".jpg", ".jpeg", ".png", ".webp", ".bmp"}:
+                frame = self._load_image(media_path)
+                if frame is None:
+                    raise RuntimeError(f"Could not read classroom photo: {media_path.name}")
+            else:
+                frames = self._sample_video_frames(media_path)
+                if not frames:
+                    raise RuntimeError(f"Could not read classroom video: {media_path.name}")
+                frame = frames[0]
+
+            detections = self._detect_samples(frame)
+            marked_frame = frame.copy()
+            all_matches = [(det, self.match_student(det.embedding)) for det in detections]
+
+            best_per_student_this_photo: dict[str, tuple] = {}
+            for det, match in all_matches:
+                if match["match"] is not None:
+                    name = match["match"]["name"]
+                    if name not in best_per_student_this_photo or match["similarity"] > best_per_student_this_photo[name][1]:
+                        best_per_student_this_photo[name] = (det, match["similarity"], match)
+            best_det_ids = {id(det) for det, _, _ in best_per_student_this_photo.values()}
+
+            for det, match in all_matches:
+                x1, y1, x2, y2 = det.bbox
+                is_best = match["match"] is not None and id(det) in best_det_ids
+
+                if is_best:
+                    student = match["match"]
+                    similarity = float(match["similarity"])
+                    is_present = similarity >= PRESENT_SIMILARITY_THRESHOLD
+                    color = (0, 200, 0) if is_present else (0, 165, 255)
+                    tag = "" if is_present else " (suspicious)"
+                    label = f"{student['name']} {similarity:.2f}{tag}"
+
+                    sid = student["student_id"]
+                    seen_any_student_ids.add(sid)
+                    if sid not in best_by_student or similarity > best_by_student[sid]["similarity"]:
+                        best_by_student[sid] = {
+                            "student": student,
+                            "similarity": similarity,
+                            "bbox": [x1, y1, x2, y2],
+                            "photo_index": photo_index,
+                            "embedding": det.embedding,
+                        }
+                else:
+                    unknown_faces += 1
+                    color = (0, 0, 255)
+                    sim = match["similarity"]
+                    label = f"Unknown {sim:.2f}"
+                    review_id = uuid.uuid4().hex
+                    store.setdefault("pending_unknown_faces", []).append({
+                        "review_id": review_id,
+                        "embedding": _normalize(det.embedding).tolist(),
+                        "created_at": _now_iso(),
+                    })
+                    unknown_faces_detail.append({
+                        "bbox": [x1, y1, x2, y2],
+                        "similarity": round(float(sim), 4),
+                        "photo_index": photo_index,
+                        "review_id": review_id,
+                    })
+
+                cv2.rectangle(marked_frame, (x1, y1), (x2, y2), color, 2)
+                cv2.putText(
+                    marked_frame, label,
+                    (x1, max(20, y1 - 8)),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.55, color, 2, cv2.LINE_AA,
+                )
+
+            marked_name = f"{media_path.stem}_marked.jpg"
+            marked_path = MARKED_DIR / marked_name
+            cv2.imwrite(str(marked_path), marked_frame)
+
+            clean_name = f"{media_path.stem}_clean.jpg"
+            clean_path = MARKED_DIR / clean_name
+            cv2.imwrite(str(clean_path), frame)
+
+            photos_out.append({
+                "marked_url": f"/api/attendance/artifacts/{marked_name}",
+                "clean_url": f"/api/attendance/artifacts/{clean_name}",
+            })
+
+        present: list[dict] = []
+        suspicious: list[dict] = []
+        for info in best_by_student.values():
+            student = info["student"]
+            similarity = info["similarity"]
+            entry = {
+                "student": student,
+                "confidence": round(similarity, 4),
+                "bbox": info["bbox"],
+                "photo_index": info["photo_index"],
+            }
+            if similarity >= PRESENT_SIMILARITY_THRESHOLD:
+                present.append(entry)
+                attendance_log.append({
+                    "student_name": student["name"],
+                    "recognized_at": _now_iso(),
+                    "source": "classroom_photo",
+                    "confidence": round(similarity, 4),
+                })
+                if similarity >= 0.60:
+                    self._add_embedding_to_gallery(store, student["student_id"], info["embedding"])
+            else:
+                review_id = uuid.uuid4().hex
+                store.setdefault("pending_reviews", []).append({
+                    "review_id": review_id,
+                    "student_id": student["student_id"],
+                    "student_name": student["name"],
+                    "similarity": round(similarity, 4),
+                    "embedding": _normalize(info["embedding"]).tolist(),
+                    "bbox": info["bbox"],
+                    "photo_index": info["photo_index"],
+                    "created_at": _now_iso(),
+                })
+                entry["review_id"] = review_id
+                suspicious.append(entry)
+
+        absent = [
+            self._student_public(s) for s in store.get("students", [])
+            if s.get("student_id") not in seen_any_student_ids
+        ]
+
+        store["attendance"] = attendance_log
+        self._write_store(store)
+
+        return {
+            "present": present,
+            "suspicious": suspicious,
+            "absent": absent,
+            "unknown_faces": unknown_faces,
+            "unknown_faces_detail": unknown_faces_detail,
+            "photos": photos_out,
             "roster": self.list_students(),
         }
 

activity_web/backend/config.py

@@ -12,6 +12,11 @@ UPLOAD_DIR = Path(os.environ.get("ACTIVITY_WEB_UPLOAD_DIR", RUNTIME_DIR / "uploa
 OUTPUT_DIR = Path(os.environ.get("ACTIVITY_WEB_OUTPUT_DIR", RUNTIME_DIR / "outputs"))
 ATTENDANCE_DIR = Path(os.environ.get("ACTIVITY_WEB_ATTENDANCE_DIR", RUNTIME_DIR / "attendance"))
 
+# Written by start_enrollment_session.py once the cloudflared tunnel is up,
+# so the running Flask process (a separate subprocess) can pick up the
+# public URL without a restart.
+TUNNEL_URL_PATH = RUNTIME_DIR / "tunnel_url.txt"
+
 # Allowed file types
 ALLOWED_EXTENSIONS = {".mp4", ".mov", ".avi", ".mkv", ".webm"}
 ALLOWED_IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".bmp"}

activity_web/backend/static/app.js

@@ -164,6 +164,34 @@ classroomSelect.addEventListener("change", async () => {
   updateRosterClassroomLabel();
   markResult.classList.add("hidden");
   await refreshAttendanceSummary();
+  if (!enrollQrPanel.classList.contains("hidden")) await loadEnrollQr();
+});
+
+// ── Attendance tab: enrollment QR (students join via cloudflared tunnel) ────
+const enrollQrToggle = document.getElementById("enroll-qr-toggle");
+const enrollQrPanel  = document.getElementById("enroll-qr-panel");
+const enrollQrBody   = document.getElementById("enroll-qr-body");
+
+async function loadEnrollQr() {
+  enrollQrBody.innerHTML = `<p class="muted">Loading...</p>`;
+  try {
+    const response = await fetch(`/api/enroll-url?classroom=${encodeURIComponent(currentClassroomId)}`);
+    const data = await response.json();
+    if (!response.ok || !data.ok) throw new Error(data.error || "No enrollment session running.");
+    enrollQrBody.innerHTML = `
+      <img class="enroll-qr-image" src="/api/enroll-qr?classroom=${encodeURIComponent(currentClassroomId)}&t=${Date.now()}" alt="Enrollment QR code" />
+      <p class="enroll-qr-link">${data.url}</p>
+      <p class="muted">Students scan this to enroll themselves into ${classroomSelect.options[classroomSelect.selectedIndex]?.textContent || "this classroom"} — no Wi-Fi match needed, works over their own mobile data.</p>`;
+  } catch (err) {
+    enrollQrBody.innerHTML = `<p class="muted">${err.message} Start it with <code>python start_enrollment_session.py</code> on this laptop, then reopen this panel.</p>`;
+  }
+}
+
+enrollQrToggle.addEventListener("click", async () => {
+  const opening = enrollQrPanel.classList.contains("hidden");
+  enrollQrPanel.classList.toggle("hidden", !opening);
+  enrollQrToggle.textContent = opening ? "Hide enrollment QR" : "Show enrollment QR";
+  if (opening) await loadEnrollQr();
 });
 
 // ── Enroll Student tab: its own independent classroom picker ────────────────
@@ -202,7 +230,7 @@ const classroomPhotoInput = document.getElementById("classroom-photo-input");
 const classroomPhotoLabel = document.getElementById("classroom-photo-label");
 const markStatus        = document.getElementById("mark-status");
 const markResult        = document.getElementById("mark-result");
-const markedPhotoPreview= document.getElementById("marked-photo-preview");
+const markedPhotoGallery = document.getElementById("marked-photo-gallery");
 const presentList       = document.getElementById("present-list");
 const suspiciousList    = document.getElementById("suspicious-list");
 const absentList        = document.getElementById("absent-list");
@@ -289,19 +317,21 @@ enrollForm.addEventListener("submit", async (event) => {
 
 markForm.addEventListener("submit", async (event) => {
   event.preventDefault();
-  if (!classroomPhotoInput.files.length) { markStatus.textContent = "Upload a classroom photo first."; markStatus.classList.add("error"); return; }
+  if (!classroomPhotoInput.files.length) { markStatus.textContent = "Upload at least one classroom photo first."; markStatus.classList.add("error"); return; }
   const btn = markForm.querySelector("button[type='submit']");
   const payload = new FormData();
   payload.append("classroom", currentClassroomId);
-  payload.append("photo", classroomPhotoInput.files[0]);
+  Array.from(classroomPhotoInput.files).forEach((f) => payload.append("photos", f));
   markStatus.classList.remove("error");
-  markStatus.textContent = "Detecting faces and marking attendance...";
+  markStatus.textContent = classroomPhotoInput.files.length > 1
+    ? `Detecting faces across ${classroomPhotoInput.files.length} photos and marking attendance...`
+    : "Detecting faces and marking attendance...";
   btn.disabled = true;
   try {
     const response = await fetch("/api/attendance/mark", { method: "POST", body: payload });
     const data = await response.json();
     if (!response.ok || !data.ok) throw new Error(data.error || "Attendance marking failed.");
-    renderMarkedPhoto(data.marked_url);
+    renderMarkedPhotos(data.photos || []);
     renderAttendanceBuckets(data.present || [], data.suspicious || [], data.absent || [], data.unknown_faces || 0, data.unknown_faces_detail || []);
     renderRoster(data.roster || []);
     markStatus.textContent = `${data.present.length} present, ${data.suspicious.length} suspicious, ${data.absent.length} absent.`;
@@ -315,7 +345,7 @@ markForm.addEventListener("submit", async (event) => {
 document.getElementById("demo-preview-btn").addEventListener("click", () => {
   markStatus.classList.remove("error");
   markStatus.textContent = "Demo classroom photo — original, no annotations.";
-  markedPhotoPreview.src = "/static/demo_classroom.jpg";
+  markedPhotoGallery.innerHTML = `<img class="marked-photo-preview" src="/static/demo_classroom.jpg" alt="Demo classroom photo" />`;
   markResult.classList.remove("hidden");
   presentList.innerHTML = "";
   suspiciousList.innerHTML = "";
@@ -330,7 +360,7 @@ document.getElementById("demo-btn").addEventListener("click", async () => {
 
   // Step 1 — show original unannotated image immediately
   markResult.classList.remove("hidden");
-  markedPhotoPreview.src = "/static/demo_classroom.jpg";
+  markedPhotoGallery.innerHTML = `<img class="marked-photo-preview" src="/static/demo_classroom.jpg" alt="Demo classroom photo" />`;
   markStatus.textContent = "Here's the demo classroom photo. Running attendance pipeline...";
 
   // Step 2 — run the pipeline
@@ -338,7 +368,7 @@ document.getElementById("demo-btn").addEventListener("click", async () => {
     const response = await fetch(`/api/attendance/demo?classroom=${encodeURIComponent(currentClassroomId)}`, { method: "POST" });
     const data = await response.json();
     if (!response.ok || !data.ok) throw new Error(data.error || "Demo failed.");
-    renderMarkedPhoto(data.marked_url);
+    renderMarkedPhotos([{ marked_url: data.marked_url, clean_url: data.clean_url }]);
     renderAttendanceBuckets(data.present || [], data.suspicious || [], data.absent || [], data.unknown_faces || 0, data.unknown_faces_detail || []);
     renderRoster(data.roster || []);
     markStatus.textContent = `Demo complete — ${data.present.length} present, ${data.suspicious.length} suspicious, ${data.absent.length} absent.`;
@@ -365,10 +395,14 @@ function renderEnrollmentResult(student, mediaSamples) {
     <div class="result-detail">${mediaSamples.map((s) => `${s.file_name} (${s.frame_samples} frames)`).join(", ")}</div>`;
 }
 
-function renderMarkedPhoto(url) {
-  if (!url) { markResult.classList.add("hidden"); return; }
+function renderMarkedPhotos(photos) {
+  if (!photos || !photos.length) { markResult.classList.add("hidden"); return; }
   markResult.classList.remove("hidden");
-  markedPhotoPreview.src = url;
+  markedPhotoGallery.innerHTML = photos
+    .map((p, i) => `<img class="marked-photo-preview" data-photo-index="${i}" src="${p.marked_url}" alt="Marked classroom photo ${i + 1}" />`)
+    .join("");
+  currentCleanPhotoUrls = photos.map((p) => p.clean_url);
+  cleanPhotoImageCache = {};
 }
 
 const unknownFacesToggle = document.getElementById("unknown-faces-toggle");
@@ -376,18 +410,33 @@ const unknownFacesGrid   = document.getElementById("unknown-faces-grid");
 let currentUnknownFaces  = [];
 let unknownFacesExpanded = false;
 
+let currentPresentFaces = [];
+
 function renderAttendanceBuckets(present, suspicious, absent, unknownFaces, unknownFacesDetail) {
+  currentPresentFaces = present.map((e) => ({ bbox: e.bbox, photoIndex: e.photo_index ?? 0 }));
   presentList.innerHTML = `<h3>Present (${present.length})</h3>
     ${present.length
-      ? present.map((e) => `<div class="result-item present-item"><strong>${e.student.name}</strong><span>Confidence ${formatNumber(e.confidence)}</span></div>`).join("")
+      ? present.map((e, i) => `
+        <div class="result-item present-item">
+          <div class="present-item-row">
+            <strong>${e.student.name}</strong>
+            <span>Confidence ${formatNumber(e.confidence)}</span>
+            <button type="button" class="show-face-btn" data-face-index="${i}">Show face</button>
+          </div>
+          <div class="face-reveal hidden" data-face-slot="${i}"></div>
+        </div>`).join("")
       : '<div class="result-item muted">No students confidently recognized.</div>'}`;
 
   suspiciousList.innerHTML = `<h3>Suspicious (${suspicious.length})</h3>
     ${suspicious.length
       ? suspicious.map((e) => `
-        <div class="result-item suspicious-item" data-review-id="${e.review_id}">
-          <strong>${e.student.name}</strong>
-          <span>Confidence ${formatNumber(e.confidence)} — please verify</span>
+        <div class="result-item suspicious-item" data-review-id="${e.review_id}" data-bbox='${JSON.stringify(e.bbox)}' data-photo-index="${e.photo_index ?? 0}">
+          <div class="present-item-row">
+            <strong>${e.student.name}</strong>
+            <span>Confidence ${formatNumber(e.confidence)} — please verify</span>
+            <button type="button" class="show-face-btn">Show face</button>
+          </div>
+          <div class="face-reveal hidden"></div>
           <div class="suspicious-actions">
             <button type="button" class="suspicious-btn suspicious-confirm-btn" data-review-id="${e.review_id}">Yes, it's them</button>
             <button type="button" class="suspicious-btn suspicious-reject-btn" data-review-id="${e.review_id}">Not them</button>
@@ -413,11 +462,108 @@ function renderAttendanceBuckets(present, suspicious, absent, unknownFaces, unkn
   }
 }
 
+function addToAbsentList(name) {
+  if ([...absentList.querySelectorAll(".absent-item strong")].some((el) => el.textContent === name)) return;
+  const muted = absentList.querySelector(".muted");
+  if (muted) muted.remove();
+  absentList.insertAdjacentHTML("beforeend", `<div class="result-item absent-item"><strong>${name}</strong></div>`);
+  const h3 = absentList.querySelector("h3");
+  if (h3) h3.textContent = `Absent (${absentList.querySelectorAll(".absent-item").length})`;
+}
+
+function removeFromAbsentList(name) {
+  const match = [...absentList.querySelectorAll(".absent-item")].find((el) => el.querySelector("strong")?.textContent === name);
+  if (match) match.remove();
+  const count = absentList.querySelectorAll(".absent-item").length;
+  const h3 = absentList.querySelector("h3");
+  if (h3) h3.textContent = `Absent (${count})`;
+  if (count === 0 && !absentList.querySelector(".muted")) {
+    absentList.insertAdjacentHTML("beforeend", '<div class="result-item muted">Everyone enrolled was seen.</div>');
+  }
+}
+
+function addPresentEntry(student, confidence, bbox, photoIndex) {
+  const muted = presentList.querySelector(".muted");
+  if (muted) muted.remove();
+  const index = currentPresentFaces.length;
+  currentPresentFaces.push({ bbox, photoIndex: photoIndex ?? 0 });
+  presentList.insertAdjacentHTML("beforeend", `
+    <div class="result-item present-item">
+      <div class="present-item-row">
+        <strong>${student.name}</strong>
+        <span>Confidence ${formatNumber(confidence)}</span>
+        <button type="button" class="show-face-btn" data-face-index="${index}">Show face</button>
+      </div>
+      <div class="face-reveal hidden" data-face-slot="${index}"></div>
+    </div>`);
+  const h3 = presentList.querySelector("h3");
+  if (h3) h3.textContent = `Present (${presentList.querySelectorAll(".present-item").length})`;
+}
+
+function addSuspiciousEntry(newSuspicious) {
+  const muted = suspiciousList.querySelector(".muted");
+  if (muted) muted.remove();
+  suspiciousList.insertAdjacentHTML("beforeend", `
+    <div class="result-item suspicious-item" data-review-id="${newSuspicious.review_id}" data-bbox='${JSON.stringify(newSuspicious.bbox)}' data-photo-index="${newSuspicious.photo_index ?? 0}">
+      <div class="present-item-row">
+        <strong>${newSuspicious.student.name}</strong>
+        <span>Confidence ${formatNumber(newSuspicious.confidence)} — please verify</span>
+        <button type="button" class="show-face-btn">Show face</button>
+      </div>
+      <div class="face-reveal hidden"></div>
+      <div class="suspicious-actions">
+        <button type="button" class="suspicious-btn suspicious-confirm-btn" data-review-id="${newSuspicious.review_id}">Yes, it's them</button>
+        <button type="button" class="suspicious-btn suspicious-reject-btn" data-review-id="${newSuspicious.review_id}">Not them</button>
+      </div>
+    </div>`);
+  const h3 = suspiciousList.querySelector("h3");
+  if (h3) h3.textContent = `Suspicious (${suspiciousList.querySelectorAll(".suspicious-item").length})`;
+}
+
+async function addUnknownEntry(newUnknown) {
+  currentUnknownFaces.push({
+    bbox: newUnknown.bbox,
+    similarity: newUnknown.similarity,
+    photo_index: newUnknown.photo_index,
+    review_id: newUnknown.review_id,
+  });
+  unknownFacesToggle.classList.remove("hidden");
+  unknownFacesToggle.textContent = unknownFacesExpanded
+    ? `Hide unknown faces (${currentUnknownFaces.length})`
+    : `Show unknown faces (${currentUnknownFaces.length})`;
+  if (unknownFacesExpanded) await renderUnknownFacesGrid();
+}
+
 // Confirming reinforces the model: the embedding that triggered the suspicious
 // match gets added to that student's gallery (same as an automatic high-
-// confidence match would). Rejecting just discards it — nothing is learned
-// from a match the teacher says is wrong.
+// confidence match would). Rejecting doesn't just discard the face — it gets
+// re-matched against the roster excluding the rejected student, and lands in
+// Present/Suspicious/Unknown depending on what that re-match finds, while the
+// wrongly-suggested student drops to Absent (unless seen elsewhere).
 suspiciousList.addEventListener("click", async (event) => {
+  const showBtn = event.target.closest(".show-face-btn");
+  if (showBtn) {
+    const item = showBtn.closest(".suspicious-item");
+    const bbox = JSON.parse(item.dataset.bbox);
+    const photoIndex = Number(item.dataset.photoIndex || 0);
+    const slot = item.querySelector(".face-reveal");
+    if (!slot.querySelector("img")) {
+      try {
+        const dataUrl = cropFaceThumbnail(imageAsCanvas(await getCleanPhotoImage(photoIndex)), bbox);
+        slot.innerHTML = `<img src="${dataUrl}" alt="Face of suspicious match" />`;
+      } catch (err) {
+        slot.innerHTML = `<span class="muted">${err.message}</span>`;
+        slot.classList.remove("hidden");
+        showBtn.textContent = "Hide face";
+        return;
+      }
+    }
+    const wasVisible = !slot.classList.contains("hidden");
+    slot.classList.toggle("hidden", wasVisible);
+    showBtn.textContent = wasVisible ? "Show face" : "Hide face";
+    return;
+  }
+
   const confirmBtn = event.target.closest(".suspicious-confirm-btn");
   const rejectBtn  = event.target.closest(".suspicious-reject-btn");
   const btn = confirmBtn || rejectBtn;
@@ -440,10 +586,28 @@ suspiciousList.addEventListener("click", async (event) => {
 
     item.classList.remove("suspicious-item");
     item.classList.add(confirmed ? "present-item" : "absent-item");
-    item.innerHTML = confirmed
-      ? `<strong>${name}</strong><span>Confirmed — added to their gallery.</span>`
-      : `<strong>${name}</strong><span>Marked as not them.</span>`;
-    if (confirmed) await refreshAttendanceSummary();
+
+    if (confirmed) {
+      item.innerHTML = `<strong>${name}</strong><span>Confirmed — added to their gallery.</span>`;
+      await refreshAttendanceSummary();
+      return;
+    }
+
+    item.innerHTML = `<strong>${name}</strong><span>Not them — re-checked against the rest of the roster.</span>`;
+
+    const stillPresent = [...presentList.querySelectorAll(".present-item strong")].some((el) => el.textContent === name);
+    if (!stillPresent) addToAbsentList(name);
+
+    if (data.outcome === "present" && data.new_match) {
+      addPresentEntry(data.new_match.student, data.new_match.confidence, data.new_match.bbox, data.new_match.photo_index);
+      removeFromAbsentList(data.new_match.student.name);
+    } else if (data.outcome === "suspicious" && data.new_suspicious) {
+      addSuspiciousEntry(data.new_suspicious);
+    } else if (data.outcome === "unknown" && data.new_unknown) {
+      await addUnknownEntry(data.new_unknown);
+    }
+
+    await refreshAttendanceSummary();
   } catch (err) {
     alert(err.message);
     item.querySelectorAll("button").forEach((b) => (b.disabled = false));
@@ -458,61 +622,166 @@ function hideUnknownFacesUI() {
   unknownFacesGrid.innerHTML = "";
 }
 
-function cropUnknownFaceThumbnails(imgEl, faces, pad = 26, outSize = 220) {
+function cropFaceThumbnail(sourceCanvas, bbox, pad = 26, outSize = 220) {
+  const [x1, y1, x2, y2] = bbox;
+  const px1 = Math.max(0, x1 - pad);
+  const py1 = Math.max(0, y1 - pad);
+  const px2 = Math.min(sourceCanvas.width, x2 + pad);
+  const py2 = Math.min(sourceCanvas.height, y2 + pad);
+  const pw = Math.max(1, px2 - px1);
+  const ph = Math.max(1, py2 - py1);
+
+  const out = document.createElement("canvas");
+  const scale = Math.max(outSize / pw, outSize / ph);
+  out.width = Math.round(pw * scale);
+  out.height = Math.round(ph * scale);
+  const octx = out.getContext("2d");
+  octx.imageSmoothingQuality = "high";
+  octx.drawImage(sourceCanvas, px1, py1, pw, ph, 0, 0, out.width, out.height);
+  return out.toDataURL("image/jpeg", 0.88);
+}
+
+function imageAsCanvas(imgEl) {
   const source = document.createElement("canvas");
   source.width = imgEl.naturalWidth;
   source.height = imgEl.naturalHeight;
-  const sctx = source.getContext("2d");
-  sctx.drawImage(imgEl, 0, 0);
-
-  return faces.map(({ bbox, similarity }) => {
-    const [x1, y1, x2, y2] = bbox;
-    const px1 = Math.max(0, x1 - pad);
-    const py1 = Math.max(0, y1 - pad);
-    const px2 = Math.min(source.width, x2 + pad);
-    const py2 = Math.min(source.height, y2 + pad);
-    const pw = Math.max(1, px2 - px1);
-    const ph = Math.max(1, py2 - py1);
-
-    const out = document.createElement("canvas");
-    const scale = Math.max(outSize / pw, outSize / ph);
-    out.width = Math.round(pw * scale);
-    out.height = Math.round(ph * scale);
-    const octx = out.getContext("2d");
-    octx.imageSmoothingQuality = "high";
-    octx.drawImage(source, px1, py1, pw, ph, 0, 0, out.width, out.height);
-    return { dataUrl: out.toDataURL("image/jpeg", 0.88), similarity };
+  source.getContext("2d").drawImage(imgEl, 0, 0);
+  return source;
+}
+
+// Face crops (Present "Show face", unknown-faces grid) are cropped from the
+// pre-annotation photo, not the boxed/labelled preview — otherwise the
+// revealed face would have a bounding-box border and confidence text drawn
+// across it. With multiple photos per mark, each face crop has to come from
+// the specific photo it was detected in — indexed by photo_index. Cached
+// per index so repeated crops don't re-fetch/re-decode.
+let currentCleanPhotoUrls = []; // clean_url per photo, indexed by photo_index
+let cleanPhotoImageCache = {};  // { [photoIndex]: { url, img } }
+
+function getCleanPhotoImage(photoIndex = 0) {
+  return new Promise((resolve, reject) => {
+    const url = currentCleanPhotoUrls[photoIndex];
+    if (!url) { reject(new Error("No photo loaded yet.")); return; }
+    const cached = cleanPhotoImageCache[photoIndex];
+    if (cached && cached.url === url) {
+      resolve(cached.img);
+      return;
+    }
+    const img = new Image();
+    img.onload = () => {
+      cleanPhotoImageCache[photoIndex] = { url, img };
+      resolve(img);
+    };
+    img.onerror = () => reject(new Error("Could not load photo for cropping."));
+    img.src = url;
   });
 }
 
-function renderUnknownFacesGrid() {
-  const thumbs = cropUnknownFaceThumbnails(markedPhotoPreview, currentUnknownFaces);
+async function cropUnknownFaceThumbnails(faces, pad = 26, outSize = 220) {
+  const results = [];
+  for (const { bbox, similarity, photo_index, review_id } of faces) {
+    const source = imageAsCanvas(await getCleanPhotoImage(photo_index ?? 0));
+    results.push({ dataUrl: cropFaceThumbnail(source, bbox, pad, outSize), similarity, reviewId: review_id });
+  }
+  return results;
+}
+
+// Present faces stay hidden by default (privacy) — a "Show face" button
+// crops the face on demand from the already-rendered marked photo, the
+// same technique used for the unknown-faces grid.
+presentList.addEventListener("click", async (event) => {
+  const btn = event.target.closest(".show-face-btn");
+  if (!btn) return;
+  const index = Number(btn.dataset.faceIndex);
+  const face = currentPresentFaces[index];
+  const slot = presentList.querySelector(`.face-reveal[data-face-slot="${index}"]`);
+  if (!face || !slot) return;
+
+  if (!slot.querySelector("img")) {
+    try {
+      const dataUrl = cropFaceThumbnail(imageAsCanvas(await getCleanPhotoImage(face.photoIndex)), face.bbox);
+      slot.innerHTML = `<img src="${dataUrl}" alt="Face of recognized student" />`;
+    } catch (err) {
+      slot.innerHTML = `<span class="muted">${err.message}</span>`;
+      slot.classList.remove("hidden");
+      btn.textContent = "Hide face";
+      return;
+    }
+  }
+  const wasVisible = !slot.classList.contains("hidden");
+  slot.classList.toggle("hidden", wasVisible);
+  btn.textContent = wasVisible ? "Show face" : "Hide face";
+});
+
+async function renderUnknownFacesGrid() {
+  const thumbs = await cropUnknownFaceThumbnails(currentUnknownFaces);
   unknownFacesGrid.innerHTML = thumbs
     .map(
       (t) => `
-        <figure class="unknown-face-card">
+        <figure class="unknown-face-card" data-review-id="${t.reviewId ?? ""}">
           <img src="${t.dataUrl}" alt="Unrecognized face, similarity ${formatNumber(t.similarity)}" />
           <figcaption>Unknown &middot; ${formatNumber(t.similarity)}</figcaption>
+          ${t.reviewId ? `
+            <select class="assign-face-select">
+              <option value="">Assign to...</option>
+              ${currentRoster.map((s) => `<option value="${s.student_id}">${s.name}</option>`).join("")}
+            </select>` : ""}
         </figure>`
     )
     .join("");
 }
 
-unknownFacesToggle.addEventListener("click", () => {
+// A teacher identifying an unrecognized face as a specific enrolled student —
+// reinforces that student's gallery with this embedding and marks them
+// present, the same idea as confirming a suspicious match but for a face
+// that had no name candidate at all.
+unknownFacesGrid.addEventListener("change", async (event) => {
+  const select = event.target.closest(".assign-face-select");
+  if (!select) return;
+  const studentId = select.value;
+  if (!studentId) return;
+  const card = select.closest(".unknown-face-card");
+  const reviewId = card.dataset.reviewId;
+  const studentName = select.options[select.selectedIndex].textContent;
+  select.disabled = true;
+
+  try {
+    const response = await fetch("/api/attendance/unknown/assign", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ classroom: currentClassroomId, review_id: reviewId, student_id: studentId }),
+    });
+    const data = await response.json();
+    if (!response.ok || !data.ok) throw new Error(data.error || "Failed to assign.");
+    card.querySelector("figcaption").textContent = `Assigned to ${studentName}`;
+    select.remove();
+    await refreshAttendanceSummary();
+  } catch (err) {
+    alert(err.message);
+    select.disabled = false;
+  }
+});
+
+unknownFacesToggle.addEventListener("click", async () => {
   unknownFacesExpanded = !unknownFacesExpanded;
   if (unknownFacesExpanded) {
-    const build = () => renderUnknownFacesGrid();
-    if (markedPhotoPreview.complete && markedPhotoPreview.naturalWidth) build();
-    else markedPhotoPreview.addEventListener("load", build, { once: true });
     unknownFacesGrid.classList.remove("hidden");
     unknownFacesToggle.textContent = `Hide unknown faces (${currentUnknownFaces.length})`;
+    try {
+      await renderUnknownFacesGrid();
+    } catch (err) {
+      unknownFacesGrid.innerHTML = `<div class="result-item muted">${err.message}</div>`;
+    }
   } else {
     unknownFacesGrid.classList.add("hidden");
     unknownFacesToggle.textContent = `Show unknown faces (${currentUnknownFaces.length})`;
   }
 });
 
+let currentRoster = [];
+
 function renderRoster(students) {
+  currentRoster = students || [];
   if (!students.length) { rosterList.innerHTML = '<div class="result-item muted">No students enrolled yet.</div>'; return; }
   rosterList.innerHTML = students.map((s) => `
     <div class="roster-item" data-student-id="${s.student_id}">
@@ -544,7 +813,12 @@ rosterList.addEventListener("click", async (event) => {
 const lightbox      = document.getElementById("photo-lightbox");
 const lightboxImg   = document.getElementById("lightbox-img");
 const lightboxClose = document.getElementById("lightbox-close");
-markedPhotoPreview.addEventListener("click", () => { lightboxImg.src = markedPhotoPreview.src; lightbox.classList.remove("hidden"); });
+markedPhotoGallery.addEventListener("click", (event) => {
+  const img = event.target.closest(".marked-photo-preview");
+  if (!img) return;
+  lightboxImg.src = img.src;
+  lightbox.classList.remove("hidden");
+});
 lightboxClose.addEventListener("click", () => lightbox.classList.add("hidden"));
 lightbox.addEventListener("click", (e) => { if (e.target === lightbox) lightbox.classList.add("hidden"); });
 document.addEventListener("keydown", (e) => { if (e.key === "Escape") lightbox.classList.add("hidden"); });

activity_web/backend/static/camera-recorder.js

@@ -18,6 +18,7 @@
 
 const CameraRecorder = (() => {
   const DEFAULT_SCRIPT = [
+    { text: "Hold your phone at arm's length, so your whole face fits inside the oval", seconds: 5 },
     { text: "Look straight at the camera", seconds: 10 },
     { text: "Slowly turn your head to the left", seconds: 8 },
     { text: "Slowly turn your head to the right", seconds: 8 },
@@ -73,7 +74,14 @@ const CameraRecorder = (() => {
 
     async function startCamera() {
       try {
-        stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
+        // Explicit resolution request — without this, some phones default to
+        // a low capture resolution (observed as low as 480x640), which combined
+        // with a face filling most of the frame gives the detector very little
+        // to work with. "ideal" degrades gracefully on cameras that can't hit it.
+        stream = await navigator.mediaDevices.getUserMedia({
+          video: { width: { ideal: 1280 }, height: { ideal: 720 } },
+          audio: false,
+        });
       } catch (err) {
         statusEl.textContent = "Couldn't access the camera: " + err.message;
         return;

activity_web/backend/static/enroll.js

@@ -43,6 +43,19 @@ async function loadClassrooms() {
     const data = await response.json();
     if (!data.ok || !data.classrooms.length) throw new Error(data.error || "No classrooms available.");
     classroomSelect.innerHTML = data.classrooms.map((c) => `<option value="${c.id}">${c.label}</option>`).join("");
+
+    // Arriving via a teacher's QR code — the link encodes the classroom so
+    // there's nothing to pick.
+    const qsClassroom = new URLSearchParams(window.location.search).get("classroom");
+    const match = data.classrooms.find((c) => c.id === qsClassroom);
+    if (match) {
+      classroomSelect.value = match.id;
+      classroomSelect.disabled = true;
+      const note = document.createElement("p");
+      note.className = "muted";
+      note.textContent = `Enrolling into ${match.label} (from your teacher's QR code).`;
+      classroomSelect.closest("label").after(note);
+    }
   } catch (err) {
     statusEl.textContent = "Couldn't load classrooms: " + err.message;
     statusEl.classList.add("error");

activity_web/backend/static/styles.css

@@ -194,6 +194,46 @@ h1 {
   color: var(--muted);
 }
 
+.enroll-qr-toggle {
+  margin-left: auto;
+  padding: 8px 16px;
+  border-radius: 12px;
+  border: 1.5px dashed rgba(37, 99, 235, 0.5);
+  background: rgba(37, 99, 235, 0.08);
+  color: #1d4ed8;
+  font-weight: 700;
+  font-size: 0.85rem;
+  cursor: pointer;
+  box-shadow: none;
+}
+.enroll-qr-toggle:hover { background: rgba(37, 99, 235, 0.15); }
+
+.enroll-qr-panel {
+  margin-bottom: 18px;
+  padding: 18px;
+  border-radius: 18px;
+  border: 1px solid var(--border);
+  background: rgba(255, 255, 255, 0.72);
+  text-align: center;
+}
+
+.enroll-qr-image {
+  width: 220px;
+  height: 220px;
+  image-rendering: pixelated;
+  border-radius: 12px;
+  background: #fff;
+  padding: 10px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}
+
+.enroll-qr-link {
+  margin: 12px 0 4px;
+  font-family: monospace;
+  font-size: 0.85rem;
+  word-break: break-all;
+}
+
 .roster-classroom-label {
   font-size: 0.8rem;
   font-weight: 700;
@@ -277,6 +317,37 @@ h1 {
   background: rgba(120, 120, 120, 0.06);
 }
 
+.present-item-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.show-face-btn {
+  margin-left: auto;
+  padding: 4px 10px;
+  border-radius: 10px;
+  font-size: 0.74rem;
+  font-weight: 700;
+  cursor: pointer;
+  border: 1.5px solid rgba(34, 197, 94, 0.4);
+  background: rgba(34, 197, 94, 0.1);
+  color: #15803d;
+  box-shadow: none;
+}
+.show-face-btn:hover { background: rgba(34, 197, 94, 0.18); }
+
+.face-reveal { margin-top: 8px; }
+
+.face-reveal img {
+  width: 96px;
+  height: 96px;
+  object-fit: cover;
+  border-radius: 12px;
+  display: block;
+}
+
 .suspicious-actions {
   display: flex;
   gap: 6px;
@@ -494,12 +565,33 @@ h1 {
   display: block;
 }
 
+.assign-face-select {
+  width: 100%;
+  padding: 5px 6px;
+  border-radius: 8px;
+  border: 1px solid var(--border);
+  font-size: 0.72rem;
+  background: rgba(255, 255, 255, 0.9);
+}
+.assign-face-select:disabled { opacity: 0.5; }
+
 .unknown-face-card figcaption {
   font-size: 0.72rem;
   color: var(--muted);
   text-align: center;
 }
 
+.marked-photo-gallery {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 12px;
+  margin-bottom: 14px;
+}
+
+.marked-photo-gallery:has(.marked-photo-preview:only-child) {
+  grid-template-columns: 1fr;
+}
+
 .marked-photo-preview {
   width: 100%;
   max-height: 420px;

activity_web/backend/templates/index.html

@@ -31,19 +31,24 @@
               Classroom
               <select id="classroom-select"></select>
             </label>
+            <button id="enroll-qr-toggle" type="button" class="enroll-qr-toggle">Show enrollment QR</button>
+          </div>
+
+          <div id="enroll-qr-panel" class="enroll-qr-panel hidden">
+            <div id="enroll-qr-body"></div>
           </div>
 
           <div class="attendance-grid">
             <article class="attendance-card attendance-card-wide">
               <div class="attendance-card-header">
                 <h2>Mark attendance</h2>
-                <p>Upload a classroom photo and match all detected faces against the enrolled roster.</p>
+                <p>Upload one or more classroom photos — a student only needs to be clearly caught in any one of them to count as present. Faces are matched against the enrolled roster.</p>
               </div>
 
               <form id="mark-form" class="stack-form">
                 <label class="file-drop file-drop-compact">
-                  <input id="classroom-photo-input" name="photo" type="file" accept="image/*,video/*" required />
-                  <span id="classroom-photo-label">Choose a classroom photo</span>
+                  <input id="classroom-photo-input" name="photos" type="file" accept="image/*,video/*" multiple required />
+                  <span id="classroom-photo-label">Choose one or more classroom photos</span>
                 </label>
 
                 <button type="submit">Mark attendance</button>
@@ -56,7 +61,7 @@
 
               <div id="mark-status" class="status">Ready to mark attendance.</div>
               <div id="mark-result" class="attendance-result hidden">
-                <img id="marked-photo-preview" class="marked-photo-preview" alt="Marked classroom photo" />
+                <div id="marked-photo-gallery" class="marked-photo-gallery"></div>
                 <div class="attendance-buckets">
                   <div class="attendance-bucket">
                     <div id="present-list" class="result-list"></div>

requirements.txt

@@ -10,8 +10,17 @@ huggingface_hub
 torch
 torchvision
 imageio-ffmpeg
+qrcode[pil]
+scipy
+deepface
+onnxruntime
 
 # Note: heavy ML packages (torch, torchvision, insightface, ultralytics)
 # may require specific wheels or system libraries and can fail on
 # ephemeral platforms. Consider using a Dockerfile or deploying to
-# a VM for reliable builds.
+# a VM for reliable builds.
+#
+# deepface pulls in tensorflow, which only ships wheels for Python 3.9-3.12 —
+# it will fail to resolve on newer local interpreters (e.g. 3.13/3.14). The
+# Dockerfile uses python:3.10-slim, where this installs cleanly; for a raw
+# local venv, make sure it's created with Python 3.10-3.12.

start_enrollment_session.py

@@ -0,0 +1,172 @@
+"""One-command launcher for a QR-based self-enrollment session.
+
+Starts the Flask app (threaded, bound to 0.0.0.0 so it can also be reached
+directly over LAN) and a cloudflared quick tunnel (so it's also reachable
+over the *public* internet — students on mobile data don't need to be on
+the teacher's Wi-Fi). Once the tunnel is up, its URL is written to
+activity_web/runtime/tunnel_url.txt, which the running Flask app reads to
+build the QR code shown on the Attendance tab ("Show enrollment QR").
+
+Usage:
+    python start_enrollment_session.py [--classroom cse8]
+
+Ctrl+C stops both processes and clears the tunnel URL.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent
+sys.path.insert(0, str(REPO_ROOT))
+
+from activity_web.backend.config import RUNTIME_DIR, TUNNEL_URL_PATH  # noqa: E402
+
+TUNNEL_URL_RE = re.compile(r"https://[a-zA-Z0-9\-]+\.trycloudflare\.com")
+FLASK_PORT = 8080
+
+
+def check_cloudflared() -> None:
+    if shutil.which("cloudflared") is None:
+        print(
+            "cloudflared isn't installed. On macOS: brew install cloudflared\n"
+            "(see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ "
+            "for other platforms)"
+        )
+        sys.exit(1)
+
+
+def port_in_use(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        return sock.connect_ex(("127.0.0.1", port)) == 0
+
+
+def stream_output(pipe, prefix: str, on_line=None) -> None:
+    for line in iter(pipe.readline, ""):
+        if not line:
+            break
+        print(f"[{prefix}] {line.rstrip()}")
+        if on_line:
+            on_line(line)
+
+
+def main() -> None:
+    sys.stdout.reconfigure(line_buffering=True)
+    check_cloudflared()
+    RUNTIME_DIR.mkdir(parents=True, exist_ok=True)
+
+    if port_in_use(FLASK_PORT):
+        print(
+            f"Port {FLASK_PORT} is already in use — an enrollment session is probably already\n"
+            f"running (maybe in another terminal, or left over from earlier). Either use that\n"
+            f"one, or stop it first:\n"
+            f"    lsof -ti:{FLASK_PORT} | xargs kill; pkill -f 'cloudflared tunnel'\n"
+            f"then re-run this script. (Starting a second instance on top of a live one leaves\n"
+            f"a stale tunnel URL behind, which is exactly what caused the Cloudflare 1033 error.)"
+        )
+        sys.exit(1)
+
+    # Only cleared past this point — starting a second instance while one is
+    # already live must NOT touch a working session's tunnel_url.txt.
+    TUNNEL_URL_PATH.unlink(missing_ok=True)
+
+    flask_proc: subprocess.Popen | None = None
+    tunnel_proc: subprocess.Popen | None = None
+
+    def cleanup() -> None:
+        TUNNEL_URL_PATH.unlink(missing_ok=True)
+        for proc in (tunnel_proc, flask_proc):
+            if proc is not None and proc.poll() is None:
+                proc.terminate()
+        for proc in (tunnel_proc, flask_proc):
+            if proc is None:
+                continue
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+
+    try:
+        print(f"Starting the local server on http://0.0.0.0:{FLASK_PORT} ...")
+        flask_proc = subprocess.Popen(
+            [sys.executable, "-m", "activity_web.backend.app"],
+            cwd=REPO_ROOT,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+        threading.Thread(target=stream_output, args=(flask_proc.stdout, "server"), daemon=True).start()
+
+        print("Starting the cloudflared tunnel ...")
+        tunnel_proc = subprocess.Popen(
+            ["cloudflared", "tunnel", "--url", f"http://localhost:{FLASK_PORT}"],
+            cwd=REPO_ROOT,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+
+        found_url: dict[str, str | None] = {"url": None}
+
+        def watch_for_url(line: str) -> None:
+            # Free quick tunnels have no uptime guarantee — if the connection
+            # drops and cloudflared reconnects, it can get reassigned a new
+            # hostname while this process keeps running. Always take the
+            # latest one (not just the first) so the QR panel self-heals
+            # instead of quietly serving a dead link.
+            match = TUNNEL_URL_RE.search(line)
+            if match and match.group(0) != found_url["url"]:
+                found_url["url"] = match.group(0)
+                TUNNEL_URL_PATH.write_text(found_url["url"], encoding="utf-8")
+                print(f"[tunnel] URL is now: {found_url['url']}")
+
+        threading.Thread(
+            target=stream_output, args=(tunnel_proc.stdout, "tunnel", watch_for_url), daemon=True
+        ).start()
+
+        print("Waiting for the tunnel URL ...")
+        waited = 0.0
+        while not found_url["url"] and waited < 30:
+            time.sleep(0.5)
+            waited += 0.5
+            if flask_proc.poll() is not None:
+                print("The local server exited unexpectedly — check the [server] log above.")
+                return
+            if tunnel_proc.poll() is not None:
+                print("cloudflared exited unexpectedly — check the [tunnel] log above.")
+                return
+
+        if not found_url["url"]:
+            print("Timed out waiting for the tunnel URL. Check the [tunnel] log above for errors.")
+            return
+
+        print("\n" + "=" * 60)
+        print("Enrollment session is live.")
+        print(f"  Public URL:  {found_url['url']}")
+        print(f"  Dashboard:   http://localhost:{FLASK_PORT}/")
+        print("Open the dashboard, pick a classroom on the Attendance tab, and")
+        print("click 'Show enrollment QR' to display the QR code for students.")
+        print("=" * 60 + "\n")
+        print("Press Ctrl+C to stop the session.")
+
+        while True:
+            time.sleep(1)
+            if flask_proc.poll() is not None or tunnel_proc.poll() is not None:
+                print("A subprocess exited — stopping the session.")
+                break
+    except KeyboardInterrupt:
+        print("\nStopping...")
+    finally:
+        cleanup()
+
+
+if __name__ == "__main__":
+    main()