How apervmm/polyplace works
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: router.py WebSocket endpoint · connection_manager.py Connection manager · redis.py Redis client · handlers.py Placement handler
Components 22
React client
- App shell
packages/client/src/App.jsx - Auth UI
packages/client/src/Auth.jsx - Canvas client
packages/client/src/PolyPlace.jsx - Client config
packages/client/src/config.js
HTTP API
- Auth routes
packages/backend/app/api/v1/auth.py - Health route
packages/backend/app/api/v1/health.py - API router
packages/backend/app/api/v1/router.py - FastAPI lifecycle
packages/backend/app/main.py
Realtime board
- WebSocket endpoint
packages/backend/app/ws/router.py - Placement handler
packages/backend/app/ws/handlers.py - Connection manager
packages/backend/app/ws/connection_manager.py
Domain and storage
- Auth service
packages/backend/app/services/auth_service.py - User repository
packages/backend/app/repositories/user_repo.py - Board service
packages/backend/app/services/board_service.py - Pixel and action store
packages/backend/app/repositories/pixel_repo.py
Shared infrastructure
- JWT and passwords
packages/backend/app/core/security.py - Rate limiting
packages/backend/app/core/rate_limit.py - Backend settings
packages/backend/app/core/config.py - Redis client
packages/backend/app/core/redis.py
Other components
- Visitor
- PostgreSQL
- Redis
Connections 33
- Visitor → App shell: uses
README.md - App shell → Auth UI: shows
packages/client/src/App.jsx - App shell → Canvas client: renders
packages/client/src/App.jsx - Auth UI → Client config: reads
packages/client/src/Auth.jsx - Canvas client → Client config: reads
packages/client/src/PolyPlace.jsx - Auth UI → Auth routes: calls auth API
README.md - Canvas client → WebSocket endpoint: opens socket
README.md - FastAPI lifecycle → API router: mounts
packages/backend/app/main.py - FastAPI lifecycle → WebSocket endpoint: mounts
packages/backend/app/main.py - API router → Auth routes: routes to
packages/backend/app/api/v1/router.py - API router → Health route: routes to
packages/backend/app/api/v1/router.py - Auth routes → Auth service: calls
packages/backend/app/api/v1/auth.py - Auth routes → Rate limiting: checks
packages/backend/app/api/v1/auth.py - Auth service → JWT and passwords: hashes and signs
packages/backend/app/services/auth_service.py - Auth service → User repository: queries
packages/backend/app/services/auth_service.py - User repository → PostgreSQL: reads and writes
README.md - WebSocket endpoint → JWT and passwords: decodes token
packages/backend/app/ws/router.py - WebSocket endpoint → Board service: loads board
packages/backend/app/ws/router.py - WebSocket endpoint → Placement handler: dispatches placement
packages/backend/app/ws/router.py - WebSocket endpoint → Connection manager: manages socket
packages/backend/app/ws/router.py - Placement handler → Rate limiting: checks cooldowns
packages/backend/app/ws/handlers.py - Placement handler → Board service: places pixel
packages/backend/app/ws/handlers.py - Placement handler → Connection manager: publishes update
packages/backend/app/ws/handlers.py - Board service → Pixel and action store: loads and upserts
packages/backend/app/services/board_service.py - Board service → Redis client: reads and patches cache
packages/backend/app/services/board_service.py - Pixel and action store → PostgreSQL: reads and writes
README.md - Connection manager → Redis client: publishes and subscribes
packages/backend/app/ws/connection_manager.py - Connection manager → Canvas client: broadcasts updates
README.md - Rate limiting → Redis client: uses
packages/backend/app/core/rate_limit.py - Redis client → Redis: connects
packages/backend/app/core/redis.py - Backend settings → Redis client: configures
packages/backend/app/core/redis.py - FastAPI lifecycle → Connection manager: starts listener
packages/backend/app/main.py - Backend settings → JWT and passwords: configures
packages/backend/app/core/security.py