# bryanlundberg/nexustimer architecture

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

- Interactive diagram: https://gitdiagram.com/bryanlundberg/nexustimer
- Repository: https://github.com/bryanlundberg/nexustimer

## Overview

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: [`src/app/api/v1/users/route.ts`](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/api/v1/users/route.ts) (API v1), [`src/features/timer/model/useTimer.ts`](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/timer/model/useTimer.ts) (Timer logic), [`src/entities/solve/model/solve.ts`](https://github.com/bryanlundberg/nexustimer/blob/main/src/entities/solve/model/solve.ts) (Domain entities), [`src/app/(with-sidebar)/(core-timer)/app/page.tsx`](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(core-timer)/app/page.tsx) (Timer app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_landing["Landing<br/>marketing shell<br/>[page.tsx]"]
  node_auth_pages["Auth pages<br/>auth routes<br/>[page.tsx]"]
  node_core_timer["Timer app<br/>workspace routes<br/>[page.tsx]"]
  node_community["Community<br/>[page.tsx]"]
  node_multiplayer["Free play<br/>room routes<br/>[page.tsx]"]
  node_algorithms["Algorithms<br/>content routes<br/>[page.tsx]"]
  node_api["API v1<br/>server routes<br/>[route.ts]"]
end

subgraph group_features["Feature modules"]
  node_timer_feature["Timer logic<br/>solve capture<br/>[useTimer.ts]"]
  node_stats_feature["Statistics<br/>analytics UI"]
  node_manage_solves["Manage solves<br/>solve tools<br/>[useQuickActions.ts]"]
  node_manage_cubes["Cubes<br/>cube management<br/>[useCubeActions.tsx]"]
  node_auth_feature["Auth flows<br/>account lifecycle"]
  node_trainer_feature["Trainer<br/>learning engine"]
  node_freeplay_feature["Room play<br/>multiplayer engine<br/>[useFreeMode.ts]"]
  node_community_feature["Profiles<br/>social views"]
end

subgraph group_domain["Domain models"]
  node_entities["Domain entities<br/>models<br/>[solve.ts]"]
end

subgraph group_shared["Shared layer"]
  node_shared_config["Shared config<br/>runtime config<br/>[mongodb.ts]"]
  node_shared_logic["Shared logic<br/>math and utils"]
  node_shared_workers["Workers<br/>off-main-thread compute"]
end

subgraph group_widgets["Page widgets"]
  node_widgets["Page widgets<br/>composed views<br/>[AppSidebar.tsx]"]
end

node_landing -->|"i18n/config"| node_shared_config
node_auth_pages -->|"forms"| node_auth_feature
node_auth_feature -->|"server calls"| node_api
node_core_timer -->|"timer UI"| node_timer_feature
node_timer_feature -->|"persist solves"| node_entities
node_timer_feature -->|"scrambles"| node_shared_logic
node_timer_feature -->|"local storage"| node_shared_config
node_timer_feature -->|"page blocks"| node_widgets
node_core_timer -->|"solve tools"| node_manage_solves
node_manage_solves -->|"mutations"| node_entities
node_core_timer -->|"cube tools"| node_manage_cubes
node_manage_cubes -->|"cube storage"| node_entities
node_core_timer -->|"analytics"| node_stats_feature
node_stats_feature -->|"heavy compute"| node_shared_workers
node_stats_feature -->|"metrics"| node_shared_logic
node_community -->|"profiles"| node_community_feature
node_community_feature -->|"user data"| node_api
node_multiplayer -->|"room UI"| node_freeplay_feature
node_freeplay_feature -->|"room service"| node_api
node_algorithms -->|"training"| node_trainer_feature
node_trainer_feature -->|"trainer data"| node_api
node_trainer_feature -->|"trainer models"| node_entities
node_api -->|"db/auth"| node_shared_config
node_api -->|"persistence"| node_entities
node_widgets -->|"formatting"| node_shared_logic

click node_landing "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/page.tsx"
click node_auth_pages "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(auth)/sign-in/page.tsx"
click node_core_timer "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(core-timer)/app/page.tsx"
click node_community "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(community)/leaderboards/page.tsx"
click node_multiplayer "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(multiplayer)/free-play/page.tsx"
click node_algorithms "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/algorithms/page.tsx"
click node_api "https://github.com/bryanlundberg/nexustimer/blob/main/src/app/api/v1/users/route.ts"
click node_timer_feature "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/timer/model/useTimer.ts"
click node_stats_feature "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/deep-statistics/model/useDeepStatistics.ts"
click node_manage_solves "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/manage-solves/model/useQuickActions.ts"
click node_manage_cubes "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/manage-cubes/model/useCubeActions.tsx"
click node_auth_feature "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/authentication/model/hooks/use-credentials-login.ts"
click node_trainer_feature "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/trainer/model/useTrainerSession.ts"
click node_freeplay_feature "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/free-play-room/model/useFreeMode.ts"
click node_community_feature "https://github.com/bryanlundberg/nexustimer/blob/main/src/features/compare-users/model/useCompareUsersStats.ts"
click node_entities "https://github.com/bryanlundberg/nexustimer/blob/main/src/entities/solve/model/solve.ts"
click node_shared_config "https://github.com/bryanlundberg/nexustimer/blob/main/src/shared/config/mongodb/mongodb.ts"
click node_shared_logic "https://github.com/bryanlundberg/nexustimer/blob/main/src/shared/lib/statistics/calculateCurrentAo.ts"
click node_shared_workers "https://github.com/bryanlundberg/nexustimer/blob/main/src/shared/worker/timer-stats.worker.ts"
click node_widgets "https://github.com/bryanlundberg/nexustimer/blob/main/src/widgets/sidebar/ui/AppSidebar.tsx"

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_landing,node_auth_pages,node_core_timer,node_community,node_multiplayer,node_algorithms,node_api toneBlue
class node_timer_feature,node_stats_feature,node_manage_solves,node_manage_cubes,node_auth_feature,node_trainer_feature,node_freeplay_feature,node_community_feature toneAmber
class node_entities toneMint
class node_shared_config,node_shared_logic,node_shared_workers toneRose
class node_widgets toneIndigo
```

## Components

### App routes

Next.js route groups and API boundaries

- [Landing](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/page.tsx): marketing shell · Public landing and informational pages · `src/app/page.tsx`
- [Auth pages](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(auth)/sign-in/page.tsx): auth routes · Sign-in, sign-up, and password recovery screens · `src/app/(with-sidebar)/(auth)/sign-in/page.tsx`
- [Timer app](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(core-timer)/app/page.tsx): workspace routes · Main timer, solves, stats, cubes, account, and transfer pages · `src/app/(with-sidebar)/(core-timer)/app/page.tsx`
- [Community](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(community)/leaderboards/page.tsx): community routes · Leaderboards and people profile pages · `src/app/(with-sidebar)/(community)/leaderboards/page.tsx`
- [Free play](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/(with-sidebar)/(multiplayer)/free-play/page.tsx): room routes · Shared room lobby and room pages · `src/app/(with-sidebar)/(multiplayer)/free-play/page.tsx`
- [Algorithms](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/algorithms/page.tsx): content routes · Algorithm library and trainer pages · `src/app/algorithms/page.tsx`
- [API v1](https://github.com/bryanlundberg/nexustimer/blob/main/src/app/api/v1/users/route.ts): server routes · 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](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/timer/model/useTimer.ts): solve capture · Input handling, inspection, timer state, solve persistence, and timer UI · `src/features/timer/model/useTimer.ts`
- [Statistics](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/deep-statistics/model/useDeepStatistics.ts): analytics UI · Deep statistics views and charting flows · `src/features/deep-statistics/model/useDeepStatistics.ts`
- [Manage solves](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/manage-solves/model/useQuickActions.ts): solve tools · Solve editing, quick actions, move, delete, DNF, and +2 workflows · `src/features/manage-solves/model/useQuickActions.ts`
- [Cubes](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/manage-cubes/model/useCubeActions.tsx): cube management · Collection creation, editing, selection, and cube storage actions · `src/features/manage-cubes/model/useCubeActions.tsx`
- [Auth flows](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/authentication/model/hooks/use-credentials-login.ts): account lifecycle · Login, registration, verification, password reset, and server auth services · `src/features/authentication/model/hooks/use-credentials-login.ts`
- [Trainer](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/trainer/model/useTrainerSession.ts): learning engine · Trainer session state, learned cases, solves, and stats · `src/features/trainer/model/useTrainerSession.ts`
- [Room play](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/free-play-room/model/useFreeMode.ts): multiplayer engine · Room creation, join, live players, stackmat listener, and room timer tabs · `src/features/free-play-room/model/useFreeMode.ts`
- [Profiles](https://github.com/bryanlundberg/nexustimer/blob/main/src/features/compare-users/model/useCompareUsersStats.ts): social views · Leaderboards, people pages, comparison, and profile content · `src/features/compare-users/model/useCompareUsersStats.ts`

### Domain models

Entities and persisted domain state

- [Domain entities](https://github.com/bryanlundberg/nexustimer/blob/main/src/entities/solve/model/solve.ts): models · 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](https://github.com/bryanlundberg/nexustimer/blob/main/src/shared/config/mongodb/mongodb.ts): runtime config · Auth, Firebase, MongoDB, i18n, and IndexedDB configuration · `src/shared/config/mongodb/mongodb.ts`
- [Shared logic](https://github.com/bryanlundberg/nexustimer/blob/main/src/shared/lib/statistics/calculateCurrentAo.ts): math and utils · Statistics, scramble generation, algorithms registry, backup sync, and general helpers · `src/shared/lib/statistics/calculateCurrentAo.ts`
- [Workers](https://github.com/bryanlundberg/nexustimer/blob/main/src/shared/worker/timer-stats.worker.ts): off-main-thread compute · Heavy timer statistics and deep statistics worker execution · `src/shared/worker/timer-stats.worker.ts`

### Page widgets

Composed page sections and shells

- [Page widgets](https://github.com/bryanlundberg/nexustimer/blob/main/src/widgets/sidebar/ui/AppSidebar.tsx): composed views · Sidebar, headers, people panels, statistics view, and transfer grids · `src/widgets/sidebar/ui/AppSidebar.tsx`

## Connections

- 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
