How cwalsh-developer/phunparty works
PhunParty is a FastAPI backend for a shared-screen multiplayer party quiz: players join a host-led session, answer questions on phones, and see scores update in real time. The central gameplay path runs through WebSocket routing, game-mode handlers and game progression, with session data persisted in PostgreSQL. The repository also contains account, social, profile, notification, privacy and presence APIs. The README documents QR/PIN joining, custom games and music-guessing; those capabilities are shown, but their detailed implementation is not inferred from unsampled code.
Main entry points: main.py FastAPI app · dbCRUD.py Game and player data · game_handlers.py Game event handlers · manager.py Connection and state manager
Components 21
Accounts and social
- Authentication
phunparty-backend/app/routes/authentication.py - Friends and notifications
phunparty-backend/app/routes/friends.py - Profiles and privacy
phunparty-backend/app/routes/profiles.py - Presence
phunparty-backend/app/routes/presence.py
Game sessions
- FastAPI app
phunparty-backend/app/main.py - Game REST API
phunparty-backend/app/routes/game.py - Questions and scores
phunparty-backend/app/routes/questions.py - Session join queue
phunparty-backend/app/queue/join_queue_manager.py - Game progression
phunparty-backend/app/logic/game_logic.py
Realtime gameplay
- WebSocket routes
phunparty-backend/app/websockets/routes.py - Game event handlers
phunparty-backend/app/websockets/game_handlers.py - Game modes
phunparty-backend/app/websockets/game_modes.py - Connection and state manager
phunparty-backend/app/websockets/manager.py - Game scheduler
phunparty-backend/app/websockets/scheduler.py
Persistence and safeguards
- PostgreSQL
phunparty-backend/app/config.py - Game and player data
phunparty-backend/app/database/dbCRUD.py - Fair-play records
phunparty-backend/app/database/fair_play_crud.py - Auth and request safeguards
phunparty-backend/app/dependencies.py - Row-level security
phunparty-backend/app/security/rls.py
Other components
- Players
- Host screen
Connections 29
- Players → FastAPI app: use REST and WebSocket
- Host screen → FastAPI app: host sessions
- FastAPI app → Authentication: routes requests
phunparty-backend/app/main.py - FastAPI app → Game REST API: routes requests
phunparty-backend/app/main.py - FastAPI app → WebSocket routes: serves gameplay sockets
phunparty-backend/app/main.py - FastAPI app → Friends and notifications: routes requests
phunparty-backend/app/main.py - FastAPI app → Profiles and privacy: routes requests
phunparty-backend/app/main.py - FastAPI app → Presence: routes requests
phunparty-backend/app/main.py - FastAPI app → Questions and scores: routes requests
phunparty-backend/app/main.py - Players → Session join queue: join by QR or PIN
- Game REST API → Game and player data: uses data access
- Authentication → Game and player data: reads player data
phunparty-backend/app/routes/authentication.py - Authentication → Auth and request safeguards: checks credentials
phunparty-backend/app/routes/authentication.py - Auth and request safeguards → Row-level security: sets player context
phunparty-backend/app/dependencies.py - WebSocket routes → Game event handlers: dispatches events
phunparty-backend/app/websockets/routes.py - WebSocket routes → Connection and state manager: manages connections
phunparty-backend/app/websockets/routes.py - WebSocket routes → Game progression: uses game logic
phunparty-backend/app/websockets/routes.py - Game event handlers → Game progression: advances gameplay
phunparty-backend/app/websockets/game_handlers.py - Game event handlers → Connection and state manager: broadcasts events
phunparty-backend/app/websockets/game_handlers.py - Game event handlers → Game modes: selects game modes
phunparty-backend/app/websockets/game_handlers.py - Game event handlers → Game and player data: reads and writes game data
phunparty-backend/app/websockets/game_handlers.py - Game event handlers → Fair-play records: uses fair-play data
phunparty-backend/app/websockets/game_handlers.py - Game progression → Game and player data: delegates database work
phunparty-backend/app/logic/game_logic.py - Game progression → Connection and state manager: updates game phase
phunparty-backend/app/logic/game_logic.py - Session join queue → Game and player data: loads session data
phunparty-backend/app/queue/join_queue_manager.py - Session join queue → Connection and state manager: uses session state
phunparty-backend/app/queue/join_queue_manager.py - Game and player data → PostgreSQL: queries PostgreSQL
- Fair-play records → Game and player data: uses shared CRUD
phunparty-backend/app/database/fair_play_crud.py - Game scheduler → Connection and state manager: coordinates timing