Expert guidance for developing Spoons, a Next.js elimination game web app with GPS verification, target assignment, and admin dashboard
Expert guidance for working with the Spoons codebase - a Next.js web application for managing campus-wide elimination games.
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.
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:**
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
```
When navigating the codebase, these are the critical files:
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
**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';
```
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
**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`
For complete setup instructions, game rules, and architecture decisions, see `README.md` in the repository root.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/spoons-game-manager/raw