General Architecture
Relevant source files
The following files were used as context for generating this wiki page:
PRKS is a self-hosted, local-first research library application currently undergoing an active architecture transition. The system enables users to organize research material including PDFs, Markdown notes, video references, and structured research relationships like Concepts and Arguments.
Sources: AGENTS.md:3-8, README.md:1-8
High-Level System Overview
The PRKS runtime is built with a Python 3.12 backend and a hybrid frontend. The frontend consists of a legacy JavaScript UI being progressively replaced by a Vue 3 and TypeScript application. The application utilizes a "local-first" approach, providing durable browser-side operations and synchronization capabilities.
The following diagram illustrates the high-level relationship between major system components:
Sources: AGENTS.md:3-8, frontend-app/AGENTS.md:5-10
Architecture Transition
The project follows a "modular-monolith" target architecture. While current implementations rely on specific technologies, the accepted long-term direction introduces abstractions to decouple the domain from the underlying infrastructure.
Current Implementation vs. Target
| Component | Current Implementation | Long-term Target |
|---|---|---|
| Relational Store | SQLite | PostgreSQL |
| Database Mode | Single-user, local | Multi-user / Multi-library capable |
| API Process | State-local | Stateless-capable |
| Storage Root | Absolute local paths | User-configurable storage backend abstraction |
| Frontend | Vue 3 + Legacy Bridge | Full Vue 3 + TypeScript |
Sources: AGENTS.md:39-50, backend/AGENTS.md:6-12
Backend Components
The backend manages the HTTP adapter lifecycle, persistence, and specialized research services.
Core Modules
- Server Adapter (
backend/server.py): Handles host/origin checks, request-size limits, method dispatch, and static file serving. - Storage Resolver (
backend/storage/resolver.py): Determines the storage root based on CLI flags, environment variables (PRKS_STORAGE), or bootstrap configuration. - Database Manager (
backend/db_manager.py): Manages interactions with the SQLite database. - Research Services: Specialized modules like
research_network.pyandresearch_graph.pyhandle the semantic research model.
Sources: AGENTS.md:175-185, backend/AGENTS.md:46-55
Data Persistence and Cleanup
The backend follows a strict post-delete cleanup recovery model. When a Work is deleted, the canonical row is committed first, followed by filesystem and derived index cleanup.
Sources: backend/AGENTS.md:103-125
Frontend Architecture
The frontend is divided into the shipped classic shell and the migrating Vue 3 application.
Shared Runtime Contracts
The two frontend layers communicate through shared runtime contracts:
- TabContext: Manages the lifecycle and state of individual workspace tabs.
- Offline Runtime: Coordinates online/offline state transitions and mutation guards.
- Durable Operations: A system for enqueueing intents when offline to be synchronized upon reconnection.
Sources: frontend-app/AGENTS.md:31-45, AGENTS.md:225-235
Workspace Management
The workspace utilizes a split-view system with Main and Secondary panes. src/workspace/ in the Vue application owns the typed canonical workspace model, while frontend/js/workspace-tabs.js coordinates live effects and persistence.
Sources: frontend-app/AGENTS.md:47-55
Storage and Security
PRKS operates as a single-user application without built-in application-level authentication, defaulting to a safe loopback bind (127.0.0.1).
Storage Layout
| Path | Purpose |
|---|---|
prks_data.db | Canonical SQLite database |
pdfs/ | Managed PDF research material |
thumbs/ | Derived card thumbnails |
prks-root.json | Storage root marker with stable storage_root_id |
root.lock | OS-level lock to ensure single-process access |
Sources: README.md:105-135, backend/AGENTS.md:58-65
Summary
The PRKS architecture prioritizes data durability and research integrity through a local-first model. Its design allows for an incremental migration from a legacy single-user SQLite application toward a modular PostgreSQL-capable system, while maintaining consistent cross-domain contracts for its specialized research network and offline synchronization logic.
Sources: AGENTS.md:3-15, backend/AGENTS.md:6-12