# Team-Based Game System - Implementation Summary

## Overview
Successfully implemented a complete team-based game system replacing individual user accounts with 4 teams of 4 stations each.

## System Configuration

### Teams (4 Total)
- **Crocks**: Stations Crocks1, Crocks2, Crocks3, Crocks4
- **Hipps**: Stations Hipps1, Hipps2, Hipps3, Hipps4
- **Buffs**: Stations Buffs1, Buffs2, Buffs3, Buffs4
- **Tusks**: Stations Tusks1, Tusks2, Tusks3, Tusks4

### Win Requirements
Each team must achieve a number of wins equal to their active session count:
- 1 active session = 1 win required per challenge
- 2 active sessions = 2 wins required per challenge
- 3 active sessions = 3 wins required per challenge
- 4 active sessions = 4 wins required per challenge

## Database Schema

### New Tables

#### `teams`
- Stores the 4 team names (Crocks, Hipps, Buffs, Tusks)
- Pre-seeded on database initialization

#### `team_sessions`
- Tracks each active login session
- Links station name to team
- Records login and last active timestamps
- Unique constraint on (team_id, player_name) to prevent duplicate sessions

#### `team_progress`
- Team-level progress for each challenge
- Tracks win_count, required_wins (dynamic), completed status
- Stores secret_code_revealed when challenge completes
- Stores game_state for complex games (Hangman)

#### `team_collected_codes`
- Team-level code collection (CASE, FLOATIES, STUNGUN, ROPE)
- Replaces individual user code collection

#### `win_contributions`
- Optional tracking of which sessions contributed wins
- Useful for analytics and debugging

### Removed Tables
- `users` - No longer needed (no individual accounts)
- `progress` - Replaced by `team_progress`
- `collected_codes` - Replaced by `team_collected_codes`

## Authentication System

### Team Login (`POST /api/auth/team-login`)
**Request:**
```json
{
  "stationName": "Crocks1"
}
```

**Response:**
```json
{
  "message": "Login successful",
  "token": "JWT_TOKEN",
  "team": {
    "id": 1,
    "name": "Crocks",
    "sessionId": 1,
    "stationName": "Crocks1"
  }
}
```

### Session Management
- **New Login**: Creates new session entry, increments required_wins for all team challenges
- **Duplicate Login**: Reuses existing session (if Crocks1 logs in again), generates new token but doesn't increment required_wins
- **JWT Payload**: `{ teamId, teamName, sessionId, playerName, iat, exp }`
- **Token Expiry**: 24 hours

## Game Routes (All Updated)

### Common Pattern
All game routes now use team-based progress:
- `GET /api/{game}/progress` - Returns team progress including winCount, requiredWins, completed
- `POST /api/{game}/win` - Records a win for the team, auto-completes when winCount >= requiredWins
- Challenge auto-completes and reveals secret code when win threshold reached

### Updated Routes
- `/api/temple/*` (GetToTheTemple)
- `/api/mastermind/*`
- `/api/anaconda/*`
- `/api/hangman/*`

### Menu Route
- `GET /api/menu/progress` - Returns team info, all game progress, collected codes
- Response includes `team.activeSessions` for display

## Admin Endpoints

### Stats (`GET /api/admin/stats`)
Returns:
```json
{
  "teams": 4,
  "activeSessions": 4,
  "completedChallenges": 0,
  "teamSessions": [
    {"team_name": "Crocks", "session_count": 4},
    ...
  ]
}
```

### Reset (`POST /api/admin/reset`)
**Request:**
```json
{
  "password": "reset123"
}
```

**Actions:**
- Deletes all team_sessions
- Deletes all team_progress
- Deletes all team_collected_codes
- Deletes all win_contributions
- **Preserves**: Teams table (4 teams remain)

**Password**: Default `reset123`, override with `ADMIN_PASSWORD` environment variable

## Frontend Updates

### Login Page (`/public/index.html`)
- Dropdown with 16 station options (4 teams × 4 stations)
- Organized by optgroup for easy selection
- Removed username/password fields
- Removed registration

### Menu Page (`/public/menu.html`)
- Displays team name and active session count
- Shows progress as "Team Progress: X / Y wins"
- Updates required_wins dynamically based on active sessions

### API Client (`/public/js/api.js`)
- Updated to handle team authentication
- Added `recordXXXWin()` methods for each game
- Stores `team` in localStorage instead of `user`

## Testing Results

### Verified Functionality
✅ Team login with all 16 stations
✅ Duplicate login reuses existing session
✅ Required wins updates dynamically (1→4 as sessions added)
✅ Menu progress displays team info correctly
✅ Admin stats endpoint shows accurate data
✅ Admin reset clears all progress, preserves teams
✅ JWT authentication working correctly
✅ Session tracking and last_active_at updates

### Test Sequence
1. Logged in Crocks1 → Required wins: 1
2. Logged in Crocks2, Crocks3, Crocks4 → Required wins: 4
3. Menu shows "Team Crocks (4 active)"
4. All challenges show "0 / 4 wins"
5. Admin reset cleared all sessions successfully

## Environment Variables

### Required
- `JWT_SECRET`: Secret key for JWT signing (default: 'default-secret-key-change-this')
- `PORT`: Server port (default: 3000)

### Optional
- `DB_PATH`: Database file path (default: './game.db')
- `ADMIN_PASSWORD`: Admin reset password (default: 'reset123')

## File Changes

### Backend
- ✅ `database.js` - New team-based schema
- ✅ `middleware/auth.js` - Team authentication
- ✅ `routes/auth.js` - Team login endpoint
- ✅ `routes/admin.js` - New admin endpoints
- ✅ `routes/game.js` (temple) - Team progress
- ✅ `routes/mastermind.js` - Team progress
- ✅ `routes/anaconda.js` - Team progress
- ✅ `routes/hangman.js` - Team progress
- ✅ `routes/menu.js` - Team menu
- ✅ `server.js` - Registered admin routes

### Frontend
- ✅ `public/index.html` - Station dropdown
- ✅ `public/js/auth.js` - Team login handler
- ✅ `public/js/api.js` - Team API methods
- ✅ `public/js/menu.js` - Team display
- ✅ `public/menu.html` - Team header

### Backups Created
- `database-old.js` - Original user-based database
- `middleware/auth-old.js` - Original auth middleware
- `routes/*-old.js` - Original route files
- `game-old.db` - Original database file

## Usage Instructions

### Starting the Server
```bash
cd server
npm run dev  # Development with auto-restart
# or
npm start    # Production
```

### Accessing the Game
1. Navigate to `http://localhost:3010`
2. Select your station from dropdown
3. Click "Start Challenge"
4. Play games to contribute wins to your team
5. When team reaches required wins, challenge completes and reveals code

### Resetting Between Sessions
```bash
curl -X POST http://localhost:3010/api/admin/reset \
  -H "Content-Type: application/json" \
  -d '{"password":"reset123"}'
```

## Notes

- **Session Persistence**: Sessions remain active indefinitely (no expiration logic)
- **Token Expiry**: JWT tokens expire after 24 hours but sessions persist
- **Re-login**: Logging in again with same station name reuses session (doesn't increment required_wins)
- **Team Isolation**: Each team's progress is completely separate
- **Win Contributions**: Tracked in `win_contributions` table for analytics

## Future Enhancements (Optional)

1. **Session Timeout**: Add automatic session expiration after inactivity
2. **Team Leaderboard**: Show which team completed first
3. **Real-time Updates**: WebSocket updates when team members win
4. **Admin Dashboard**: Web UI for monitoring team progress
5. **Session Management**: Admin endpoint to manually remove/reset specific sessions