Developer Setup
Relevant source files
The following files were used as context for generating this wiki page:
Developer setup provides the necessary environment to contribute to PRKS, a research knowledge system using Python, SQLite, and Vue 3. You must configure a local Python environment, install required dependencies, and set up Git hooks to ensure code quality and storage safety.
Sources: README.md:1, AGENTS.md:3
Core Environment Setup
PRKS requires Python 3.12 or higher and specific runtime package pins. You should use a project-local virtual environment to manage dependencies and avoid system-level package conflicts.
Sources: README.md:46-51
1. Initialize Python Virtual Environment
Follow these steps to create and activate your environment:
- Create the virtual environment:
python3 -m venv .venv. - Install runtime dependencies:
./.venv/bin/python -m pip install -r requirements.txt. - Install development/test tooling:
./.venv/bin/python -m pip install -r requirements-dev.txt.
Sources: README.md:53-56, README.md:154-158
2. Configure Git Hooks
You must set up local Git hooks after cloning the repository. This script sets the local core.hooksPath to .githooks. Successful commits then generate a prks-latest.zip archive of the new HEAD.
- Run the setup script:
./scripts/setup-git-hooks.sh. - Verify the configuration:
git config --get core.hooksPath.
Sources: AGENTS.md:57-61
The diagram shows the sequential steps required to initialize a local development environment. Sources: README.md:154-158, AGENTS.md:57-61
Development Runtime Modes
PRKS provides two primary ways to run the application for development: standard testing mode and Docker-based execution.
Testing Mode
Testing mode is the default execution path for developers and agents. It uses port 8070 and stores data in data_testing/ to prevent modification of production data.
- Run command:
python prks_app.py --testing - Effects: Sets
PRKS_TESTING=1, isolates storage, and refuses access to the repository'sdata/directory.
Sources: README.md:92-100, AGENTS.md:63-65
Docker Execution
You can build and run the application using Docker Compose. The Docker image builds the classic frontend into ordered JavaScript bundles.
- Build:
./docker-build.sh - Run:
docker compose up -d - Port: Binds
0.0.0.0:8080in the container, published to127.0.0.1:8080on the host.
Sources: README.md:104-118
| Environment Variable | Default Value | Purpose |
|---|---|---|
PRKS_STORAGE | data/ | Root directory for persistent data (DB, PDFs, thumbs). |
PRKS_TESTING | 0 | Enables testing paths and stricter security checks. |
PRKS_LOG_LEVEL | INFO | Stderr log volume level. |
PRKS_CONFIG_FILE | Platform-specific | Path to the bootstrap configuration file. |
Sources: README.md:129-142
Testing Infrastructure
PRKS uses a multi-layered testing strategy including unit tests, end-to-end (E2E) browser tests, and UX interaction tours.
Running Tests
- Fast Unit Suite:
./.venv/bin/python run_tests.py. Includes anopenapi-corepreflight check. - Full Browser E2E Gate:
./.venv/bin/python run_tests.py --e2e. Uses Playwright and installs Chromium into.playwright-browsers/if missing. - UX Interaction Tour:
python run_tests.py --ux-tour. Produces artifacts for interaction validation.
Sources: README.md:161-170, AGENTS.md:46-50
The sequence diagram illustrates the automated workflow for executing E2E browser tests. Sources: README.md:161-165, AGENTS.md:46-50
Frontend Development (Vue 3)
The PRKS frontend is migrating to Vue 3 and TypeScript. The source code for this migration lives in frontend-app/.
Toolchain Requirements
- Node.js:
>=24.15.0 <25. - Package Manager:
npm.
Sources: frontend-app/README.md:37-38
Frontend Commands
- Navigate to the frontend directory:
cd frontend-app. - Install dependencies:
npm ci --ignore-scripts. - Build the production bundle:
npm run build. This generatesfrontend/vue/prks-vue.js. - Run component catalog:
npm run storybook.
Sources: frontend-app/README.md:44-51
Architecture Bridge
The Vue application is not a separate router. It bridges from the legacy TabContext runtime. src/route-surface/ acts as the bridge for mounting Vue views within the existing PRKS shell.
Sources: frontend-app/README.md:20-22, frontend-app/AGENTS.md:27-29
Storage and Data Layout
PRKS uses a single-process lock on storage roots. Exactly one server process may open a storage root at a time. The process holds a lock on .prks-maintenance/root.lock.
Storage Root Markers
Every storage root contains a prks-root.json marker with a storage_root_id. The application refuses to open:
- Directories that do not look like PRKS libraries.
- Roots with unreadable or newer markers.
- Roots on network filesystems (NFS/SMB).
Sources: README.md:144-150
Summary
Setting up a PRKS development environment requires Python 3.12+, Node.js 24+, and the execution of the Git hook setup script. You should prioritize running the application in testing mode (--testing) to ensure storage isolation and safety. All changes must be verified through the run_tests.py suite before submission.
Sources: README.md:92, AGENTS.md:57, frontend-app/README.md:37