Soc Ops is a fast, in-person social bingo game built with FastAPI, Jinja2, and HTMX.
Players walk around, meet people, and mark squares like "has lived in another country" or "plays an instrument". First line wins.
Most icebreakers feel forced. Soc Ops turns introductions into a lightweight game that gets everyone talking in minutes.
This repository is also a practical workshop for agent-assisted development with GitHub Copilot.
- Start a new game in one click
- Generate a shuffled 5x5 board with a centered free space
- Toggle squares as you meet matching people
- Detect bingo across rows, columns, and diagonals
- Show a bingo modal and keep playing after dismissing it
- Run fully server-rendered interactions via HTMX partial swaps
- Backend: FastAPI
- Templates: Jinja2
- Frontend behavior: HTMX
- Session state: Starlette SessionMiddleware + in-memory game sessions
- Tooling: uv, Ruff, pytest
- Python: 3.13+
- Install prerequisites: Python 3.13+ and uv
- Sync dependencies:
uv sync- Run quality checks:
uv run ruff check .
uv run pytest- Start the app:
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000- Open in your browser:
- App routes: app/main.py
- Session orchestration: app/game_service.py
- Core game logic: app/game_logic.py
- Immutable models: app/models.py
- HTML templates and HTMX partials: app/templates/
- Static assets: app/static/
- API and logic tests: tests/
Follow the guided workshop to learn setup, context engineering, design workflows, and multi-agent development:
| Part | Title |
|---|---|
| 00 | Overview and Checklist |
| 01 | Setup and Context Engineering |
| 02 | Design-First Frontend |
| 03 | Custom Quiz Master |
| 04 | Multi-Agent Development |
Offline docs are available in workshop/.
Contributions are welcome. Please review:
- CONTRIBUTING.md
- CODE_OF_CONDUCT.md
- SECURITY.md
This project is licensed under the MIT License. See LICENSE.