Tubes separates deterministic puzzle mechanics from responsive SVG/CSS pouring animations and keeps its campaign playable offline. A separate FastAPI backend adds identity, cloud progression, daily challenges, leaderboards, social features, and WebSocket matches. Match settlement, progression consumers, and season rollover are implemented, but their production launchers are absent from the checked-in deployment configuration.
Problem
A touch-friendly water-sort game needs precise move rules, responsive liquid animations, and reliable progress even without connectivity. Connected competition also needs server-verified results and synchronized multiplayer state.
Frontend work
- Deterministic pouring, undo, hints, fog-of-war, and win rules on a TanStack Store game model
- Responsive SVG/CSS liquid animations with staged tilt, stream, fill, settle, and celebration effects
- Local-first campaign progression with unlock rules, personal bests, resume state, and authenticated cloud merging
- Typed REST client with Zod runtime validation, bearer authentication, token refresh, and WebSocket match state
- Installable PWA with offline notices, reduced-motion interactions, Web Audio cues, haptic fallbacks, and Capacitor native-shell support
Backend & system work
- Versioned FastAPI APIs for progress, daily challenges, leaderboards, profiles, social features, clubs, custom puzzles, and competitions
- Server-authoritative puzzle and move-replay validation for campaign results and competitive matches
- Redis-backed WebSocket rooms with reconnect tickets, presence, distributed locks, ordered commands, and duplicate-command protection
- MongoDB repositories and indexes for identity, progression, ratings, match history, seasons, and shared content
- Passwordless email, Google, and Apple authentication with signed access tokens and rotating opaque refresh tokens
- Implemented Redis Stream consumers for match settlement and progression, plus season rollover; checked-in deployment configuration does not launch these workers
Key decisions
- Keep campaign gameplay functional offline through a local catalog and locally persisted progression
- Separate deterministic game mechanics from animated presentation, committing pours after animation completion
- Use TanStack Start in static SPA mode for PWA delivery and Capacitor native-shell integration
- Validate external data with Zod and verify competitive move sequences on the server
- Use MongoDB for durable records and Redis for realtime coordination, locks, caching, and event streams
Challenges
- Synchronizing liquid geometry, animation phases, input, audio, and authoritative move commits
- Keeping the mobile board stable as browser chrome changes the visible viewport
- Reconciling local and remote progression across level IDs, slugs, and independent move/time personal bests
- Maintaining ordered, idempotent multiplayer commands across reconnects and coordinating MongoDB records with Redis Stream processing
Tech stack
Frontend
- React 19
- TypeScript 6
- TanStack Start
- TanStack Router
- TanStack Query
- TanStack Store
- Vite 8
- CSS custom properties
- SVG animations
- Zod
Backend
- Python 3.14
- FastAPI
- Uvicorn
- Pydantic Settings
- PyJWT
- HTTPX
- Structlog
Data
- MongoDB
- PyMongo
- Redis
- Redis Streams
- Redis Pub/Sub
- localStorage
- sessionStorage
Infrastructure
- Cloudflare Pages
- vite-plugin-pwa
- Workbox
- Capacitor 7
- Docker
- Docker Compose
- Render Blueprint
- Mailpit
- SMTP
- Resend
Testing
- Vitest
- Playwright
- axe-core
- pytest
- pytest-asyncio
Tooling
- ESLint
- Prettier
- Husky
- Ruff
- Mypy
Browser APIs
- WebSocket
- Web Audio
- Vibration API
- Visual Viewport API
- Service Worker
- Web App Manifest
- matchMedia