# apervmm/polyplace architecture

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

- Interactive diagram: https://gitdiagram.com/apervmm/polyplace
- Repository: https://github.com/apervmm/polyplace

## Overview

PolyPlace is a real-time multiplayer pixel canvas. Users can watch the board without signing in; authenticated users can register or log in, then place pixels over WebSocket. The backend validates and rate-limits placements, persists them, updates the board cache, and uses Redis pub/sub to distribute updates across API instances. The map also includes the documented health endpoint and client canvas/auth flows. Legacy Node services are excluded. Relationships for unsampled modules rely on SOURCE INDEX references or README documentation; they are not claims of having inspected those implementations.

Main entry points: [`packages/backend/app/ws/router.py`](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/router.py) (WebSocket endpoint), [`packages/backend/app/ws/connection_manager.py`](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/connection_manager.py) (Connection manager), [`packages/backend/app/core/redis.py`](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/redis.py) (Redis client), [`packages/backend/app/ws/handlers.py`](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/handlers.py) (Placement handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_app["App shell<br/>[App.jsx]"]
  node_auth_ui["Auth UI<br/>[Auth.jsx]"]
  node_canvas["Canvas client<br/>[PolyPlace.jsx]"]
  node_client_config["Client config<br/>[config.js]"]
end

subgraph group_api["HTTP API"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_health_route["Health route<br/>[health.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_app_entry["FastAPI lifecycle<br/>[main.py]"]
end

subgraph group_realtime["Realtime board"]
  node_ws_router["WebSocket endpoint<br/>[router.py]"]
  node_place_handler["Placement handler<br/>[handlers.py]"]
  node_connections["Connection manager"]
end

subgraph group_domain["Domain and storage"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_user_repo["User repository<br/>[user_repo.py]"]
  node_board_service["Board service<br/>[board_service.py]"]
  node_pixel_repo["Pixel and action store<br/>[pixel_repo.py]"]
end

subgraph group_infrastructure["Shared infrastructure"]
  node_security["JWT and passwords<br/>[security.py]"]
  node_rate_limit["Rate limiting<br/>[rate_limit.py]"]
  node_config["Backend settings<br/>[config.py]"]
  node_redis_client["Redis client<br/>[redis.py]"]
end

node_visitor(("Visitor"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_visitor -->|"uses"| node_client_app
node_client_app -->|"shows"| node_auth_ui
node_client_app -->|"renders"| node_canvas
node_auth_ui -->|"reads"| node_client_config
node_canvas -->|"reads"| node_client_config
node_auth_ui -->|"calls auth API"| node_auth_routes
node_canvas -->|"opens socket"| node_ws_router
node_app_entry -->|"mounts"| node_api_router
node_app_entry -->|"mounts"| node_ws_router
node_api_router -->|"routes to"| node_auth_routes
node_api_router -->|"routes to"| node_health_route
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"checks"| node_rate_limit
node_auth_service -->|"hashes and signs"| node_security
node_auth_service -->|"queries"| node_user_repo
node_user_repo -->|"reads and writes"| node_postgres
node_ws_router -->|"decodes token"| node_security
node_ws_router -->|"loads board"| node_board_service
node_ws_router -->|"dispatches placement"| node_place_handler
node_ws_router -->|"manages socket"| node_connections
node_place_handler -->|"checks cooldowns"| node_rate_limit
node_place_handler -->|"places pixel"| node_board_service
node_place_handler -->|"publishes update"| node_connections
node_board_service -->|"loads and upserts"| node_pixel_repo
node_board_service -->|"reads and patches cache"| node_redis_client
node_pixel_repo -->|"reads and writes"| node_postgres
node_connections -->|"publishes and subscribes"| node_redis_client
node_connections -->|"broadcasts updates"| node_canvas
node_rate_limit -->|"uses"| node_redis_client
node_redis_client -->|"connects"| node_redis
node_config -->|"configures"| node_redis_client
node_app_entry -->|"starts listener"| node_connections
node_config -->|"configures"| node_security

click node_client_app "https://github.com/apervmm/polyplace/blob/main/packages/client/src/App.jsx"
click node_auth_ui "https://github.com/apervmm/polyplace/blob/main/packages/client/src/Auth.jsx"
click node_canvas "https://github.com/apervmm/polyplace/blob/main/packages/client/src/PolyPlace.jsx"
click node_client_config "https://github.com/apervmm/polyplace/blob/main/packages/client/src/config.js"
click node_auth_routes "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/api/v1/auth.py"
click node_health_route "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/api/v1/health.py"
click node_api_router "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/api/v1/router.py"
click node_auth_service "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/services/auth_service.py"
click node_security "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/security.py"
click node_user_repo "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/repositories/user_repo.py"
click node_ws_router "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/router.py"
click node_place_handler "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/handlers.py"
click node_board_service "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/services/board_service.py"
click node_pixel_repo "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/repositories/pixel_repo.py"
click node_connections "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/connection_manager.py"
click node_rate_limit "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/rate_limit.py"
click node_config "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/config.py"
click node_redis_client "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/redis.py"
click node_app_entry "https://github.com/apervmm/polyplace/blob/main/packages/backend/app/main.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_client_app,node_auth_ui,node_canvas,node_client_config toneBlue
class node_auth_routes,node_health_route,node_api_router,node_app_entry,node_postgres,node_redis toneAmber
class node_ws_router,node_place_handler,node_connections toneMint
class node_auth_service,node_user_repo,node_board_service,node_pixel_repo toneRose
class node_security,node_rate_limit,node_config,node_redis_client,node_visitor toneIndigo
```

## Components

### React client

- [App shell](https://github.com/apervmm/polyplace/blob/main/packages/client/src/App.jsx): `packages/client/src/App.jsx`
- [Auth UI](https://github.com/apervmm/polyplace/blob/main/packages/client/src/Auth.jsx): `packages/client/src/Auth.jsx`
- [Canvas client](https://github.com/apervmm/polyplace/blob/main/packages/client/src/PolyPlace.jsx): `packages/client/src/PolyPlace.jsx`
- [Client config](https://github.com/apervmm/polyplace/blob/main/packages/client/src/config.js): `packages/client/src/config.js`

### HTTP API

- [Auth routes](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/api/v1/auth.py): `packages/backend/app/api/v1/auth.py`
- [Health route](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/api/v1/health.py): `packages/backend/app/api/v1/health.py`
- [API router](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/api/v1/router.py): `packages/backend/app/api/v1/router.py`
- [FastAPI lifecycle](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/main.py): `packages/backend/app/main.py`

### Realtime board

- [WebSocket endpoint](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/router.py): `packages/backend/app/ws/router.py`
- [Placement handler](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/handlers.py): `packages/backend/app/ws/handlers.py`
- [Connection manager](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/ws/connection_manager.py): `packages/backend/app/ws/connection_manager.py`

### Domain and storage

- [Auth service](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/services/auth_service.py): `packages/backend/app/services/auth_service.py`
- [User repository](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/repositories/user_repo.py): `packages/backend/app/repositories/user_repo.py`
- [Board service](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/services/board_service.py): `packages/backend/app/services/board_service.py`
- [Pixel and action store](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/repositories/pixel_repo.py): `packages/backend/app/repositories/pixel_repo.py`

### Shared infrastructure

- [JWT and passwords](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/security.py): `packages/backend/app/core/security.py`
- [Rate limiting](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/rate_limit.py): `packages/backend/app/core/rate_limit.py`
- [Backend settings](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/config.py): `packages/backend/app/core/config.py`
- [Redis client](https://github.com/apervmm/polyplace/blob/main/packages/backend/app/core/redis.py): `packages/backend/app/core/redis.py`

### Other components

- **Visitor**
- **PostgreSQL**
- **Redis**

## Connections

- Visitor → App shell: uses (evidence: `README.md`)
- App shell → Auth UI: shows (evidence: `packages/client/src/App.jsx`)
- App shell → Canvas client: renders (evidence: `packages/client/src/App.jsx`)
- Auth UI → Client config: reads (evidence: `packages/client/src/Auth.jsx`)
- Canvas client → Client config: reads (evidence: `packages/client/src/PolyPlace.jsx`)
- Auth UI → Auth routes: calls auth API (evidence: `README.md`)
- Canvas client → WebSocket endpoint: opens socket (evidence: `README.md`)
- FastAPI lifecycle → API router: mounts (evidence: `packages/backend/app/main.py`)
- FastAPI lifecycle → WebSocket endpoint: mounts (evidence: `packages/backend/app/main.py`)
- API router → Auth routes: routes to (evidence: `packages/backend/app/api/v1/router.py`)
- API router → Health route: routes to (evidence: `packages/backend/app/api/v1/router.py`)
- Auth routes → Auth service: calls (evidence: `packages/backend/app/api/v1/auth.py`)
- Auth routes → Rate limiting: checks (evidence: `packages/backend/app/api/v1/auth.py`)
- Auth service → JWT and passwords: hashes and signs (evidence: `packages/backend/app/services/auth_service.py`)
- Auth service → User repository: queries (evidence: `packages/backend/app/services/auth_service.py`)
- User repository → PostgreSQL: reads and writes (evidence: `README.md`)
- WebSocket endpoint → JWT and passwords: decodes token (evidence: `packages/backend/app/ws/router.py`)
- WebSocket endpoint → Board service: loads board (evidence: `packages/backend/app/ws/router.py`)
- WebSocket endpoint → Placement handler: dispatches placement (evidence: `packages/backend/app/ws/router.py`)
- WebSocket endpoint → Connection manager: manages socket (evidence: `packages/backend/app/ws/router.py`)
- Placement handler → Rate limiting: checks cooldowns (evidence: `packages/backend/app/ws/handlers.py`)
- Placement handler → Board service: places pixel (evidence: `packages/backend/app/ws/handlers.py`)
- Placement handler → Connection manager: publishes update (evidence: `packages/backend/app/ws/handlers.py`)
- Board service → Pixel and action store: loads and upserts (evidence: `packages/backend/app/services/board_service.py`)
- Board service → Redis client: reads and patches cache (evidence: `packages/backend/app/services/board_service.py`)
- Pixel and action store → PostgreSQL: reads and writes (evidence: `README.md`)
- Connection manager → Redis client: publishes and subscribes (evidence: `packages/backend/app/ws/connection_manager.py`)
- Connection manager → Canvas client: broadcasts updates (evidence: `README.md`)
- Rate limiting → Redis client: uses (evidence: `packages/backend/app/core/rate_limit.py`)
- Redis client → Redis: connects (evidence: `packages/backend/app/core/redis.py`)
- Backend settings → Redis client: configures (evidence: `packages/backend/app/core/redis.py`)
- FastAPI lifecycle → Connection manager: starts listener (evidence: `packages/backend/app/main.py`)
- Backend settings → JWT and passwords: configures (evidence: `packages/backend/app/core/security.py`)
