128 lines
4.3 KiB
Markdown
128 lines
4.3 KiB
Markdown
# 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/
|