Development

Start with the contributor guide. Coding agents must also read AGENTS.md. The system tour, design, and CI guide describe the architecture and quality gates.

Choose a setup

For the complete container stack, follow the README quick start. It supplies the API, worker, frontend, PostgreSQL and Valkey. Rebuild with docker compose build --no-cache after changing source or dependencies.

Native development, CI and the backend/worker image use Python 3.15. The backend package retains Python 3.12 as its minimum supported version and Ruff syntax target. The frontend uses Node.js 26 with npm. A modern browser and PostgreSQL 18/Valkey 9 are required for end-to-end execution.

Native development

Start from a fork/clone and run the infrastructure steps from the repository root. The shell examples assume a POSIX shell.

cp .env.example .env

Set a strong OPE_SECRET_KEY before connecting accounts and keep .env private. Only configure the providers you use; see configuration and provider setup.

Database and queue

The normal Compose stack does not publish PostgreSQL or Valkey ports. To use its images with a host-native API, start a separate development project with loopback-only ports:

docker compose --project-name ope-native-dev \
  --file docker-compose.yml --file - up --detach --wait postgres valkey <<'YAML'
services:
  postgres:
    ports:
      - "127.0.0.1:5432:5432"
  valkey:
    ports:
      - "127.0.0.1:6379:6379"
YAML

These are local development services, not a production exposure pattern. If those ports are occupied, use separate services/ports and update the connection URLs below. The project name isolates these resources from the regular stack.

API

Settings read .env from the process working directory. Create a backend-local copy so Alembic, the API and worker use the same configuration:

cd backend
cp ../.env .env

Set these values in backend/.env for the development services:

OPE_DATABASE_URL=postgresql+psycopg://ope:ope@127.0.0.1:5432/ope
OPE_VALKEY_URL=redis://127.0.0.1:6379/0
OPE_FRONTEND_URL=http://localhost:5173

Then, from backend/:

python3.15 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python -m alembic upgrade head
uvicorn app.main:app --reload --no-access-log

The API is available at http://localhost:8000, with interactive documentation at /docs and a basic availability check at /health. Provider callbacks still need the exact registered URLs in the connection guide.

Worker

In another shell, start from the repository root:

cd backend
. .venv/bin/activate
arq app.jobs.worker.WorkerSettings

Keep the worker and API in the same working directory so they use the same settings and snapshot path. Scheduled sync, cleanup and durable background work need the worker, not just a healthy API.

Frontend

From the repository root in another shell:

cd frontend
npm ci
npm run dev

Open http://localhost:5173. Vite proxies /api, /health and /share to the local API. Provider secrets belong in the backend environment, never Vite code.

Stop and debug

Stop native API, worker and Vite processes with Ctrl+C in their own terminals. From the repository root, stop the development infrastructure with:

docker compose --project-name ope-native-dev down

Normal shutdown keeps its database volume. Do not use --volumes unless you intend to erase that project's data.

For connection failures, check the API/worker terminal output, active working directory, URLs and whether Alembic migrations completed. For container deployments, inspect docker compose logs --tail=100 backend worker. Redact credentials and personal data before sharing diagnostics.

Checks and synthetic fixtures

Run Ruff, pytest, dependency checks, API/type generation, TypeScript and production builds using the exact commands in CI. Run focused tests first, then the checks for every affected surface. There is no configured frontend unit-test or dedicated accessibility-audit runner; do not substitute a fictitious npm test.

Backend provider tests use injected httpx.MockTransport fixtures for official APIs and an in-memory client_factory for YouTube Music. Use synthetic data only; see ADR 0002. Do not validate migrations against real libraries as part of a test run.

For UI changes, verify keyboard operation, focus, narrow layouts and affected workflows with mocked accounts. Follow accessibility verification. Regenerate the FastAPI and TypeScript contracts together after public API changes, as described in the CI guide.

For documentation changes, use a virtual environment from the repository root:

python3.15 -m venv .venv
. .venv/bin/activate
python -m pip install --requirement requirements-docs.txt
python -m mkdocs build --strict

Repository layout and extension points

Path Contents
backend/ FastAPI routes, providers, matching, jobs, database and pytest tests
frontend/ React SPA, product styles and generated API client types
openapi/ Vendored Open Playlist specification and generated engine contract
docs/ User/developer guides, architecture, ADRs and site assets

The frontend and backend are hard-separated. The frontend communicates through the backend's generated OpenAPI contract.

To add a provider, implement ProviderAdapter under backend/app/providers/<name>/adapter.py, declare a CapabilityDescriptor, register it, and pass backend/tests/conformance/. Keep matching in core services, not adapters. See the provider contract and backend guide.

Build and distribution

The current GitHub releases provide source archives, not a desktop installer or published application container image. Build the existing Compose images locally with docker compose build --no-cache; the frontend's standalone production output is frontend/dist/ after npm run build.

The container CI check builds and smoke-tests the actual stack, including database upgrades. Documentation builds use requirements-docs.txt and MkDocs; the Pages workflow deploys only from main or manual dispatch, not pull requests.

There is no separate release/signing script to invoke. Do not create tags, GitHub releases, image pushes or signing claims merely to validate documentation or local builds.