Spoons Game Manager

Expert guidance for working with the Spoons codebase - a Next.js web application for managing campus-wide elimination games.

What This Skill Does

Provides Claude Code with deep context about the Spoons project architecture, stack, database schema, and development workflows. Enables efficient development of features for player management, target assignment algorithms, kill verification with GPS, and admin dashboards.

Project Overview

Spoons is a Next.js web app for managing campus-wide elimination games. Players are assigned targets to eliminate and submit kills with GPS verification for authenticity.

**Tech Stack:**

Development Commands

When working with this codebase, use these commands:

1. **Start development server:**

```bash

npm run dev

```

2. **Build for production:**

```bash

npm run build

```

3. **Run linting:**

```bash

npm run lint

```

4. **Auto-fix formatting:**

```bash

npm run format:fix

```

5. **After modifying Prisma schema:**

```bash

npx prisma generate

```

Key File Locations

When navigating the codebase, these are the critical files:

Database Schema

The database uses four main models:

1. **User** - Player records with game state

- `currentTarget` - FK to assigned target user

- `totalKills` - Kill counter

- `killed` - Boolean flag if player is eliminated

- `killedBy` - FK to eliminating user

- `gamemaster` - Admin access flag

2. **Kill** - Kill submission records

- GPS coordinates for verification

- Approval status tracking

- Timestamp and player references

3. **GameConfiguration** - Key-value configuration store

- Game status (active, paused, ended)

- `sign_ups_open` flag

- `ffa` (free-for-all mode) toggle

4. **TargetRules** - Target assignment constraints

- Defines rules for valid target assignments

- Used by `targetAssignment.ts` algorithm

Authentication System

Prisma 7 Specific Notes

**Important differences from older Prisma versions:**

1. Uses `@prisma/adapter-pg` driver adapter (not default connector)

2. Generated Prisma client lives at `prisma/generated/prisma/client`

3. Database URL configured in `prisma.config.ts`, **not** in `schema.prisma`

4. Always run `npx prisma generate` after schema modifications

**Import pattern:**

```typescript

import { prisma } from '@/lib/prisma';

```

Development Guidelines

When implementing features:

1. **Database Changes:**

- Modify `prisma/schema.prisma`

- Run `npx prisma generate`

- Test migrations carefully

2. **API Routes:**

- Place in `app/api/` directory

- Use Prisma client from `lib/prisma.ts`

- Validate authentication for protected endpoints

3. **Admin Features:**

- Build in `app/spoonmaster/` directory

- Always check `gamemaster` flag

- Use consistent admin UI patterns

4. **Target Assignment:**

- Core logic in `lib/targetAssignment.ts`

- Respect `TargetRules` constraints

- Test edge cases (small player pools, eliminations)

5. **GPS Verification:**

- Store coordinates with kill submissions

- Implement reasonable proximity checks

- Consider accuracy/error margins

Common Tasks

**Adding a new game configuration option:**

1. Add entry to `GameConfiguration` table

2. Update admin dashboard to expose control

3. Implement logic that reads the config value

**Modifying target assignment logic:**

1. Review existing algorithm in `lib/targetAssignment.ts`

2. Update `TargetRules` schema if adding constraints

3. Test thoroughly with various player counts

**Creating admin dashboard features:**

1. Add route under `app/spoonmaster/`

2. Verify `gamemaster` authentication

3. Use Prisma queries from `lib/prisma.ts`

Reference

For complete setup instructions, game rules, and architecture decisions, see `README.md` in the repository root.