Quickstart

0. Prerequisites

Enable pnpm via corepack (ships with Node): corepack enable. Nothing installs globally — every dependency lives in per-project node_modules, resolved from the committed lockfile.

1. Clone and install

git clone https://github.com/abhay-yemekar/hirelens.git
cd hirelens
pnpm install

Ends with Done in a few minutes (~1 GB of packages on first run). If pnpm asks to approve build scripts, run pnpm approve-builds, select the listed packages, and re-run pnpm install.

2. Start the database

docker compose up -d
docker compose ps

Starts hirelens-postgres — Postgres 16 with pgvector, on port 5433 (deliberately offset from any local 5432). Status shows Up (healthy) after ~10 s.

3. Configure the environment

cp packages/db/.env.example packages/db/.env

Local-dev defaults work as-is. The BETTER_AUTH_SECRET in the example file is dev-only — generate a real one with openssl rand -base64 32 for anything beyond local experimentation. OAuth variables are optional; empty means disabled.

4. Migrate

pnpm --filter @hirelens/db db:migrate

Prints Migrations applied. and creates all tables: identity and organizations, jobs, rubrics, candidates, documents, scoring runs, scores, evidence, audit log.

5. Verify your setup

pnpm typecheck   # strict TypeScript across all 8 packages
pnpm test        # full suite (~89 tests)

The suite includes 3 orchestrator integration tests that need the database from step 2 — they create an org, a job, candidates, run a real scoring batch through the mock model, and recompute the hash-chained audit log from stored rows.

6. Run the apps

The fastest path is the one-command stack:

cp .env.example .env      # set BETTER_AUTH_SECRET
docker compose up --build -d
# web :3000 · api :4000 · postgres :5433

Migrations apply automatically on API boot. For daily development instead:

pnpm --filter @hirelens/api dev    # API on :4000
pnpm --filter @hirelens/web dev    # product UI on :3000
pnpm --filter @hirelens/docs dev   # docs site on :3002

Then: sign in / sign up → create an organization → create a job → upload resumes → score → review with evidence. LLM scoring needs HIRELENS_LLM_PROVIDER + HIRELENS_LLM_MODEL (+ key) in the API env; without them the server runs fine and scoring returns 503 llm_not_configured.

What “everything works” looks like

• docker compose ps → postgres Up (healthy)
• pnpm test → all packages green, including the 3 integration tests
• curl localhost:4000/api/health → {"ok":true}

Stuck? Every error we hit during development — and its fix — is in Troubleshooting.