brackt/AGENTS.md

AGENTS.md

Brackt.com is a fantasy sports drafting platform (React Router 7 + SSR, Socket.IO, PostgreSQL/DrizzleORM, Clerk auth).

Commands

npm run dev               # development with HMR
npm run typecheck         # TypeScript check
npm run lint              # lint check (run alongside typecheck after edits)
npm run db:generate       # generate Drizzle migration
npm run db:migrate        # apply migrations
npm run test:run          # unit tests (once)
npm run test:e2e:headless # Cypress E2E
npm run test:all          # everything

Code Search

Always use grepai instead of grep for searching code. grepai is the preferred search tool for this project.

It uses natural language semantic search, not exact text matching:

grepai search "where draft picks are validated"
grepai search "socket.io event handlers" --limit 5
grepai search "user authentication middleware" --path app/middleware

Critical Rules

Routes: Every new route file must also be registered in app/routes.ts — React Router 7 does not auto-discover files. Forgetting this causes a silent 404. See routing guide.

Database: Always query through app/models/ — never write Drizzle queries directly in route files.

Tests: Required for all new features. Do not consider a feature complete until tests pass. See testing guide.

Drizzle migrations: Never manually create migration SQL or edit _journal.json. Always use npm run db:generate. See database guide.

Reference Docs

• Architecture — server layout, DB layer, Socket.IO events
• Domain Models — draft system and sports data models
• Database — migration rules, scoring event date gotcha
• Routing — route registration, admin routes
• Testing — what tests are required and where they live
• Auth — Clerk patterns, ownership validation