# CLAUDE.md

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

## Commands

```bash
npm run dev               # development with HMR
npm run typecheck         # TypeScript check
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:

```bash
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](docs/agents/routing.md).

**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](docs/agents/testing.md).

**Drizzle migrations**: Never manually create migration SQL or edit `_journal.json`. Always use `npm run db:generate`. See [database guide](docs/agents/database.md).

## Reference Docs

- [Architecture](docs/agents/architecture.md) — server layout, DB layer, Socket.IO events
- [Domain Models](docs/agents/domain-models.md) — draft system and sports data models
- [Database](docs/agents/database.md) — migration rules, scoring event date gotcha
- [Routing](docs/agents/routing.md) — route registration, admin routes
- [Testing](docs/agents/testing.md) — what tests are required and where they live
- [Auth](docs/agents/auth.md) — Clerk patterns, ownership validation