Average Joe

Don't be right. Be average.

A multiplayer quiz game for the web. Players score by guessing what the group will answer — not what's actually correct. After each round, the server computes the average of all answers and awards points to whoever came closest.

Requirements

• Python 3.10+
• A modern browser (desktop or mobile)
• 2+ players on the same network or internet (to play together)

Setup

Clone or download the project, then create a virtual environment and install dependencies:

cd average_joe
python3 -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt

Start the app

Development (local):

source .venv/bin/activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 in your browser.

LAN / Raspberry Pi (accessible from other devices on your network):

source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000

Open http://<your-machine-ip>:8000 from any device on the same network (e.g. http://192.168.1.42:8000).

One-liner (after setup):

.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000

Question UI test lab

Open http://127.0.0.1:8000/dev/test (or from the home page link) to troubleshoot all question types:

• Filter and pick any of the 165 questions
• Exercise the real answer widget (number, date, color, map, choice)
• Submit/lock/unlock to test disabled states
• Show mock reveal — preview the round-results overlay
• Test server scoring — POST your answer and see normalization + mock consensus

How to play

1. Create a lobby — enter your name and choose 5, 10, or 15 questions.
2. Share the link — copy the lobby URL and send it to friends. No account needed.
3. Wait for players — at least 2 players must join before the host can start.
4. Host starts the game — everyone is redirected to the game screen together.
5. Answer each question — you have 30 seconds. Questions use different UIs depending on type.
6. See the average — after each round, the crowd consensus is revealed and points are awarded.
7. Win — highest total score after all rounds wins.

Question types

Type	What you do
Number	Estimate a value (distance, cost, speed, temperature, age, weight, etc.) with slider + input
Date	Pick a year, month, or full date
Color	Choose a color with the picker or hex field
Location	Drop a pin on a world map
Choice	Pick one option from a list

Points are based on how close your answer is to the mean of all players' answers — never the real-world correct answer.

Tech stack

• Backend: FastAPI, WebSockets, uvicorn
• Frontend: Jinja2 templates, vanilla JavaScript
• Maps: Leaflet.js + OpenStreetMap (no API key)

Project structure

average_joe/
├── requirements.txt
├── README.md
└── app/
    ├── main.py              # HTTP routes + WebSocket endpoint
    ├── lobby_manager.py     # Create / join lobbies
    ├── game_engine.py       # Rounds, timer, scoring broadcast
    ├── models.py            # Lobby and player state
    ├── questions.json       # Built-in question bank (165 questions)
    ├── scoring/             # Consensus math per answer type
    ├── templates/           # HTML pages (home, lobby, game)
    └── static/              # CSS and JavaScript

Configuration

Setting	Default	Where
Port	8000	uvicorn --port flag
Round timer	30 seconds	app/game_engine.py
Questions per game	5, 10, or 15	chosen at lobby creation

Troubleshooting

externally-managed-environment when running pip
Use the virtual environment as shown in Setup — do not install packages system-wide.

address already in use
Another process is on port 8000. Stop it or use a different port:

uvicorn app.main:app --host 0.0.0.0 --port 8080

Friends can't connect on LAN
Make sure you started with --host 0.0.0.0 and that your firewall allows inbound traffic on the chosen port.

Map questions don't load
The app fetches map tiles from OpenStreetMap. The device running the browser needs internet access.