How kash/cubedesk works
1. CubeDesk is a full-stack TypeScript/JavaScript monorepo built around a browser UI, a Node server, a relational database, and a small amount of shared code used on both sides. The product is a speedcubing platform: timer, solve logging, stats, trainer, and online head-to-head play.
2. The client is a React app organized by feature domains rather than by technical layer. Top-level areas include timer, solves, stats, trainer, play/match, profile/account, community, settings, landing, login, and admin. Most UI behavior is implemented in client/components, with styling split into co-located SCSS files.
3. App-wide client state is split across Redux-like reducers and action modules, with custom hooks for accessing stores, auth, settings, SSR state, sockets, and local databases. The layout layer handles routing, header/nav, loading/offline/demo restrictions, theme selection, and initialization before the feature pages render.
4. A major architectural boundary on the client is local persistence. The client/db area uses LokiJS-backed databases for sessions, solves, settings, and trainer data, which lets the app keep time logs and preferences locally and then synchronize or transform them into server-backed data when needed.
5. The server exposes two main interaction styles. First, there is a GraphQL layer defined by schema.graphql, server/schemas, and server/resolvers, which is the primary API for application data. Second, there are REST-style endpoints under server/api for concerns like auth, forgotten passwords, profile/media operations, smart-device hooks, notifications, and webhooks.
6. Server data modeling is centered on Prisma and SQL migrations. schema.prisma plus the migrations folder define persistence, while server/models and server/database represent the domain objects and database access patterns used by resolvers, APIs, and background jobs.
7. The real-time multiplayer play subsystem is a distinct backend domain. server/match manages match lifecycle, pairing, chat, heartbeat, solve events, standings, rematches, and win/lose updates, while the client-side client/components/play tree mirrors that with match UI, timers, lobbies, warnings, and game logic. Shared socket/event contracts live in shared/match and client/shared/match.
8. Matchmaking and ranking are separate from the core timing flow. There is explicit ELO-related logic for pairing and rating updates, plus elimination and head-to-head match types. The shared game-logic modules and server update handlers indicate that results are computed server-side, then pushed back to clients.
9. The timer subsystem is one of the most specialized parts of the app. It supports manual timing, StackMat integration, smart cubes over Bluetooth, hotkeys, scramble generation, PB detection, notifications, and solve saving. It also includes 3D cube visualization and device-management flows, which makes the timer a hardware-integrated client feature rather than a simple stopwatch page.
10. Stats are computed from solve history through dedicated client and server layers. The client has charts, calendars, distributions, and summary modules, while the server provides stats resolvers and model-backed aggregations. Solve caching and rolling average/worst/PB helpers suggest the architecture is optimized for repeated statistic queries over a large solve history.
11. Trainer is another self-contained domain, with custom algorithms, visualizations, public trainers, favorites, and data-cleaning utilities. It uses both local and server-backed persistence, and it relies on shared algorithm/solve representations so the same cubing notation can drive editors, previews, and training sessions.
12. Account, profile, community, and admin form the user-management boundary. These areas cover authentication, personal info, notification preferences, linked accounts, membership/pro features, reports, bans, user search, leaderboards, and moderation tools. Permission checks are enforced server-side through auth/ownership middleware and role-aware resolvers.
13. The repo also depends on several external services that materially shape the architecture: Stripe for billing, SES for email, Redis for caching/coordination, Discord and Airtable integrations, IP geolocation, search indexing, and object storage/CDN services. Background jobs, cron tasks, sitemap generation, and webhooks are first-class server concerns rather than ad hoc scripts.
14. Shared code is used intentionally to keep client/server contracts aligned. The shared directory contains cube/solve constants, feature flags, integration types, match socket types, and other data shapes that must remain consistent across the UI, GraphQL layer, and real-time match system.
15. Deployment is containerized and AWS-oriented. The repo includes Docker, Docker Compose, Elastic Beanstalk configuration, Nginx/Apache proxy settings, and CI/CD workflows for staging and production. Static assets live in public, while server resources also include email templates and HTML fallback content.
16. If you are drawing an architecture diagram, the clearest top-level boxes are: client SPA, client local DB, GraphQL/API server, real-time match service, relational database, and external integrations. The dominant flows are user interaction to client state, client requests to GraphQL/REST, socket events for matches, and server writes/reads to the database plus external services for billing, email, storage, and notifications.
Main entry points: App.tsx Layout Shell · consts.ts Shared Contracts · schema.graphql GraphQL API · _index.ts REST API
Components 18
Client
React SPA, browser state, and local persistence.
- Client SPA · Browser application shell and feature pages.
client/components/App.tsx - Layout Shell · Routing, nav, loading/offline/demo gating, theme, and initialization.
client/components/layout/App.tsx - Timer · Manual, StackMat, smart-cube, scramble, solve save, and device flows.
client/components/timer/Timer.tsx - Solves & Stats · Solve history, filters, charts, summaries, and cached statistics.
client/components/solves/SolvesList.tsx - Trainer · Algorithm trainers, custom trainers, visualizations, favorites, and cleanup.
client/components/trainer/Trainer.tsx - Play UI · Match lobby, timers, warnings, game state, and result views.
client/components/play/Play.tsx - Profile & Community · Profile, account, community, friends, search, leaderboards, and reporting.
client/components/profile/Profile.tsx - Settings · Appearance, cube types, timer settings, device access, and data import.
client/components/settings/Settings.tsx - Local DB · Browser-local sessions, solves, settings, and trainer stores.
client/db/lokijs.ts
Server
GraphQL, REST, match service, and data access.
- GraphQL API · Primary app API built from schema, resolvers, and type modules.
schema.graphql - REST API · Auth, forgotten password, profile/media, device hooks, notifications, and webhooks.
server/api/_index.ts - Match Service · Pairing, lifecycle, chat, heartbeat, solve events, standings, and rematches.
server/match/match.ts - Models & DB · Prisma schema, migrations, domain models, and database access patterns.
schema.prisma - Auth Guards · Authentication, ownership, pro checks, and search-engine/verification guards.
server/middlewares/auth.ts - Jobs & Integrations · Cron, search, email, billing, storage, Redis, Discord, Airtable, and webhooks.
server/services/cron.ts
Shared
Contracts and logic used by both runtimes.
- Shared Contracts · Cube, solve, feature, storage, and integration constants shared across runtimes.
shared/consts.ts - Match Contracts · Shared match events, socket types, and game-logic helpers.
shared/match/socketio.types.ts
Infra
Deployment, hosting, and runtime configuration.
- Deploy & Hosting · Docker, AWS/Elastic Beanstalk, nginx/httpd proxy config, and CI/CD workflows.
Dockerfile
Connections 29
- Client SPA → Layout Shell: renders · The SPA is mounted through the layout shell.
- Layout Shell → Timer: routes · Layout initializes and routes into the timer flow.
- Layout Shell → Solves & Stats: routes · Layout exposes solves and stats pages.
- Layout Shell → Trainer: routes · Layout exposes trainer pages.
- Layout Shell → Play UI: routes · Layout exposes multiplayer play pages.
- Layout Shell → Profile & Community: routes · Layout exposes profile and community areas.
- Layout Shell → Settings: routes · Layout exposes settings and import flows.
- Timer → Local DB: persists · Timer saves sessions, solves, and preferences locally first.
- Solves & Stats → Local DB: reads · History and statistics query local solve/session data.
- Trainer → Local DB: persists · Trainer uses local stores for custom training data.
- Settings → Local DB: persists · Settings are stored locally and reused on startup.
- Timer → Shared Contracts: uses · Timer logic depends on shared cube and solve shapes.
- Solves & Stats → Shared Contracts: uses · Statistics and history views use shared solve data shapes.
- Trainer → Shared Contracts: uses · Trainer editors and previews share notation and algorithm data.
- Play UI → Match Contracts: uses · Match UI follows shared socket and event contracts.
- Client SPA → GraphQL API: queries · Most application data flows through GraphQL.
- Client SPA → REST API: requests · Client also calls REST endpoints for auth and media/device concerns.
- Play UI → Match Service: sockets · Real-time play is coordinated by the match service.
- GraphQL API → Models & DB: loads/saves · Resolvers read and write domain data through Prisma-backed models.
- REST API → Models & DB: loads/saves · REST endpoints operate on the same persistent model layer.
- Match Service → Models & DB: updates · Match outcomes, ELO, chat, and participation are persisted.
- GraphQL API → Auth Guards: guards · Resolvers enforce auth, ownership, and role checks.
- REST API → Auth Guards: guards · REST endpoints use the same guardrail middleware.
- Jobs & Integrations → Models & DB: syncs · Jobs and integrations read and write application state and logs.
- Jobs & Integrations → Shared Contracts: uses · Background processes rely on shared constants and types.
- Match Service → Match Contracts: publishes · Server emits match events using shared definitions.
- GraphQL API → Shared Contracts: uses · GraphQL schema and resolvers mirror shared domain contracts.
- Deploy & Hosting → REST API: hosts · Deployment exposes the HTTP application entrypoint.
- Deploy & Hosting → Match Service: hosts · Deployment also supports websocket match traffic.