euchre_camp/AGENTS.md

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

Admin User Creation

To create an admin user, use the provided scripts:

Option 1: Using Better Auth API (Recommended)

node scripts/create-admin-via-api.js

This creates the admin user david@dhg.lol with password adminadmin using Better Auth's internal API.

Option 2: Direct Database Creation

node scripts/create-admin-better-auth.js

This creates the admin user david@dhg.lol with password admin directly in the database.

List All Users:

node scripts/list-users.js

Update Admin Password:

node scripts/update-admin-password.js

This updates the admin password to adminadmin.

Note: All scripts currently create the user david@dhg.lol. If you need to create a different admin user, you can modify the email in the script or use Better Auth's CLI.

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

Database Provider Switching

The application supports both SQLite (default) and PostgreSQL databases.

To switch between databases:

# Switch to SQLite
npm run db:switch sqlite

# Switch to PostgreSQL  
npm run db:switch postgresql

To set up PostgreSQL:

npm run db:setup-postgres

Database Configuration:

• Edit .env file to set DATABASE_PROVIDER and DATABASE_URL
• For PostgreSQL, also set DATABASE_SHADOW_URL for migrations

Note: The database provider is automatically detected by Better Auth and Prisma.

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/