flight-finder AGENTS.md

AGENTS.md

Guidance for AI coding agents working on Flight Finder, a self-hosted flight price tracker. This is the cross-tool entry point. See CLAUDE.md for the deeper conventions and the "Altitude" design system, README.md for the product overview, and API.md for the runtime HTTP API you can call against a running instance.

Stack

TypeScript (strict) monorepo on Node >= 22, npm workspaces. Next.js 16 (App Router, React 19) web app, Prisma 7 over PostgreSQL 16, Redis 7 for caching and rate limiting, Playwright for scraping, Vitest for tests. Secrets come from Doppler, never .env files.

Setup

npm install
docker compose up -d db redis      # or: make setup
npm run db:push                    # apply the Prisma schema
npm run db:generate                # generate the Prisma client
npm run dev                        # Next.js web app on http://localhost:3003

make dev wraps the database, Redis, and dev-server steps.

Checks (run before every commit and PR)

npm run ci         # lint + typecheck + test + build (web) + build (cli)
# or individually:
npm run lint       # ESLint, both workspaces, --max-warnings 0
npm run typecheck  # tsc strict, both workspaces
npm run test       # Vitest, both workspaces

npm run ci must pass before you push; GitHub Actions runs the same gate. Linting is zero-warnings and typecheck is strict (noUncheckedIndexedAccess).

Monorepo layout

• apps/web: the Next.js app and API backend (@flight-finder/web). Prisma schema at apps/web/prisma/schema.prisma; core logic under apps/web/src/lib/ (auth, prisma, redis, notifications, scraper).
• packages/cli: the Ink/React terminal UI (@flight-finder/cli). It reuses the scraper from apps/web via relative imports.
• apps/desktop: the Tauri (Rust) launcher. It is not an npm workspace and is built and versioned on its own.

All four version points (root, apps/web, packages/cli, apps/desktop) are kept in lockstep; the /create-release flow bumps them together.