# kash/cubedesk architecture

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

- Interactive diagram: https://gitdiagram.com/kash/cubedesk
- Repository: https://github.com/kash/cubedesk

## Overview

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: [`client/components/layout/App.tsx`](https://github.com/kash/cubedesk/blob/main/client/components/layout/App.tsx) (Layout Shell), [`shared/consts.ts`](https://github.com/kash/cubedesk/blob/main/shared/consts.ts) (Shared Contracts), [`schema.graphql`](https://github.com/kash/cubedesk/blob/main/schema.graphql) (GraphQL API), [`server/api/_index.ts`](https://github.com/kash/cubedesk/blob/main/server/api/_index.ts) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["Client SPA<br/>react app<br/>[App.tsx]"]
  node_client_layout["Layout Shell<br/>routing/shell<br/>[App.tsx]"]
  node_client_timer["Timer<br/>timing UI<br/>[Timer.tsx]"]
  node_client_solves_stats["Solves & Stats<br/>history/analytics<br/>[SolvesList.tsx]"]
  node_client_trainer["Trainer<br/>training UI<br/>[Trainer.tsx]"]
  node_client_play["Play UI<br/>multiplayer UI<br/>[Play.tsx]"]
  node_client_profile_community["Profile & Community<br/>social UI<br/>[Profile.tsx]"]
  node_client_settings["Settings<br/>preferences UI<br/>[Settings.tsx]"]
  node_client_db[("Local DB<br/>LokiJS persistence<br/>[lokijs.ts]")]
end

subgraph group_server["Server"]
  node_server_graphql["GraphQL API<br/>schema/resolvers<br/>[schema.graphql]"]
  node_server_rest["REST API<br/>HTTP endpoints<br/>[_index.ts]"]
  node_server_match["Match Service<br/>realtime domain<br/>[match.ts]"]
  node_server_models_db[("Models & DB<br/>Prisma/data access<br/>[schema.prisma]")]
  node_server_auth["Auth Guards<br/>middleware<br/>[auth.ts]"]
  node_server_jobs_integrations["Jobs & Integrations<br/>background/external<br/>[cron.ts]"]
end

subgraph group_shared["Shared"]
  node_shared_contracts["Shared Contracts<br/>shared types<br/>[consts.ts]"]
  node_shared_match["Match Contracts<br/>socket contracts<br/>[socketio.types.ts]"]
end

subgraph group_infra["Infra"]
  node_infra_deploy["Deploy & Hosting<br/>deployment"]
end

node_client_app -->|"renders"| node_client_layout
node_client_layout -->|"routes"| node_client_timer
node_client_layout -->|"routes"| node_client_solves_stats
node_client_layout -->|"routes"| node_client_trainer
node_client_layout -->|"routes"| node_client_play
node_client_layout -->|"routes"| node_client_profile_community
node_client_layout -->|"routes"| node_client_settings
node_client_timer -->|"persists"| node_client_db
node_client_solves_stats -->|"reads"| node_client_db
node_client_trainer -->|"persists"| node_client_db
node_client_settings -->|"persists"| node_client_db
node_client_timer -->|"uses"| node_shared_contracts
node_client_solves_stats -->|"uses"| node_shared_contracts
node_client_trainer -->|"uses"| node_shared_contracts
node_client_play -->|"uses"| node_shared_match
node_client_app -->|"queries"| node_server_graphql
node_client_app -->|"requests"| node_server_rest
node_client_play -->|"sockets"| node_server_match
node_server_graphql -->|"loads/saves"| node_server_models_db
node_server_rest -->|"loads/saves"| node_server_models_db
node_server_match -->|"updates"| node_server_models_db
node_server_graphql -->|"guards"| node_server_auth
node_server_rest -->|"guards"| node_server_auth
node_server_jobs_integrations -->|"syncs"| node_server_models_db
node_server_jobs_integrations -->|"uses"| node_shared_contracts
node_server_match -->|"publishes"| node_shared_match
node_server_graphql -->|"uses"| node_shared_contracts
node_infra_deploy -->|"hosts"| node_server_rest
node_infra_deploy -->|"hosts"| node_server_match

click node_client_app "https://github.com/kash/cubedesk/blob/main/client/components/App.tsx"
click node_client_layout "https://github.com/kash/cubedesk/blob/main/client/components/layout/App.tsx"
click node_client_timer "https://github.com/kash/cubedesk/blob/main/client/components/timer/Timer.tsx"
click node_client_solves_stats "https://github.com/kash/cubedesk/blob/main/client/components/solves/SolvesList.tsx"
click node_client_trainer "https://github.com/kash/cubedesk/blob/main/client/components/trainer/Trainer.tsx"
click node_client_play "https://github.com/kash/cubedesk/blob/main/client/components/play/Play.tsx"
click node_client_profile_community "https://github.com/kash/cubedesk/blob/main/client/components/profile/Profile.tsx"
click node_client_settings "https://github.com/kash/cubedesk/blob/main/client/components/settings/Settings.tsx"
click node_client_db "https://github.com/kash/cubedesk/blob/main/client/db/lokijs.ts"
click node_server_graphql "https://github.com/kash/cubedesk/blob/main/schema.graphql"
click node_server_rest "https://github.com/kash/cubedesk/blob/main/server/api/_index.ts"
click node_server_match "https://github.com/kash/cubedesk/blob/main/server/match/match.ts"
click node_server_models_db "https://github.com/kash/cubedesk/blob/main/schema.prisma"
click node_server_auth "https://github.com/kash/cubedesk/blob/main/server/middlewares/auth.ts"
click node_server_jobs_integrations "https://github.com/kash/cubedesk/blob/main/server/services/cron.ts"
click node_shared_contracts "https://github.com/kash/cubedesk/blob/main/shared/consts.ts"
click node_shared_match "https://github.com/kash/cubedesk/blob/main/shared/match/socketio.types.ts"
click node_infra_deploy "https://github.com/kash/cubedesk/tree/main/Dockerfile"

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_client_layout,node_client_timer,node_client_solves_stats,node_client_trainer,node_client_play,node_client_profile_community,node_client_settings,node_client_db toneBlue
class node_server_graphql,node_server_rest,node_server_match,node_server_models_db,node_server_auth,node_server_jobs_integrations toneAmber
class node_shared_contracts,node_shared_match toneMint
class node_infra_deploy toneRose
```

## Components

### Client

React SPA, browser state, and local persistence.

- [Client SPA](https://github.com/kash/cubedesk/blob/main/client/components/App.tsx): react app · Browser application shell and feature pages. · `client/components/App.tsx`
- [Layout Shell](https://github.com/kash/cubedesk/blob/main/client/components/layout/App.tsx): routing/shell · Routing, nav, loading/offline/demo gating, theme, and initialization. · `client/components/layout/App.tsx`
- [Timer](https://github.com/kash/cubedesk/blob/main/client/components/timer/Timer.tsx): timing UI · Manual, StackMat, smart-cube, scramble, solve save, and device flows. · `client/components/timer/Timer.tsx`
- [Solves & Stats](https://github.com/kash/cubedesk/blob/main/client/components/solves/SolvesList.tsx): history/analytics · Solve history, filters, charts, summaries, and cached statistics. · `client/components/solves/SolvesList.tsx`
- [Trainer](https://github.com/kash/cubedesk/blob/main/client/components/trainer/Trainer.tsx): training UI · Algorithm trainers, custom trainers, visualizations, favorites, and cleanup. · `client/components/trainer/Trainer.tsx`
- [Play UI](https://github.com/kash/cubedesk/blob/main/client/components/play/Play.tsx): multiplayer UI · Match lobby, timers, warnings, game state, and result views. · `client/components/play/Play.tsx`
- [Profile & Community](https://github.com/kash/cubedesk/blob/main/client/components/profile/Profile.tsx): social UI · Profile, account, community, friends, search, leaderboards, and reporting. · `client/components/profile/Profile.tsx`
- [Settings](https://github.com/kash/cubedesk/blob/main/client/components/settings/Settings.tsx): preferences UI · Appearance, cube types, timer settings, device access, and data import. · `client/components/settings/Settings.tsx`
- [Local DB](https://github.com/kash/cubedesk/blob/main/client/db/lokijs.ts): LokiJS persistence · Browser-local sessions, solves, settings, and trainer stores. · `client/db/lokijs.ts`

### Server

GraphQL, REST, match service, and data access.

- [GraphQL API](https://github.com/kash/cubedesk/blob/main/schema.graphql): schema/resolvers · Primary app API built from schema, resolvers, and type modules. · `schema.graphql`
- [REST API](https://github.com/kash/cubedesk/blob/main/server/api/_index.ts): HTTP endpoints · Auth, forgotten password, profile/media, device hooks, notifications, and webhooks. · `server/api/_index.ts`
- [Match Service](https://github.com/kash/cubedesk/blob/main/server/match/match.ts): realtime domain · Pairing, lifecycle, chat, heartbeat, solve events, standings, and rematches. · `server/match/match.ts`
- [Models & DB](https://github.com/kash/cubedesk/blob/main/schema.prisma): Prisma/data access · Prisma schema, migrations, domain models, and database access patterns. · `schema.prisma`
- [Auth Guards](https://github.com/kash/cubedesk/blob/main/server/middlewares/auth.ts): middleware · Authentication, ownership, pro checks, and search-engine/verification guards. · `server/middlewares/auth.ts`
- [Jobs & Integrations](https://github.com/kash/cubedesk/blob/main/server/services/cron.ts): background/external · Cron, search, email, billing, storage, Redis, Discord, Airtable, and webhooks. · `server/services/cron.ts`

### Shared

Contracts and logic used by both runtimes.

- [Shared Contracts](https://github.com/kash/cubedesk/blob/main/shared/consts.ts): shared types · Cube, solve, feature, storage, and integration constants shared across runtimes. · `shared/consts.ts`
- [Match Contracts](https://github.com/kash/cubedesk/blob/main/shared/match/socketio.types.ts): socket contracts · Shared match events, socket types, and game-logic helpers. · `shared/match/socketio.types.ts`

### Infra

Deployment, hosting, and runtime configuration.

- [Deploy & Hosting](https://github.com/kash/cubedesk/tree/main/Dockerfile): deployment · Docker, AWS/Elastic Beanstalk, nginx/httpd proxy config, and CI/CD workflows. · `Dockerfile`

## Connections

- 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.
