Works & Documents
Relevant source files
The following files were used as context for generating this wiki page:
PRKS organizes research material into "Works," which represent primary research entities such as PDFs, YouTube videos, and Markdown research notes. The system manages bibliographic metadata, reading progress, and structured relationships between these documents and other entities like People, Tags, and Folders.
Sources: README.md:3-8, frontend/index.html:132-154
Work Types and Sources
Works in PRKS are categorized by their underlying source material. The system currently supports two primary source types:
- PDF: Managed local files that you can read, annotate, and index for full-text search.
- YouTube: Online video references identified by URL, where PRKS stores metadata and channel information.
Sources: frontend/index.html:438-450, frontend-app/src/features/work/detail-lifecycle.ts:133-155
Source Identification
The system uses the prksInferWorkSourceKind helper to determine if a work is a PDF or a video. PDFs are served via the /api/pdfs/ endpoint, while YouTube videos are embedded using oEmbed or direct iframe rendering.
Sources: tests/browser/run_work_metadata_sync_selftest.js:46-51, frontend-app/src/features/work/detail-lifecycle.ts:140-161
Metadata and Synchronization
PRKS manages bibliographic metadata through a field-scoped synchronization system. This architecture ensures that concurrent edits to different fields (e.g., DOI and ISBN) on the same work do not result in conflicts.
Sources: frontend/js/work-metadata-state.js:3-10
Synchronized Fields
The system tracks several specific fields for each work:
| Field | Description | Type |
|---|---|---|
title | The name of the work | String |
status | Reading progress (e.g., In Progress, Completed) | Enum |
doc_type | BibLaTeX document type (e.g., article, book) | Enum |
thumb_page | PDF page used for the card thumbnail | Integer |
author_text | Plain text author credit | String |
abstract | Brief summary or preface | Text |
published_date | Publication date in ISO format | Date |
source_url | Original location or provenance URL | URL |
Sources: frontend/js/work-metadata-state.js:27-31, frontend/js/work-metadata-state.js:154-180
Field Codecs and Representations
Fields use specific codecs to transform values between different representations:
- Display: What you see in the metadata editor.
- Canonical: The "wire" format sent to the server.
- Entity: The representation stored in the local cache or database.
For example, thumb_page is sent as a string ("3") on the wire but stored as an integer (3) in the entity model to satisfy type validation.
Sources: frontend/js/work-metadata-state.js:145-180, tests/browser/run_work_metadata_sync_selftest.js:936-960
Local-First Architecture
PRKS employs a local-first workflow where edits are recorded as durable operations in a local store (prks-local-v1) before being sent to the server.
Optimistic Overlays
When you edit a work, the UI renders an "optimistic overlay." The system computes the effective state by taking the acknowledged server data and applying pending local operations.
The diagram shows how the system combines server data with local edits to produce the current view.
Sources: frontend/js/work-metadata-state.js:264-279, tests/browser/run_work_metadata_sync_selftest.js:336-350
Conflict Resolution
Conflicts are detected at the field level using revision numbers. If the server revision differs from the base revision observed by the client, a REVISION_CONFLICT is reported. You must then choose to either "Use server state" or "Apply mine," which creates a new operation against the current server revision.
Sources: frontend/js/work-metadata-state.js:401-425, tests/browser/run_work_metadata_sync_selftest.js:475-500
Work Lifecycle and Maintenance
The system handles the creation, mounting, and deletion of works through coordinated frontend and backend processes.
Mount Sequence
The mountWorkDetail function manages the transition to a specific work's detail view. It follows a strict sequence:
- Verify the current tab generation.
- Capture a resource ticket for Research Notes (EasyMDE).
- Load the appropriate viewer module (PDF or Video).
- Fetch related metadata (Tags, Concepts, Arguments).
- Initialize the viewer and notes editor.
Sources: frontend-app/src/features/work/detail-lifecycle.ts:79-130
Post-Delete Cleanup
When you delete a work, the system commits the database change first. It then records a "cleanup claim" in the pending_pdf_cleanup table. A background process retries these claims to remove orphaned files from the pdfs/ directory without locking the database during the initial transaction.
Sources: backend/AGENTS.md:124-145
Conclusion
Works and Documents form the core data layer of PRKS. By using field-scoped synchronization and a local-first durable operation queue, the system maintains research data integrity even during offline use or concurrent editing. The architecture separates raw source material from its bibliographic metadata and derived search indexes to ensure performance and reliability.
Sources: README.md:100-115, frontend/js/work-metadata-state.js:3-15