Playlists & Progress
Relevant source files
The following files were used as context for generating this wiki page:
Playlists and Progress tracking represent the organizational and lifecycle layers of the Personal Research Knowledge System (PRKS). The system organizes related video research materials into ordered sequences called Playlists and tracks the consumption state of individual research entities through Progress statuses.
The module implements a local-first architecture where organizational changes—such as reordering a playlist or updating a reading status—are captured as durable operations. These operations provide immediate UI feedback while maintaining eventual consistency with the server through a revision-based synchronization protocol.
Sources: README.md, frontend/js/playlist-state.js:1-12
Playlist Management
A Playlist groups related video works, such as course lectures, into a specific ordered sequence. Unlike folders which are hierarchical, playlists are aggregate structures where the entire order of items is treated as a single unit of synchronization to avoid index-by-index merge conflicts.
Data Model and Fields
Each playlist contains three primary editable fields and an ordered list of memberships.
| Field | Type | Description |
|---|---|---|
title | String | The name of the playlist (Defaults to "Untitled playlist"). |
description | String | Optional context or summary of the playlist content. |
original_url | String | Link to the source material (e.g., a YouTube playlist URL). |
items | Array | Ordered list of Work IDs belonging to the playlist. |
Sources: frontend/js/playlist-state.js:19-33, backend/db_manager.py:1262-1273
Local-First Operations
Playlist modifications use specific operation shapes to ensure offline capability. When a user reorders a playlist, the frontend enqueues a REORDER_PLAYLIST_ITEMS operation containing the entire desired ID list.
The diagram shows how user actions are transformed into durable operations before being sent to the API.
Sources: frontend/js/playlist-state.js:350-388, tests/browser/run_playlist_sync_selftest.js:46-52
Work Membership and Progress
Which playlist a video belongs to is treated as a scalar field on the Work entity itself. A video work can exist in at most one playlist at a time.
Progress Statuses
Research progress is tracked using five distinct statuses. These are shared across all work types, including PDFs and videos.
- Not Started: The default state for new entities.
- Planned: Material identified for future research.
- In Progress: Material currently being consumed or analyzed.
- Paused: Active research that has been temporarily halted.
- Completed: Research consumption is finished.
Sources: backend/db_manager.py:48-52, frontend/index.html:112-145
Membership Logic
Updating membership involves the SET_WORK_PLAYLIST operation. Removing a video from a playlist is performed by setting the playlist_id to an empty string.
The sequence illustrates the flow of a work membership change from local capture to server acknowledgement.
Sources: frontend/js/playlist-state.js:296-305, tests/browser/run_playlist_sync_selftest.js:98-115
Effective Projections
The system uses "Effective Projections" to render the UI. These functions take the canonical cached data and overlay any pending local operations. This allows the user to see their changes (like a renamed playlist or a moved video) before the server has acknowledged the request.
Effective Playlist Detail
The prksEffectivePlaylistDetail function merges a playlist's cached state with pending memberships and reorders.
- Field Application: Applies pending title or description edits.
- Membership Update: Adds works that have pending joins and removes those with pending departures.
- Order Application: If a pending reorder exists, it sorts the items. Items not in the reorder list but present in the playlist are moved to the end to prevent data loss.
Sources: frontend/js/playlist-state.js:154-192
Effective Work Progress
The system provides a specific browse projection for progress tracking. This projection is optimized for card-based views and omits large fields like the full text content or private notes to save bandwidth during synchronization.
| Parameter | Function |
|---|---|
id | Unique work identifier. |
status | Current progress state. |
abstract_excerpt | Bounded excerpt of the abstract (first 100 characters). |
author_text | Displayed author attribution. |
Sources: backend/db_manager.py:207-231
Data Synchronization and Conflict Handling
Coherence is maintained using a revision-based system. Every field and the playlist order have associated revision numbers.
Revision Fencing
A durable operation must name the base_revision it was measured against. If the server's current revision is higher than the submitted base, a REVISION_CONFLICT is returned.
- Fencing: When an operation is acknowledged, the system "fences" the affected domain. This prevents stale reads (GET requests issued before the change) from overwriting the new local state.
- Tombstones: Deletions are treated as tombstones. The entity is hidden in the UI immediately, but the local data is not destroyed until the server acknowledges the deletion.
Sources: frontend/js/playlist-state.js:315-348, tests/e2e/test_playlists_offline.py:61-75, tests/browser/run_playlist_sync_selftest.js:164-175
Summary
The Playlists and Progress systems provide a local-first framework for organizing research materials and tracking their status. By utilizing durable operations and effective projections, PRKS ensures that organizational changes remain responsive and available regardless of network connectivity. The system treats playlist order as an aggregate unit and work membership as a work-level scalar to simplify conflict resolution and maintain a consistent sequence of research materials.