Skip to content

UC-ING-502: Automated Video Metric Ingestion

1. Metadata

Property Value
ID UC-ING-502
Actor System / Media Player Service
Trigger Video playback 'Heartbeat' event
Pre-conditions Student is watching an assigned module; CDN is streaming content
Post-conditions Percentage-watched updated in real-time; Completion event fired at 95%
Side Effects Update 'Engagement Heatmap' in Admin Console

2. Description

A low-latency data stream that tracks real-time student engagement with educational video content, enabling precise impact measurement and preventing curriculum skipping.

3. Success Scenario

  1. Stream Start: Mobile Video Player (HLS) initiates playback.
  2. Heartbeat Generation: Every 10 seconds of playback, the player generates a signed 'Engagement Token'.
  3. Transmission: Token is transmitted via a lightweight WebSocket or HTTP/2 stream to the Ingestion Gateway.
  4. Processing:
    • Backend validates the Token signature (preventing playback spoofing).
    • Backend increments the seconds_watched counter for the specific {student_id, module_id} pair.
  5. Logic Assessment:
    • System calculates completion_percentage = (seconds_watched / total_duration) * 100.
    • If completion_percentage >= 95%, the backend marks the video segment as 'MASTERED'.
  6. Persistence: Aggregated progress is stored in a Redis cache for sub-second dashboard updates and periodically flushed to PostgreSQL.

4. Acceptance Criteria

  • [ ] Data Efficiency: Heartbeat packets must be < 1KB to minimize student data usage.
  • [ ] Spoof-Proof: Tokens must be time-bound and cryptographically signed by the device.
  • [ ] Concurrency: Ingestion gateway must support 10,000+ simultaneous heartbeats during peak school hours.
  • [ ] Resilience: If the heartbeat ingestor is down, the mobile app must buffer up to 5 metrics locally.

5. Signature Logic (Secure Ingestion)

sequenceDiagram participant P as Media Player participant A as Mobile App participant G as Ingestion Gateway P->>A: Playback Heartbeat (10s) A->>A: Sign Payload (Private Key) A->>G: Transmit Heartbeat + Signature G->>G: Validate Signature G->>G: Increment Seconds Watched