# Harbury Wildlife Quiz — App Specification

## What to build

A local-network multiplayer quiz web app called the **Harbury Wildlife Quiz**. It reads
`data.csv` to generate multiple-choice questions and serves them via Flask. There are two
roles: the **host** (whoever runs `quiz.py`) controls the game; **players** join from any
device on the same WiFi network.

## Files to create

| File | Purpose |
|------|---------|
| `quiz.py` | The Flask server — all routes, game logic, question generation |
| `templates/host.html` | Host/projector screen — current question, live answer count |
| `templates/player.html` | Player screen — join form, answer buttons, waiting states |

Do not modify `data.csv`.

## Screens

**Host screen** (`/host`)
- Shows the current question and its 4 answer options
- Shows a live count of how many players have answered
- Has a "Next question" button to advance
- Has a "Start game" button before the first question
- When all questions are done: shows a simple "Game over" message

**Player screen** (`/`)
- On arrival: a name entry form ("What's your name?") and a Join button
- Once joined and waiting: "Waiting for the host to start…"
- During a question: the question text and 4 answer buttons — one tap submits
- After answering: "Answer received — waiting for next question"
- When the game ends: shows the player their total score

## Question generation

Read `data.csv` on startup and generate questions using these patterns:

1. **"What type of animal is [Name]?"** — correct answer from `Type` column; wrong answers
   from other rows' `Type` values (deduplicated, shuffled)
2. **"What is the conservation status of [Name]?"** — correct answer from `Conservation
   Status`; wrong answers from other rows
3. **"Where does [Name] mainly live?"** — correct answer from `Main Habitat`; wrong answers
   from other rows
4. **"Which way is the [Name] population trending?"** — correct answer from `Population
   Trend`; wrong answers from other rows

Generate all valid questions from every row, shuffle the full list, then use the first N for
the game. Always present 4 options (1 correct + 3 wrong). If fewer than 3 distinct wrong
answers exist in that column, use what's available.

## API endpoints

| Method | Route | Purpose |
|--------|-------|---------|
| GET | `/api/state` | Returns full game state as JSON — polled every second by both screens |
| POST | `/api/join` | Player submits their name; returns player token |
| POST | `/api/answer` | Player submits an answer for the current question |
| POST | `/api/start` | Host starts the game |
| POST | `/api/next` | Host advances to the next question |

## Scoring

- Correct answer: +10 points
- Wrong answer: 0 points
- No negative scoring

## Game flow

1. Host opens `/host`, sees a waiting room and "Start game" button
2. Players visit the printed IP address, enter their name, join
3. Host starts the game — first question appears on both screens simultaneously
4. Players tap an answer on their phone
5. Host sees answer count update live; when ready, clicks "Next question"
6. Repeat until questions run out
7. Host screen shows "Game over"; players see their total score