# john-henriquez/speedcube-timer architecture

> Architecture diagram of the GitHub repository john-henriquez/speedcube-timer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/john-henriquez/speedcube-timer
- Repository: https://github.com/john-henriquez/speedcube-timer

## Overview

Speedcube Timer is an offline-first speedcubing web app with a Django sync API. The main workflow is recording solves locally, reviewing statistics and training progress, and optionally syncing records across devices. Separate branches provide the OLL/PLL almanac and structured training zones. The graph includes the local persistence and synchronization layers; links for unsampled pages or backend routing are limited to documented or indexed references.

Main entry points: [`frontend/src/App.jsx`](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/storage/index.js`](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/storage/index.js) (Storage facade), [`frontend/src/pages/AlmanacPage.jsx`](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/AlmanacPage.jsx) (Case almanac), [`frontend/src/sync/syncClient.js`](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/sync/syncClient.js) (Sync client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web app"]
  node_app["App shell<br/>[App.jsx]"]
  node_timer["Solve timer<br/>[TimerPage.jsx]"]
  node_calendar["Calendar and stats<br/>[CalendarPage.jsx]"]
end

subgraph group_training["Training and almanac"]
  node_training_page["Zone practice<br/>[TrainingPage.jsx]"]
  node_almanac_page["Case almanac<br/>[AlmanacPage.jsx]"]
  node_catalog["OLL PLL catalog<br/>[data.js]"]
  node_catalog_logic["Catalog analysis<br/>[analysis.js]"]
  node_case_logic["Case selection<br/>[selection.js]"]
  node_training_logic["Training zones<br/>[index.js]"]
  node_attempt_logic["Attempt records<br/>[attempts.js]"]
  node_cube["Cube simulator<br/>[cube.js]"]
end

subgraph group_data["Local data and sync"]
  node_solve_hook["Solve state<br/>[useSolves.js]"]
  node_attempt_hook["Attempt state<br/>[useAttempts.js]"]
  node_almanac_hook["Almanac preferences<br/>[useAlmanac.js]"]
  node_local_storage["Storage facade<br/>[index.js]"]
  node_indexeddb[("IndexedDB<br/>[indexedDb.js]")]
  node_sync_hook["Sync scheduling<br/>[useSync.js]"]
  node_sync_client["Sync client<br/>[syncClient.js]"]
  node_sync_mapping["Record mapping<br/>[mapping.js]"]
end

subgraph group_api["Sync API"]
  node_api_views["Sync endpoints<br/>[views.py]"]
  node_serializers["API serializers<br/>[serializers.py]"]
  node_models[("User records<br/>[models.py]")]
end

node_user(("Speedcuber"))
node_client(("Browser fetch"))
node_server(("Django API"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_timer
node_app -->|"renders"| node_calendar
node_app -->|"renders"| node_training_page
node_app -->|"renders"| node_almanac_page
node_app -->|"loads"| node_solve_hook
node_app -->|"loads"| node_attempt_hook
node_app -->|"loads"| node_almanac_hook
node_app -->|"starts"| node_sync_hook
node_almanac_page -->|"reads cases"| node_catalog
node_almanac_page -->|"filters cases"| node_case_logic
node_almanac_page -->|"loads zone cases"| node_training_logic
node_catalog -->|"analyzes algorithms"| node_catalog_logic
node_catalog_logic -->|"simulates moves"| node_cube
node_training_page -->|"uses zones"| node_training_logic
node_training_page -->|"records practice"| node_attempt_hook
node_attempt_hook -->|"validates records"| node_attempt_logic
node_calendar -->|"reads solves"| node_solve_hook
node_solve_hook -->|"loads and saves"| node_local_storage
node_attempt_hook -->|"loads and saves"| node_local_storage
node_almanac_hook -->|"stores preferences"| node_local_storage
node_local_storage -->|"delegates storage"| node_indexeddb
node_sync_hook -->|"runs sync"| node_sync_client
node_sync_client -->|"reads and applies"| node_local_storage
node_sync_client -->|"maps records"| node_sync_mapping
node_sync_client -->|"sends requests"| node_client
node_client -->|"calls API"| node_server
node_server -->|"routes requests"| node_api_views
node_api_views -->|"validates data"| node_serializers
node_api_views -->|"reads and writes"| node_models
node_serializers -->|"serializes records"| node_models

click node_app "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/App.jsx"
click node_timer "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/TimerPage.jsx"
click node_calendar "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/CalendarPage.jsx"
click node_training_page "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/TrainingPage.jsx"
click node_almanac_page "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/AlmanacPage.jsx"
click node_catalog "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/catalog/data.js"
click node_catalog_logic "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/catalog/analysis.js"
click node_case_logic "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/training/selection.js"
click node_training_logic "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/training/zones/index.js"
click node_attempt_logic "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/training/attempts.js"
click node_cube "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/core/cube/cube.js"
click node_solve_hook "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useSolves.js"
click node_attempt_hook "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useAttempts.js"
click node_almanac_hook "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useAlmanac.js"
click node_local_storage "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/storage/index.js"
click node_indexeddb "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/storage/indexedDb.js"
click node_sync_hook "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useSync.js"
click node_sync_client "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/sync/syncClient.js"
click node_sync_mapping "https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/sync/mapping.js"
click node_api_views "https://github.com/john-henriquez/speedcube-timer/blob/main/backend/timer/views.py"
click node_serializers "https://github.com/john-henriquez/speedcube-timer/blob/main/backend/timer/serializers.py"
click node_models "https://github.com/john-henriquez/speedcube-timer/blob/main/backend/timer/models.py"

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_app,node_timer,node_calendar,node_client toneBlue
class node_training_page,node_almanac_page,node_catalog,node_catalog_logic,node_case_logic,node_training_logic,node_attempt_logic,node_cube toneAmber
class node_solve_hook,node_attempt_hook,node_almanac_hook,node_local_storage,node_indexeddb,node_sync_hook,node_sync_client,node_sync_mapping,node_server toneMint
class node_api_views,node_serializers,node_models toneRose
class node_user toneIndigo
```

## Components

### Web app

- [App shell](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Solve timer](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/TimerPage.jsx): `frontend/src/pages/TimerPage.jsx`
- [Calendar and stats](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/CalendarPage.jsx): `frontend/src/pages/CalendarPage.jsx`

### Training and almanac

- [Zone practice](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/TrainingPage.jsx): `frontend/src/pages/TrainingPage.jsx`
- [Case almanac](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/pages/AlmanacPage.jsx): `frontend/src/pages/AlmanacPage.jsx`
- [OLL PLL catalog](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/catalog/data.js): `frontend/src/catalog/data.js`
- [Catalog analysis](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/catalog/analysis.js): `frontend/src/catalog/analysis.js`
- [Case selection](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/training/selection.js): `frontend/src/training/selection.js`
- [Training zones](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/training/zones/index.js): `frontend/src/training/zones/index.js`
- [Attempt records](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/training/attempts.js): `frontend/src/training/attempts.js`
- [Cube simulator](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/core/cube/cube.js): `frontend/src/core/cube/cube.js`

### Local data and sync

- [Solve state](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useSolves.js): `frontend/src/hooks/useSolves.js`
- [Attempt state](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useAttempts.js): `frontend/src/hooks/useAttempts.js`
- [Almanac preferences](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useAlmanac.js): `frontend/src/hooks/useAlmanac.js`
- [Storage facade](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/storage/index.js): `frontend/src/storage/index.js`
- [IndexedDB](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/storage/indexedDb.js): `frontend/src/storage/indexedDb.js`
- [Sync scheduling](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/hooks/useSync.js): `frontend/src/hooks/useSync.js`
- [Sync client](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/sync/syncClient.js): `frontend/src/sync/syncClient.js`
- [Record mapping](https://github.com/john-henriquez/speedcube-timer/blob/main/frontend/src/sync/mapping.js): `frontend/src/sync/mapping.js`

### Sync API

- [Sync endpoints](https://github.com/john-henriquez/speedcube-timer/blob/main/backend/timer/views.py): `backend/timer/views.py`
- [API serializers](https://github.com/john-henriquez/speedcube-timer/blob/main/backend/timer/serializers.py): `backend/timer/serializers.py`
- [User records](https://github.com/john-henriquez/speedcube-timer/blob/main/backend/timer/models.py): `backend/timer/models.py`

### Other components

- **Speedcuber**
- **Browser fetch**
- **Django API**

## Connections

- Speedcuber → App shell: uses
- App shell → Solve timer: renders (evidence: `frontend/src/App.jsx`)
- App shell → Calendar and stats: renders (evidence: `frontend/src/App.jsx`)
- App shell → Zone practice: renders (evidence: `frontend/src/App.jsx`)
- App shell → Case almanac: renders (evidence: `frontend/src/App.jsx`)
- App shell → Solve state: loads (evidence: `frontend/src/App.jsx`)
- App shell → Attempt state: loads (evidence: `frontend/src/App.jsx`)
- App shell → Almanac preferences: loads (evidence: `frontend/src/App.jsx`)
- App shell → Sync scheduling: starts (evidence: `frontend/src/App.jsx`)
- Case almanac → OLL PLL catalog: reads cases (evidence: `frontend/src/pages/AlmanacPage.jsx`)
- Case almanac → Case selection: filters cases (evidence: `frontend/src/pages/AlmanacPage.jsx`)
- Case almanac → Training zones: loads zone cases (evidence: `frontend/src/pages/AlmanacPage.jsx`)
- OLL PLL catalog → Catalog analysis: analyzes algorithms (evidence: `frontend/src/catalog/index.js`)
- Catalog analysis → Cube simulator: simulates moves (evidence: `frontend/src/catalog/analysis.js`)
- Zone practice → Training zones: uses zones
- Zone practice → Attempt state: records practice (evidence: `frontend/src/App.jsx`)
- Attempt state → Attempt records: validates records (evidence: `frontend/src/hooks/useAttempts.js`)
- Calendar and stats → Solve state: reads solves (evidence: `frontend/src/pages/CalendarPage.jsx`)
- Solve state → Storage facade: loads and saves (evidence: `frontend/src/hooks/useSolves.js`)
- Attempt state → Storage facade: loads and saves (evidence: `frontend/src/hooks/useAttempts.js`)
- Almanac preferences → Storage facade: stores preferences (evidence: `frontend/src/hooks/useAlmanac.js`)
- Storage facade → IndexedDB: delegates storage (evidence: `frontend/src/storage/index.js`)
- Sync scheduling → Sync client: runs sync (evidence: `frontend/src/hooks/useSync.js`)
- Sync client → Storage facade: reads and applies (evidence: `frontend/src/sync/syncClient.js`)
- Sync client → Record mapping: maps records (evidence: `frontend/src/sync/syncClient.js`)
- Sync client → Browser fetch: sends requests (evidence: `frontend/src/sync/syncClient.js`)
- Browser fetch → Django API: calls API (evidence: `README.md`)
- Django API → Sync endpoints: routes requests (evidence: `README.md`)
- Sync endpoints → API serializers: validates data (evidence: `backend/timer/views.py`)
- Sync endpoints → User records: reads and writes (evidence: `backend/timer/views.py`)
- API serializers → User records: serializes records (evidence: `backend/timer/serializers.py`)
