badman AGENTS.md

Repository guidance (Claude Code, Cursor, AI)

This file (AGENTS.md) is the single source of truth for AI-assisted development in this repo.

CLAUDE.md is a symbolic link to AGENTS.md in the repository root (CLAUDE.md → AGENTS.md). Tools that read either path see the same content. Edit AGENTS.md only—do not replace the symlink with a duplicate file, or Claude Code and Cursor will drift apart.

Environment Setup

Required for dev and AI-assisted scripts:

# pnpm is pinned via the packageManager field; corepack provides it
corepack enable

# Copy .env.local if it doesn't exist (contains LINEAR_API_KEY for issue creation)
cp .env.local.example .env.local  # or manually source .env before running scripts

# Load environment in your shell (add to ~/.zshrc or ~/.bashrc for persistence):
source /path/to/badman/.env.local

Variables needed for scripts:

• LINEAR_API_KEY — for creating Linear issues from CLI

Project Overview

Competitive badminton management platform (Badman). Backend-only Turborepo + pnpm monorepo with NestJS (backend API + workers), Sequelize ORM (PostgreSQL), Apollo GraphQL (code-first), Bull queues (Redis).

The frontend lives in a separate repository (Constitution v2.0.0, Principle V). The legacy Angular frontend was removed from this repo; do not reintroduce frontend code here.

Orchestration: Turborepo (turbo.json) over pnpm workspaces (pnpm-workspace.yaml). Deployable apps live under apps/; shared libraries are compiled internal packages under packages/, imported as @badman/<name> and resolved via workspace:* dependencies + each package's exports map (no tsconfig path aliases).

Common Commands

# Install (frozen, what CI runs)
pnpm install --frozen-lockfile

# Start Docker containers (PostgreSQL, Redis, pgAdmin)
npm run docker:up

# Serve API + sync worker in dev (watch mode; builds dependencies first)
pnpm start:server          # = turbo run dev --filter=api --filter=worker-sync

# Serve the ranking workers
pnpm start:ranking

# Build everything / one project (dependencies build first via ^build)
pnpm build                 # = turbo run build
pnpm turbo run build --filter=api
pnpm turbo run build --filter=@badman/backend-graphql

# Run tests for a specific package
pnpm turbo run test --filter=@badman/backend-graphql
# Or run jest directly inside the package (deps must be built once first):
cd packages/backend-graphql && pnpm test

# Run only affected tests (vs a base; CI sets TURBO_SCM_BASE to the PR base)
pnpm turbo run test --affected

# Run integration tests against the dev postgres (docker-compose.dev.yml)
# Off by default; set RUN_INTEGRATION_TESTS=1 to opt in. Files named *.integration.spec.ts
# guard themselves with that env var, so a normal test run skips them.
npm run docker:up
cd packages/backend-graphql && RUN_INTEGRATION_TESTS=1 pnpm exec jest \
  --testPathPattern <feature>.integration

# Lint a specific package
pnpm turbo run lint --filter=@badman/backend-graphql

# Run database migrations
npx sequelize-cli db:migrate

# Format code
prettier --write .
prettier --check .

# Seed test data
npm run seed:test-data

# Full coverage report (all packages, no DB required)
# Produces: text summary per package + lcov.info under root coverage/
pnpm test:coverage:all     # = turbo run test -- --coverage

# Update coverage threshold after adding tests:
# 1. Run: pnpm test:coverage:all
# 2. Find the "Lines %" for backend-graphql in the output
# 3. Round down to nearest 5%
# 4. Edit packages/backend-graphql/jest.config.ts → coverageThreshold.global.*
# 5. Commit the updated jest.config.ts

# Cache notes: turbo caches build/test/lint per package. A no-change re-run is
# near-instant (>>> FULL TURBO). To force re-execution: append --force.