Local development

Prerequisites

Use Node.js 22 or newer, pnpm 10 or newer and Docker Compose for PostgreSQL. Model-backed research also needs a supported provider credential and outbound access to the relevant source services.

The web application and worker are separate processes. Starting the website alone does not execute queued research.

Install and prepare the database

From the repository root:

cp .env.example .env.local
pnpm install
docker compose up -d postgres
pnpm db:migrate
pnpm db:seed

Edit .env.local before starting research. Set a strong AUTH_COOKIE_SECRET, verify DATABASE_URL and provide the credential required by the configured model provider. Never commit real credentials.

Migration, seed and worker scripts load .env.local when present. Exported environment variables take precedence. The Next.js development server also loads its environment files.

Start both processes

In one terminal:

pnpm dev

In another terminal:

pnpm worker

The default application address is http://localhost:3000. For a different development port:

pnpm dev --hostname 127.0.0.1 --port 3200

Keep browser and API requests on the same origin. A working page is not proof that PostgreSQL, source services or the model provider are configured correctly.

Project structure

src/app/                 Routes, layouts and API handlers
src/features/research/   Setup, progress, findings and report UI
src/features/docs/       Handbook navigation and Markdown rendering
src/shared/              Serializable contracts and boundary schemas
src/server/sources/      Real-source adapters and provenance
src/server/graph/        LangGraph orchestration and provider dispatch
src/server/gates/        Deterministic quality checks
src/server/runs/         Durable job service, worker and diagnostics
src/server/db/           PostgreSQL schema, repositories and migrations
src/server/reports/      Standalone PDF rendering
docs/handbook/           Markdown articles shown in this documentation

Run checks

pnpm typecheck
pnpm test
pnpm test:graph
pnpm lint

Browser checks need a running development app:

PLAYWRIGHT_BASE_URL=http://127.0.0.1:3200 pnpm test:e2e

Live source tests are opt-in and depend on external availability:

pnpm test:sources:live

Do not enable grid access merely to make a test pass: review the source’s reuse conditions first. Database integration suites also have explicit environment prerequisites; skipped tests are not successful verification of those integrations.

Build and maintain

Use pnpm build for a production build and pnpm start to run it. Keep the worker running separately with the same intended database and environment.

Add handbook content as Markdown under docs/handbook/ and register the article in src/features/docs/catalog.ts. Use level-two and level-three headings for the article contents links. Standard Markdown, GFM tables, blockquotes and fenced language-labelled code blocks are supported; raw HTML is not executed.