ADR-0021: Watch History¶
Metadata¶
Status: Accepted (2026-10-15) · Date: 2026-10-15 · Deciders: nguyenhuuca · Tags: history, privacy, data-model, api-contract Supersedes: ADR-0013, ADR-0014. Both were written on 2026-06-01, before collections, i18n, the view counter and the History page existed, and neither was implemented. Related: PRD-watch-history-v2 · plan-watch-history-v2 · ADR-0020 (i18n)
Context¶
- The History page (nav key
history) exists, but it only holds "My suggestions". The Stitch design ("History & My Suggestions") adds a watch-history tab: entries grouped by day, a watched-progress bar, "pause history", "clear all" and search. - The player already reports real playback.
VideoPlayercallsPOST /videos/{id}/viewonce 3 s of real, visible playback have been watched; seeks are ignored.VideoViewServiceImpldedupes per viewer for 30 min and incrementsvideo_sources.view_count. The request carries the JWT, so the server knows the user. user_settings.incognito_enabledexists, and Settings shows it as "Incognito Mode — watch history won't be recorded while active". Nothing reads it yet.- Per-user tables in this schema (
video_reactions,video_collection_items) use a composite primary key and nativeINSERT … ON CONFLICT. - Prod runs on a 1 vCPU VM with Postgres on the same host. Writes must stay cheap, with no fan-out.
Decision Drivers¶
- One trigger, one threshold: a "watch" means the same thing as a counted view (≥ 3 s of real playback), with no second client timer.
- No extra requests on play start: zero new requests for the common case.
- Privacy:
- Owner-only access, derived from the JWT and never from a client
userId. - Incognito really records nothing, including progress.
- The user can delete one entry or everything.
- Owner-only access, derived from the JWT and never from a client
- Bounded storage: at most 500 entries per user, enforced on write.
- Convention fit: composite primary key and native upsert, like
video_reactions. Liquibase SQL. No new infrastructure.
Decisions¶
D1. Record history inside the existing view endpoint¶
- In
POST /videos/{id}/view, an authenticated caller who is not in incognito also gets a history upsert. - This is independent of the 30-minute view dedupe: a re-watch inside the window still moves the entry to the top. It does not count a second view.
- Guests (IP viewer key) get no history.
- Rejected: a separate
POST /watch-historyon play start (ADR-0013/0014). It costs an extra request per play and duplicates the threshold logic. It would also record 1-second skips.
D2. Table watch_history, composite primary key (user_id, video_id)¶
watch_history(
user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
video_id BIGINT NOT NULL REFERENCES video_sources(id) ON DELETE CASCADE,
watched_at TIMESTAMPTZ NOT NULL DEFAULT now(),
position_sec INT NOT NULL DEFAULT 0 CHECK (position_sec >= 0),
duration_sec INT CHECK (duration_sec > 0),
PRIMARY KEY (user_id, video_id))
INDEX (user_id, watched_at DESC)
- One row per user per video. A re-watch updates
watched_at. - The upsert inserts through
INSERT … SELECT … FROM video_sources WHERE id = ? AND is_hide = false AND status = 'PUBLISHED', the same public-visibility rule as the feed. An unknown or hidden id therefore writes nothing, and no foreign-key error escapes. This replaces ADR-0014's "store null video_id" approach. - Rejected: a
BIGINTsurrogate key or a UUID. The pair is the identity, and no entry id is ever exposed.
D3. 500-entry cap, enforced in the upsert transaction¶
- After the upsert, run
DELETE FROM watch_history WHERE user_id = ? AND video_id IN (SELECT video_id … ORDER BY watched_at DESC OFFSET 500). - This is self-healing under concurrency: a concurrent writer can only leave the table transiently over the cap.
- There is no time-based retention job. The cap bounds storage at 500 × users.
D4. Progress is a separate, update-only call¶
PUT /watch-history/{videoId}/progress {positionSec, durationSec}updates the existing row only. It never inserts, so it cannot bypass the 3 s threshold.- It is a no-op in incognito.
- The client sends it on pause, on switching video, on tab hide and every 30 s while playing. It uses
fetchwithkeepalive.sendBeaconis not usable because it cannot send theAuthorizationheader. - The server clamps values: position ≤ duration, duration ≤ 6 h.
- A video counts as completed at ≥ 90 % or within 10 s of the end. Completed videos show "Watched" and resume from 0.
D5. Read API, owner-scoped and paged¶
GET /watch-history?q=&page=&size=returns entries newest first, joined tovideo_sourcesin one query (no N+1).qis a case-insensitive title match.GET /watch-history/summaryreturns at most 500 entries as{videoId, positionSec, durationSec}. It drives the "Watched" badges and resume without a request per card.DELETE /watch-history/{videoId}andDELETE /watch-historyreturn 204.- The client groups entries into Today / Yesterday / Earlier in the user's local time zone.
D6. "Pause history" is user_settings.incognito_enabled¶
- The History page toggle and the Settings "Incognito Mode" toggle edit the same flag through the existing
PATCH /user/settings. They are two entry points for one setting, with no new column. - While it is on, D1 and D4 write nothing. Existing entries remain readable and deletable.
D7. Account deletion clears history¶
UserSettingsServiceImpl.deleteAccount soft-deletes the user (ADR-0016). It now also deletes that user's watch_history, because viewing history is personal data with no audit value. The cascade covers hard deletes.
Consequences¶
Positive:
- No new request on play start.
- History and view counts share one definition of a watch.
- Incognito finally does what Settings says.
- Storage is bounded.
Negative:
- History depends on the view call. A blocked or dropped view request means no history entry. This is the same best-effort contract as view counts, and it is acceptable.
- Progress heartbeats add about 1 small
PUTper 30 s per active logged-in viewer. On 1 vCPU this is fine at current traffic; revisit if traffic grows ten times. - The title search is accent-sensitive (
ILIKE). Theunaccentextension is a later option (see open questions in the PRD).
Reversibility: a two-way door. The table and endpoints are additive. Rollback drops the table and removes the upsert call from the view path.
Compliance¶
@RateLimited:GETlist: 60/min- summary: 30/min
- progress: 120/min
- deletes: 20/min
- All endpoints are authenticated and use the JWT user id only.
- Tests cover:
- owner isolation
- incognito
- the cap
- a hidden or unknown video
- re-watch inside the dedupe window
- clamping