david/euchre_camp
Public Access
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

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

Browse Source
This commit is contained in:
David Gwilliam
2026-03-29 19:32:58 -07:00
parent 123df671f5
commit b82116b06a
2 changed files with 185 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+127
View File
@@ -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/
README.md
+46 -16
View File
@@ -1,27 +1,29 @@
# EuchreCamp
A comprehensive tournament management and partnership analytics system for the card game Euchre, built with Next.js, TypeScript, and Prisma.
A comprehensive tournament management and partnership analytics system for the card game Euchre.
## Overview
EuchreCamp is a full-stack web application that provides:
EuchreCamp is a full-stack web application built with Next.js 14+ and TypeScript that provides:
- **Tournament Management**: Create and manage round-robin, single elimination, double elimination, and Swiss-style tournaments
- **Partnership Analytics**: Track partnership performance, win rates, and Elo changes between players
- **Player Profiles**: Display individual player statistics and partnership breakdowns
- **Admin Dashboard**: Centralized management interface for tournaments, players, and matches
- **CSV Import**: Batch import match results from CSV files
- **Authentication & Authorization**: Role-based access control with player, tournament_admin, and club_admin roles
- **Home Page**: Public-facing landing page showing top players, recent tournaments, and club information
## Tech Stack
- **Framework**: Next.js 16 (App Router)
- **Framework**: Next.js 14+ (App Router)
- **Language**: TypeScript
- **Database**: Prisma ORM with SQLite
- **Styling**: Tailwind CSS
- **Authentication**: NextAuth.js
- **Authentication**: Better Auth
- **Form Handling**: React Hook Form + Zod validation
- **CSV Parsing**: PapaParse
- **Unit Testing**: Vitest
- **Acceptance Testing**: Playwright
## Project Structure
@@ -33,11 +35,17 @@ euchre_camp/
│ │ ├── auth/ # Authentication pages
│ │ ├── admin/ # Admin pages
│ │ ├── players/ # Player pages
│ │ ├── components/ # Shared components
│ │ └── lib/ # Utilities and configuration
│ └── types/ # TypeScript type definitions
│ │ ├── rankings/ # Rankings page
│ │ └── components/ # Shared components
│ ├── lib/ # Utilities and configuration
│ │ ├── auth.ts # Better Auth configuration
│ │ ├── prisma.ts # Prisma client
│ │ ├── permissions.ts # Authorization functions
│ │ └── elo-utils.ts # Elo calculation utilities
│ └── __tests__/ # Vitest and Playwright tests
├── prisma/ # Prisma schema and migrations
├── docs/ # Documentation
├── scripts/ # Utility scripts
└── public/ # Static assets
```
@@ -47,18 +55,20 @@ euchre_camp/
- [x] User registration with email confirmation
- [x] Login with credentials
- [x] Password reset flow
- [x] Session management with JWT
- [x] Role-based access control
- [x] Session management with Better Auth
- [x] Role-based access control (player, tournament_admin, club_admin)
### Epic 2: Player Profile & Analytics
- [x] Player profile page with statistics
- [x] Partnership performance table
- [x] Win rate and Elo display
- [x] Direct player stats (gamesPlayed, wins, losses)
### Epic 3: Rankings & Public Data
- [x] Player rankings page
- [x] Sortable rankings table
- [x] Public player profiles
- [x] Home page with top 10 players, recent tournament, club president
### Epic 4: Tournament Management
- [x] Create tournaments
@@ -76,8 +86,9 @@ euchre_camp/
### Prerequisites
- Node.js 22+
- Node.js 20+
- npm or yarn
- SQLite3
### Installation
@@ -94,7 +105,8 @@ euchre_camp/
3. **Set up the database**
```bash
npx prisma db push
npx prisma migrate deploy
npx prisma generate
```
4. **Start the development server**
@@ -108,8 +120,8 @@ Create a `.env` file:
```env
DATABASE_URL="file:./dev.db"
NEXTAUTH_SECRET="your-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"
BETTER_AUTH_SECRET="your-secret-key-here"
BETTER_AUTH_URL="http://localhost:3000"
```
## Usage
@@ -127,18 +139,30 @@ NEXTAUTH_URL="http://localhost:3000"
### Viewing Player Profiles
Navigate to `/players/[id]/profile` to see statistics, partnerships, and recent games.
### Home Page
Visit `/` to see:
- Top 10 players by Elo rating
- Most recent tournament with full match list
- Club president information
## API Endpoints
### Tournaments
- `GET /api/tournaments` - List all tournaments
- `POST /api/tournaments` - Create new tournament
- `GET /api/tournaments/[id]` - Get tournament details
### Matches
- `GET /api/matches` - List matches
- `POST /api/matches` - Create match result
- `POST /api/matches/upload` - Upload CSV with match results
### Authentication
- `POST /api/auth/sign-up/email` - Register new account
- `POST /api/auth/sign-in/email` - Login with email/password
- `POST /api/auth/sign-out` - Logout
### Users
- `GET /api/users/[id]/role` - Get user role
## Development
```bash
@@ -148,6 +172,12 @@ npm run dev
# Production build
npm run build
npm start
# Run unit tests
npm run test
# Run acceptance tests
npm run test:acceptance
```
## User Stories