This is the repository for the CFBD API v2, hosted at api.CollegeFootballData.com. The API is built with Node.js, TypeScript, Express, TSOA, and PostgreSQL.

This repo uses pnpm for dependency management.

pnpm install
pnpm dev

pnpm dev starts the API with hot reload and regenerates TSOA routes/specs as controller files change.

pnpm build         # generate TSOA routes/specs and compile TypeScript
pnpm test          # run all Jest tests
pnpm lint          # run ESLint
pnpm prettify      # format code with Prettier
pnpm docs:check    # verify required docs, AGENTS.md size, and local doc links
pnpm build:db      # regenerate Kysely database types

• AGENTS.md: short operating guide for Codex and other agents.
• ARCHITECTURE.md: request flow, source layout, data access, auth/quotas, generated outputs, tests, and release/deploy behavior.
• docs/index.md: repository knowledge-base index.
• docs/QUALITY_SCORE.md: documentation quality snapshot and cleanup queue.

This project uses TSOA to generate OpenAPI documentation and Express routes from TypeScript controllers. Data access is primarily implemented with Kysely, with existing pg-promise usage for auth and legacy paths.

Feature code lives under src/app/<domain>/ and follows a controller.ts, service.ts, types.ts pattern. See ARCHITECTURE.md before changing request flow, authentication, quota behavior, generated OpenAPI output, or deployment behavior.

Semantic versioning is handled by semantic-release based on conventional commit messages. commitlint is used in the release workflow to enforce commit message formatting.