How bryanlundberg/nexustimer works
1. What this repo is
NexusTimer is a full-stack speedcubing timer and analytics product built as a Next.js/TypeScript app. It combines an on-device timer, local solve management, deep statistics, community profiles/leaderboards, multiplayer free-play rooms, and an algorithms trainer.
2. Top-level app structure
The app router in src/app is split by product areas: landing, legal pages, auth, the core timer workspace, community pages, multiplayer rooms, and algorithms/trainer pages. Most user-facing experiences live under (with-sidebar), which suggests a shared shell with navigation and page-specific headers.
3. Frontend composition model
The repository follows a feature-sliced structure:
- src/widgets assembles page-level blocks such as sidebars, headers, people views, transfer-solves, and statistics views.
- src/features contains user actions and workflows like timer control, manage-solves, manage-cubes, authentication, backup import/export, trainer flows, and free-play room creation/joining.
- src/entities holds domain models for solves, cubes, users, backups, trainer records, credentials, tokens, and logs.
- src/shared contains cross-cutting utilities, config, constants, algorithm data, statistics math, timers, and generic UI.
4. Core timer data flow
The timer experience is centered in src/features/timer and src/shared/model/timer. User input and hardware events feed the timer state, then solve data is stored locally and used to update statistics panels, scramble displays, and overview widgets. This is the main “capture a solve → persist it → recompute analytics → render results” loop in the app.
5. Local-first persistence boundary
The app uses browser storage heavily through IndexedDB wrappers in src/shared/config/indexdb and entity-specific helpers like cubes/settings storage. This supports offline use, local cubes, solve history, and import/export flows. Backup sync hooks in src/shared/model/backup bridge local data with server-backed backups when the user is authenticated.
6. Server/API boundary
Backend functionality is exposed through src/app/api, especially api/v1. These routes cover authentication, users, backups, feedback, leaderboards, rooms, trainer data, solves, and image upload. The API layer is the boundary between the client’s local stores and the app’s shared server-side persistence/services.
7. Authentication and account lifecycle
Authentication is not just sign-in; it includes registration, email verification, password reset, resend flows, and credential validation. The codebase has NextAuth configuration under src/app/api/auth/[...nextauth] plus custom auth services in src/features/authentication/server. This indicates a multi-step account lifecycle with both client hooks and server-side verification/token logic.
8. Community and social views
Community features are split into leaderboards and “people” profile pages. These consume leaderboard/user APIs and render profile timelines, cubes, last activity, and comparison views. The src/features/compare-users and src/widgets/people areas show that user statistics are first-class and can be compared across accounts, not just within one local session.
9. Multiplayer and room coordination
Free-play rooms are a separate subsystem under src/app/(with-sidebar)/(multiplayer) and src/features/free-play-room. Rooms support live players, private-room password verification, Stackmat listener integration, and room-level timer/results tabs. The api/v1/rooms endpoints suggest a server-coordinated room model rather than purely peer-to-peer multiplayer.
10. Algorithms and trainer subsystem
Algorithms are treated as product content and as a training engine. Static algorithm sets live in src/shared/data/algs, while the trainer feature stores learned cases, solve history, session state, and stats. The trainer also has its own API routes, indicating a backend-persisted learning model rather than purely client-side practice state.
11. Compute-heavy analytics
Statistical computation is split between shared math utilities and Web Workers. src/shared/lib/statistics contains reusable metric calculations, while src/shared/worker/timer-stats.worker.ts and src/features/deep-statistics/worker offload heavier aggregation/charting work. This is important for architecture diagrams because analytics is intentionally separated from the main UI thread.
12. Hardware, scrambles, and media integration
The timer can connect to external cube/timer hardware via adapters in src/features/hardware and bundled CSTimer vendor scripts in public/vendors/cstimer. Scramble generation and solution generation are also in src/shared/lib/timer, and the app ships audio assets, virtual cube visuals, and PWA assets/service worker files, so the runtime is optimized for both desktop-style and mobile-style use.
13. Infrastructure and external services
The repo includes configuration for NextAuth, MongoDB, Firebase, UploadThing, and i18n message bundles. That means the system likely spans browser storage, server APIs, and external services for auth, persistence, and file/image uploads. The presence of firebase.json, uploadthing, and MongoDB config is an architectural clue that the app is not single-store or single-backend.
14. Quality and delivery setup
The project is covered by unit tests for core statistics functions and Playwright e2e tests for timer, cubes, solves, transfers, backups, and algorithm scraping flows. A dev Docker compose file, Husky pre-commit hooks, and locale/message files indicate the repo is designed for repeatable development, cross-language support, and regression protection across the main user flows.
Main entry points: route.ts API v1 · useTimer.ts Timer logic · solve.ts Domain entities · page.tsx Timer app
Components 20
App routes
Next.js route groups and API boundaries
- Landing · Public landing and informational pages
src/app/page.tsx - Auth pages · Sign-in, sign-up, and password recovery screens
src/app/(with-sidebar)/(auth)/sign-in/page.tsx - Timer app · Main timer, solves, stats, cubes, account, and transfer pages
src/app/(with-sidebar)/(core-timer)/app/page.tsx - Community · Leaderboards and people profile pages
src/app/(with-sidebar)/(community)/leaderboards/page.tsx - Free play · Shared room lobby and room pages
src/app/(with-sidebar)/(multiplayer)/free-play/page.tsx - Algorithms · Algorithm library and trainer pages
src/app/algorithms/page.tsx - API v1 · Auth, backups, users, rooms, trainer, leaderboards, feedback, and uploads
src/app/api/v1/users/route.ts
Feature modules
User workflows and interactive product features
- Timer logic · Input handling, inspection, timer state, solve persistence, and timer UI
src/features/timer/model/useTimer.ts - Statistics · Deep statistics views and charting flows
src/features/deep-statistics/model/useDeepStatistics.ts - Manage solves · Solve editing, quick actions, move, delete, DNF, and +2 workflows
src/features/manage-solves/model/useQuickActions.ts - Cubes · Collection creation, editing, selection, and cube storage actions
src/features/manage-cubes/model/useCubeActions.tsx - Auth flows · Login, registration, verification, password reset, and server auth services
src/features/authentication/model/hooks/use-credentials-login.ts - Trainer · Trainer session state, learned cases, solves, and stats
src/features/trainer/model/useTrainerSession.ts - Room play · Room creation, join, live players, stackmat listener, and room timer tabs
src/features/free-play-room/model/useFreeMode.ts - Profiles · Leaderboards, people pages, comparison, and profile content
src/features/compare-users/model/useCompareUsersStats.ts
Domain models
Entities and persisted domain state
- Domain entities · Solve, cube, user, backup, trainer, token, and log models
src/entities/solve/model/solve.ts
Shared layer
Cross-cutting config, logic, UI, and workers
- Shared config · Auth, Firebase, MongoDB, i18n, and IndexedDB configuration
src/shared/config/mongodb/mongodb.ts - Shared logic · Statistics, scramble generation, algorithms registry, backup sync, and general helpers
src/shared/lib/statistics/calculateCurrentAo.ts - Workers · Heavy timer statistics and deep statistics worker execution
src/shared/worker/timer-stats.worker.ts
Page widgets
Composed page sections and shells
- Page widgets · Sidebar, headers, people panels, statistics view, and transfer grids
src/widgets/sidebar/ui/AppSidebar.tsx
Connections 25
- Landing → Shared config: i18n/config · Landing and app shell rely on shared runtime configuration
- Auth pages → Auth flows: forms · Auth screens are built from authentication feature flows
- Auth flows → API v1: server calls · Authentication uses API routes for registration, verification, and password recovery
- Timer app → Timer logic: timer UI · Core timer routes are driven by timer state and controls
- Timer logic → Domain entities: persist solves · Solved times and related records are stored in domain entities
- Timer logic → Shared logic: scrambles · Timer flow depends on scramble and solution helpers
- Timer logic → Shared config: local storage · Timer and solve state use IndexedDB and app settings storage
- Timer logic → Page widgets: page blocks · Timer pages assemble panels and navigation widgets
- Timer app → Manage solves: solve tools · Solve management pages use quick actions and solve detail workflows
- Manage solves → Domain entities: mutations · Solve edits operate on solve entities and related records
- Timer app → Cubes: cube tools · Cube management pages use cube collection actions and selectors
- Cubes → Domain entities: cube storage · Cube collections are backed by cube entities and local persistence
- Timer app → Statistics: analytics · Stats pages render deep statistics and charts
- Statistics → Workers: heavy compute · Deep statistics offload aggregation to workers
- Statistics → Shared logic: metrics · Statistics reuse shared calculation helpers
- Community → Profiles: profiles · Community routes compose leaderboards and people views
- Profiles → API v1: user data · Profiles and comparisons consume leaderboard and user API data
- Free play → Room play: room UI · Free-play routes are implemented by the room subsystem
- Room play → API v1: room service · Rooms depend on server-coordinated room and password verification endpoints
- Algorithms → Trainer: training · Algorithms pages connect content browsing with trainer flows
- Trainer → API v1: trainer data · Trainer sessions, learned cases, and solves are persisted through APIs
- Trainer → Domain entities: trainer models · Trainer state is represented by trainer-specific domain entities
- API v1 → Shared config: db/auth · API routes depend on MongoDB, Firebase, NextAuth, and upload configuration
- API v1 → Domain entities: persistence · Server routes read and write domain entities for users, solves, backups, and trainer data
- Page widgets → Shared logic: formatting · Widgets reuse shared helpers for display and aggregation