Introduction to PRKS
Relevant source files
The following files were used as context for generating this wiki page:
PRKS (Personal Research Knowledge System) is a self-hosted, local-first research library. It organizes PDFs, Markdown research notes, online video references, bibliographic metadata, and structured research relationships. The system runs on Python 3.12+ and uses SQLite for storage, requiring no separate database server for standard deployments.
The application enables you to read and annotate PDFs, connect notes to a research graph, and manage research across in-app tabs and split panes. It is currently undergoing an architecture transition from a legacy JavaScript UI to a Vue 3 and TypeScript frontend, and from SQLite toward a modular-monolith target capable of supporting PostgreSQL.
Sources: README.md:1-15, AGENTS.md:1-10
Core System Architecture
PRKS operates as a single-user application without built-in authentication. The backend uses a standard library HTTP adapter and executes commands via a CLI entry point.
Architecture Transition
The system is moving toward a modular-monolith target. This future state includes explicit User/Library boundaries, PostgreSQL as the canonical relational store, and stateless-capable API processes. The current implementation relies on SQLite, local file management, and a durable browser-side synchronization protocol.
Sources: AGENTS.md:1-15, AGENTS.md:65-75, backend/AGENTS.md:8-15
Backend Layout
The backend manages storage resolution, database migrations, and research indexing.
The diagram shows the request flow from the CLI entry point through the HTTP adapter to domain logic and storage management.
Sources: AGENTS.md:133-170
Data Management and Storage
PRKS stores persistent data in a directory defined by the PRKS_STORAGE environment variable. If unset, it defaults to a project-local data/ directory.
Storage Root Resolution
A storage root is chosen based on a specific hierarchy. Only one PRKS process may use a storage root at a time, enforced by an operating-system lock on .prks-maintenance/root.lock.
| Priority | Source | Description |
|---|---|---|
| 1 | --storage-root PATH | Explicit path passed during startup. |
| 2 | PRKS_STORAGE | Environment variable. |
| 3 | Bootstrap Config | storage.local_root in the config file. |
| 4 | Default | Project-local data/ directory. |
Sources: README.md:87-105, backend/AGENTS.md:71-82
Data Components
The system categorizes data to manage backups and restores effectively.
- Canonical Data: SQLite database (
prks_data.db), managed PDFs, and person files. These are required for backups. - Derived Data: Thumbnails, text indexes, and research indexes. These are rebuildable from canonical state and are excluded from backups.
- Operational Data: Storage markers (
prks-root.json) and process locks.
Sources: README.md:113-118, backend/AGENTS.md:92-105
Workspace and User Interface
The PRKS interface provides a dense, utilitarian workspace focused on research efficiency. It avoids standard browser tab management by implementing internal tabs and split-pane views.
Workspace Structure
The workspace consists of a Main pane and optional Secondary panes. You can resize splits and the application remembers local layout memory.
The diagram illustrates the hierarchical relationship between the shell and the active research panes.
Sources: README.md:155-165, frontend-app/AGENTS.md:55-70, frontend/index.html:45-120
Key Navigation Components
- Command Palette: Accessible via
Ctrl/Cmd+Kfor navigation and search. - Research Graph: A visual map of Concepts, Positions, and Arguments.
- Saved Views: Stored search definitions for quick access to filtered research sets.
Sources: README.md:155-168, frontend/index.html:125-145
Feature Summary
PRKS provides specialized modules for different aspects of the research process.
| Feature | Description |
|---|---|
| PDF Viewer | Supports reading, continuous vertical scroll, and annotations. |
| Research Notes | Side-by-side Markdown editing with wiki-link support ([[Work Title]]). |
| People Management | Organizes individuals by roles (Author, Editor, etc.) and groups. |
| Processing Inbox | A watch-folder for ingesting new files into the library. |
| Offline Runtime | Uses IndexedDB and Service Workers for offline-capable operations. |
Sources: README.md:14-25, frontend/index.html:105-115, frontend-app/README.md:95-110
Security and Operational Model
PRKS is designed as a local, single-user tool. It binds to the literal loopback address 127.0.0.1:8080 by default.
- No Authentication: The application contains no built-in login system. You must not expose it to untrusted networks without an external access layer.
- Privacy: Logs are metadata-only and never record user content, notes, or search terms.
- Host Validation: The server performs origin and host checks to protect against browser-based attacks.
Sources: README.md:51-60, README.md:175-180, backend/AGENTS.md:58-65, SECURITY.md:55-65
PRKS organizes research by combining local file management with structured metadata and semantic relationships. Its architecture prioritizes data durability and local-first availability, while its interface provides a consolidated workspace for intensive research tasks.