JobPrepWorks-OpenEdition: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) working in this repository.

What this is

JobPrep Works — Open Edition is a single-user, local, MIT-licensed interview prep tool: upload career documents, add target jobs, get an honest fit analysis, drill with adaptive mock interviews. It runs on the user's own machine against whichever LLM provider they configure.

There are no accounts, no authentication, no billing, and no plans. Every feature is always available; the user pays their provider directly. If you find yourself adding a gate, a tier, or a sign-in, stop — that's a different product.

README.md is the pitch and setup guide; llm.txt is the same for an agent.

Commands

No build step, no linter configured. Python + one hand-written stylesheet. There is a pytest suite with coverage.

scripts/setup                    # venv + requirements + .env (idempotent)
scripts/run                      # http://127.0.0.1:8000
scripts/run --reload             # auto-restart while editing

# fast, deterministic, no API calls — the right mode for UI and logic work
LLM_PROVIDER=mock scripts/run --reload

# tests: throwaway SQLite file + mock provider, no network, no key
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest                     # -q --cov=app, HTML in htmlcov/

# quick checks
python3 -m compileall -q app/
node --check app/static/app.js

Verifying changes safely. The app writes to a real database and real uploaded files. To exercise anything that writes, point it at a throwaway data directory with the mock provider — never at the user's data/:

JOBPREP_DATA_DIR=/tmp/jp-scratch LLM_PROVIDER=mock .venv/bin/python -c "
from starlette.testclient import TestClient
from app.main import app
with TestClient(app) as c: ...
"

init_db() runs from the FastAPI lifespan, which TestClient triggers; to drive services directly, call it yourself first.

Architecture

Stack: FastAPI + Jinja2 + HTMX (vendored at app/static/htmx.min.js) + SQLite. HTMX is the only client framework; there is no bundler. All CSS is one file (app/static/style.css); the only JS is app.js, theme.js, theme-boot.js, dictation.js, resume-print.js — hand-written, loaded defer.