docs: update README and add AGENTS.md for agent guidance

2026-03-29 19:32:58 -07:00
parent 123df671f5
commit b82116b06a
2 changed files with 185 additions and 28 deletions
@@ -0,0 +1,127 @@
+# EuchreCamp - Agent Guide
+
+This document provides guidance for AI agents working on the EuchreCamp project.
+
+## Project Overview
+
+EuchreCamp is a Next.js 14+ application for managing Euchre tournaments and tracking partnership analytics.
+
+### Key Technologies
+- **Next.js 14+** (App Router)
+- **TypeScript**
+- **Prisma ORM** (SQLite)
+- **Tailwind CSS**
+- **Better Auth** (Authentication)
+- **Vitest** (Unit Testing)
+- **Playwright** (Acceptance Testing)
+
+## Architecture Patterns
+
+### Authentication & Authorization
+- **Session Management**: Better Auth with cookie-based sessions
+- **Role-Based Access Control**: Three roles (player, tournament_admin, club_admin)
+- **Permission Functions**: Located in `src/lib/permissions.ts`
+- **Session Cache**: Disabled to avoid stale role data
+
+### Database Schema
+- **Players**: `id`, `name`, `currentElo`, `gamesPlayed`, `wins`, `losses`
+- **Users**: `id`, `email`, `role`, `playerId` (foreign key to players)
+- **Events**: Tournaments with `ownerId` for ownership tracking
+- **Matches**: Individual match results with `createdById` for tracking
+
+### Data Flow
+1. User authentication via Better Auth
+2. Session stored in HTTP-only cookies
+3. Permission checks read directly from database
+4. API routes enforce authorization
+
+## Common Tasks
+
+### Fixing Authentication Issues
+If users are redirected incorrectly or permissions aren't working:
+1. Check if cookie cache is disabled in `src/lib/auth.ts`
+2. Verify permission functions read from database, not session
+3. Ensure `getSession()` uses `disableCookieCache=true`
+
+### Adding New Features
+1. Create API route in `src/app/api/`
+2. Add permission checks using functions from `src/lib/permissions.ts`
+3. Create UI component in `src/app/` or `src/components/`
+4. Add tests in `src/__tests__/`
+5. Run tests: `npm run test` and `npm run test:acceptance`
+
+### Database Changes
+1. Edit `prisma/schema.prisma`
+2. Run `npx prisma migrate dev --name <migration-name>`
+3. Run `npx prisma generate`
+4. Update affected API routes and components
+
+### Running Tests
+- **Unit tests**: `npm run test`
+- **Acceptance tests**: `npm run test:acceptance`
+- **Specific test**: `npm run test:acceptance -- --grep "test name"`
+
+## Key Files
+
+### Configuration
+- `src/lib/auth.ts` - Better Auth configuration
+- `src/lib/permissions.ts` - Authorization functions
+- `src/lib/elo-utils.ts` - Elo calculation logic
+
+### API Routes
+- `src/app/api/auth/[[...all]]/route.ts` - Better Auth API
+- `src/app/api/tournaments/route.ts` - Tournament management
+- `src/app/api/matches/upload/route.ts` - CSV upload processing
+
+### UI Components
+- `src/components/Navigation.tsx` - Navigation with role-based links
+- `src/app/page.tsx` - Home page with top players, recent tournament, club president
+- `src/app/players/[id]/profile/page.tsx` - Player profile with stats
+
+### Tests
+- `src/__tests__/unit/permissions.test.ts` - Permission function tests
+- `src/__tests__/unit/elo.test.ts` - Elo calculation tests
+- `src/__tests__/e2e/global.setup.ts` - Test setup with admin user creation
+- `src/__tests__/e2e/home-page.test.ts` - Home page tests
+
+## Troubleshooting
+
+### Session Cache Issues
+**Problem**: Updated user roles don't reflect in session
+**Solution**: Ensure cookie cache is disabled and permission functions read from database
+
+### Test Failures
+**Problem**: Tests timing out or failing unexpectedly
+**Solution**:
+- Check if dev server is running
+- Verify database is accessible
+- Run tests with `--headed` to see browser
+
+### Database Conflicts
+**Problem**: Tests interfering with each other
+**Solution**: Tests run sequentially with `fullyParallel: false` and `workers: 1`
+
+## Conventions
+
+### Commit Messages
+- Use conventional commit format: `<type>: <description>`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+
+### Code Style
+- Use TypeScript for type safety
+- Prefer React Server Components for data fetching
+- Keep business logic in `src/lib/` directory
+- Write tests for new features
+
+### File Naming
+- Components: PascalCase (e.g., `Navigation.tsx`)
+- Utilities: camelCase (e.g., `elo-utils.ts`)
+- Tests: `.test.ts` or `.test.tsx` suffix
+
+## Resources
+
+- **Better Auth Docs**: https://better-auth.com/docs
+- **Next.js Docs**: https://nextjs.org/docs
+- **Prisma Docs**: https://www.prisma.io/docs
+- **Playwright Docs**: https://playwright.dev
+- **Vitest Docs**: https://vitest.dev/