Development Setup
The recommended way to develop Parascope is using the provided Docker Compose environment. This setup provides a consistent environment with all dependencies pre-configured and hot-reloading enabled for both the frontend and backend.
Prerequisites
- Docker and Docker Compose installed and running.
- Git for version control.
Getting Started (Docker Dev Mode)
-
Configure Environment: Copy the example environment file to
.envin the root directory.cp .env.example .env -
Start Development Containers:
docker compose up --build
Why use Docker for development?
- Hot Reloading: Changes in
frontend/srcorbackend/srcare automatically detected and reflected in the running application without manual restarts. - Integrated Environment: PostgreSQL and the worker pool are automatically set up and seeded with example data.
- Shared Libraries: The
parascope-runtimepackage is mounted as an editable install, so changes in the shared runtime are immediately reflected in the backend. - Consistency: Every developer works in the exact same environment, minimizing configuration issues.
Common Development Tasks
Viewing Logs
To stream logs from all services:
docker compose logs -f
To see logs for a specific service (e.g., the backend execution engine):
docker compose logs -f backend
Entering a Container
To run commands inside the backend container (e.g., manual database operations):
docker compose exec backend bash
Resetting the Environment
To clear all data (including the database volume) and restart fresh:
docker compose down -v
docker compose up --build
Linting & Formatting
Maintaining consistent code style is important. We use automated tools for both parts of the stack.
Backend (Ruff)
Ruff handles linting, import sorting, and formatting for Python code.
cd backend
uv run ruff check . # Check for issues
uv run ruff check --fix . # Fix issues and sort imports
uv run ruff format . # Format code
Frontend (Biome)
Biome handles linting and formatting for the TypeScript frontend.
cd frontend
pnpm lint # Check for issues
pnpm format # Fix issues and format code
Alternative: Manual Local Setup
For power users who prefer running services directly on their host machine:
Backend
- Requires Python 3.12 and uv.
- Install locked dependencies:
cd backend && uv sync --locked. This also installs the local runtime as an editable dependency. - Run migrations:
uv run alembic upgrade head. - Start:
uv run python src/main.py.
Frontend
- Requires Node.js 24 and pnpm 12.14.0, pinned in
package.json. - Install dependencies:
cd frontend && pnpm install --frozen-lockfile. - Start:
pnpm dev(Runs on http://localhost:5173).
Dependency Management
Python lockfiles
Commit both backend/uv.lock and packages/parascope-runtime/uv.lock.
Each project has its own lockfile; update the runtime lockfile as well as the
backend lockfile when changing shared runtime dependencies.
CI uses Python 3.12 and uv 0.13.1. Lint commands use uv run --locked, and
backend images use uv sync --locked, so stale lockfiles fail instead of being
silently rewritten. Production excludes development dependencies; the test
runner explicitly installs the locked test extra. Container environments live
at /opt/venv so source bind mounts do not hide the installed dependencies.
To intentionally update dependencies, run uv lock --upgrade-package PACKAGE
inside the relevant Python project and commit the resulting lockfile. Use
uv lock after changing a manifest, then validate with uv lock --check.
JavaScript dependency policy
The frontend, documentation, and E2E projects each keep their own pnpm lockfile
and pnpm-workspace.yaml. All three use pnpm 12.14.0 and the same policy:
minimumReleaseAge: 10080means seven days, expressed in minutes (7 * 24 * 60). This applies to direct and transitive dependencies, including verification of locked versions during installation.- Strict release-age checks reject immature versions rather than automatically adding exceptions. Missing publication timestamps are also rejected.
trustPolicy: no-downgraderejects reduced publication trust compared with earlier-published releases, even across major-version lines. Narrow exceptions cover existing legacysemver@6.3.1and, in docs,detect-port@1.6.1releases without provenance. These exceptions do not cover future versions.blockExoticSubdeps: trueblocks Git and direct-tarball transitive sources.strictDepBuilds: truerequires an explicit build-script decision. Only frontendesbuildbuilds are approved;reteand the documentation'score-jsscripts are explicitly denied. Review new scripts before changingallowBuilds; do not globally enable dependency scripts.
For normal upgrades, use pnpm update inside the appropriate project and commit
the manifest, lockfile, and any reviewed policy changes. Renovate also waits
seven days before proposing npm updates.
The pnpm 12 lockfiles contain two YAML documents: package-manager dependencies first, then application dependencies. Keep both documents committed, and ensure any lockfile scanners read both rather than reporting an empty dependency graph.
Urgent security fixes
The security update workflow
runs daily and can be dispatched manually. It uses pnpm audit --fix=override to generate
overrides and exact patched-version minimumReleaseAgeExclude entries for
known vulnerability fixes, then opens a PR per affected JavaScript project.
All advisory severities are eligible for this automatic exception; it does not
auto-merge or bypass provenance checks, build approvals, or normal PR checks.
Registry errors fail the workflow, and a final audit reports any remaining
vulnerabilities, including those without a published fix.
Repository administrators must configure SECURITY_UPDATES_TOKEN as a bot token
with repository Contents: write and Pull requests: write permissions.
Unlike the default GITHUB_TOKEN, this allows the generated PRs to trigger CI.
Until configured, the workflow fails with an explicit setup error.
Renovate's immediate vulnerability PRs additionally require GitHub's dependency graph and Dependabot alerts to be enabled, with alert read access for Renovate. The pnpm audit workflow does not depend on those GitHub features.
For an immediate local fix:
pnpm audit --fix=override
pnpm install --no-frozen-lockfile
pnpm audit
Review and commit both the policy changes and lockfile. Remove obsolete release-age exceptions once the release has passed the seven-day window.