# cwalsh-developer/phunparty architecture

> Architecture diagram of the GitHub repository cwalsh-developer/phunparty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cwalsh-developer/phunparty
- Repository: https://github.com/cwalsh-developer/phunparty

## Overview

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: [`phunparty-backend/app/main.py`](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/main.py) (FastAPI app), [`phunparty-backend/app/database/dbCRUD.py`](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/database/dbCRUD.py) (Game and player data), [`phunparty-backend/app/websockets/game_handlers.py`](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/game_handlers.py) (Game event handlers), [`phunparty-backend/app/websockets/manager.py`](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/manager.py) (Connection and state manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Accounts and social"]
  node_auth["Authentication<br/>[authentication.py]"]
  node_social["Friends and notifications<br/>[friends.py]"]
  node_profiles["Profiles and privacy<br/>[profiles.py]"]
  node_presence["Presence<br/>[presence.py]"]
end

subgraph group_play["Game sessions"]
  node_api["FastAPI app<br/>[main.py]"]
  node_session_api["Game REST API<br/>[game.py]"]
  node_questions["Questions and scores<br/>[questions.py]"]
  node_join_queue["Session join queue"]
  node_progression["Game progression<br/>[game_logic.py]"]
end

subgraph group_realtime["Realtime gameplay"]
  node_ws_routes["WebSocket routes<br/>[routes.py]"]
  node_handlers["Game event handlers<br/>[game_handlers.py]"]
  node_modes["Game modes<br/>[game_modes.py]"]
  node_manager["Connection and state manager<br/>[manager.py]"]
  node_scheduler["Game scheduler<br/>[scheduler.py]"]
end

subgraph group_storage["Persistence and safeguards"]
  node_database[("PostgreSQL<br/>[config.py]")]
  node_crud["Game and player data<br/>[dbCRUD.py]"]
  node_fairplay["Fair-play records<br/>[fair_play_crud.py]"]
  node_security["Auth and request safeguards<br/>[dependencies.py]"]
  node_rls["Row-level security<br/>[rls.py]"]
end

node_players(("Players"))
node_host(("Host screen"))

node_players -->|"use REST and WebSocket"| node_api
node_host -->|"host sessions"| node_api
node_api -.->|"routes requests"| node_auth
node_api -.->|"routes requests"| node_session_api
node_api -.->|"serves gameplay sockets"| node_ws_routes
node_api -.->|"routes requests"| node_social
node_api -.->|"routes requests"| node_profiles
node_api -.->|"routes requests"| node_presence
node_api -.->|"routes requests"| node_questions
node_players -.->|"join by QR or PIN"| node_join_queue
node_session_api -.->|"uses data access"| node_crud
node_auth -->|"reads player data"| node_crud
node_auth -->|"checks credentials"| node_security
node_security -->|"sets player context"| node_rls
node_ws_routes -->|"dispatches events"| node_handlers
node_ws_routes -->|"manages connections"| node_manager
node_ws_routes -->|"uses game logic"| node_progression
node_handlers -->|"advances gameplay"| node_progression
node_handlers -->|"broadcasts events"| node_manager
node_handlers -->|"selects game modes"| node_modes
node_handlers -->|"reads and writes game data"| node_crud
node_handlers -->|"uses fair-play data"| node_fairplay
node_progression -->|"delegates database work"| node_crud
node_progression -->|"updates game phase"| node_manager
node_join_queue -->|"loads session data"| node_crud
node_join_queue -->|"uses session state"| node_manager
node_crud -.->|"queries PostgreSQL"| node_database
node_fairplay -->|"uses shared CRUD"| node_crud
node_scheduler -.->|"coordinates timing"| node_manager

click node_api "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/main.py"
click node_auth "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/authentication.py"
click node_social "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/friends.py"
click node_profiles "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/profiles.py"
click node_presence "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/presence.py"
click node_session_api "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/game.py"
click node_questions "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/questions.py"
click node_join_queue "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/queue/join_queue_manager.py"
click node_ws_routes "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/routes.py"
click node_handlers "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/game_handlers.py"
click node_modes "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/game_modes.py"
click node_progression "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/logic/game_logic.py"
click node_manager "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/manager.py"
click node_scheduler "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/scheduler.py"
click node_database "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/config.py"
click node_crud "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/database/dbCRUD.py"
click node_fairplay "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/database/fair_play_crud.py"
click node_security "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/dependencies.py"
click node_rls "https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/security/rls.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_social,node_profiles,node_presence,node_host toneBlue
class node_api,node_session_api,node_questions,node_join_queue,node_progression toneAmber
class node_ws_routes,node_handlers,node_modes,node_manager,node_scheduler toneMint
class node_database,node_crud,node_fairplay,node_security,node_rls toneRose
class node_players toneIndigo
```

## Components

### Accounts and social

- [Authentication](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/authentication.py): `phunparty-backend/app/routes/authentication.py`
- [Friends and notifications](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/friends.py): `phunparty-backend/app/routes/friends.py`
- [Profiles and privacy](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/profiles.py): `phunparty-backend/app/routes/profiles.py`
- [Presence](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/presence.py): `phunparty-backend/app/routes/presence.py`

### Game sessions

- [FastAPI app](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/main.py): `phunparty-backend/app/main.py`
- [Game REST API](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/game.py): `phunparty-backend/app/routes/game.py`
- [Questions and scores](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/routes/questions.py): `phunparty-backend/app/routes/questions.py`
- [Session join queue](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/queue/join_queue_manager.py): `phunparty-backend/app/queue/join_queue_manager.py`
- [Game progression](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/logic/game_logic.py): `phunparty-backend/app/logic/game_logic.py`

### Realtime gameplay

- [WebSocket routes](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/routes.py): `phunparty-backend/app/websockets/routes.py`
- [Game event handlers](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/game_handlers.py): `phunparty-backend/app/websockets/game_handlers.py`
- [Game modes](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/game_modes.py): `phunparty-backend/app/websockets/game_modes.py`
- [Connection and state manager](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/manager.py): `phunparty-backend/app/websockets/manager.py`
- [Game scheduler](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/websockets/scheduler.py): `phunparty-backend/app/websockets/scheduler.py`

### Persistence and safeguards

- [PostgreSQL](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/config.py): `phunparty-backend/app/config.py`
- [Game and player data](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/database/dbCRUD.py): `phunparty-backend/app/database/dbCRUD.py`
- [Fair-play records](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/database/fair_play_crud.py): `phunparty-backend/app/database/fair_play_crud.py`
- [Auth and request safeguards](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/dependencies.py): `phunparty-backend/app/dependencies.py`
- [Row-level security](https://github.com/cwalsh-developer/phunparty/blob/main/phunparty-backend/app/security/rls.py): `phunparty-backend/app/security/rls.py`

### Other components

- **Players**
- **Host screen**

## Connections

- Players → FastAPI app: use REST and WebSocket
- Host screen → FastAPI app: host sessions
- FastAPI app → Authentication: routes requests (evidence: `phunparty-backend/app/main.py`)
- FastAPI app → Game REST API: routes requests (evidence: `phunparty-backend/app/main.py`)
- FastAPI app → WebSocket routes: serves gameplay sockets (evidence: `phunparty-backend/app/main.py`)
- FastAPI app → Friends and notifications: routes requests (evidence: `phunparty-backend/app/main.py`)
- FastAPI app → Profiles and privacy: routes requests (evidence: `phunparty-backend/app/main.py`)
- FastAPI app → Presence: routes requests (evidence: `phunparty-backend/app/main.py`)
- FastAPI app → Questions and scores: routes requests (evidence: `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 (evidence: `phunparty-backend/app/routes/authentication.py`)
- Authentication → Auth and request safeguards: checks credentials (evidence: `phunparty-backend/app/routes/authentication.py`)
- Auth and request safeguards → Row-level security: sets player context (evidence: `phunparty-backend/app/dependencies.py`)
- WebSocket routes → Game event handlers: dispatches events (evidence: `phunparty-backend/app/websockets/routes.py`)
- WebSocket routes → Connection and state manager: manages connections (evidence: `phunparty-backend/app/websockets/routes.py`)
- WebSocket routes → Game progression: uses game logic (evidence: `phunparty-backend/app/websockets/routes.py`)
- Game event handlers → Game progression: advances gameplay (evidence: `phunparty-backend/app/websockets/game_handlers.py`)
- Game event handlers → Connection and state manager: broadcasts events (evidence: `phunparty-backend/app/websockets/game_handlers.py`)
- Game event handlers → Game modes: selects game modes (evidence: `phunparty-backend/app/websockets/game_handlers.py`)
- Game event handlers → Game and player data: reads and writes game data (evidence: `phunparty-backend/app/websockets/game_handlers.py`)
- Game event handlers → Fair-play records: uses fair-play data (evidence: `phunparty-backend/app/websockets/game_handlers.py`)
- Game progression → Game and player data: delegates database work (evidence: `phunparty-backend/app/logic/game_logic.py`)
- Game progression → Connection and state manager: updates game phase (evidence: `phunparty-backend/app/logic/game_logic.py`)
- Session join queue → Game and player data: loads session data (evidence: `phunparty-backend/app/queue/join_queue_manager.py`)
- Session join queue → Connection and state manager: uses session state (evidence: `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 (evidence: `phunparty-backend/app/database/fair_play_crud.py`)
- Game scheduler → Connection and state manager: coordinates timing
