# mizumi250/rubik-solver architecture

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

- Interactive diagram: https://gitdiagram.com/mizumi250/rubik-solver
- Repository: https://github.com/mizumi250/rubik-solver

## Overview

This is a frontend-only Rubik’s Cube solver. The user scans or enters cube faces, reviews and corrects the captured stickers, requests a solution, then follows the moves in a step-by-step guide. The graph also includes substantial Arkzen runtime modules named in the source index; they appear to be exported framework infrastructure rather than part of the solver workflow. Generated route and solver-script modules are referenced in excerpts but are absent from the supplied tree, so their implementation is not mapped.

Main entry points: [`frontend/src/pages/components/RkApp.tsx`](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkApp.tsx) (Workflow shell), [`frontend/src/pages/components/RkGuide.tsx`](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkGuide.tsx) (Move-by-move guide), [`frontend/src/pages/components/hooks.tsx`](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/hooks.tsx) (Solver state), [`frontend/src/main.tsx`](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/main.tsx) (Frontend entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Solve Workflow"]
  node_entry["Frontend entry<br/>[main.tsx]"]
  node_app["App router<br/>[App.tsx]"]
  node_page["Solver page<br/>[index.tsx]"]
  node_solver_app["Workflow shell<br/>[RkApp.tsx]"]
  node_scan["Face scanning<br/>[RkScanStage.tsx]"]
  node_review["Sticker review<br/>[RkReviewStage.tsx]"]
  node_solve["Solution stage<br/>[RkSolveStage.tsx]"]
  node_state["Solver state<br/>[hooks.tsx]"]
  node_mini_face["Scan face preview<br/>[RkMiniFace.tsx]"]
  node_swatch["Color swatch<br/>[RkSwatch.tsx]"]
end

subgraph group_guide["Cube Guidance"]
  node_guide["Move-by-move guide<br/>[RkGuide.tsx]"]
  node_cube_net["Cube net<br/>[RkCubeNet.tsx]"]
  node_cube_3d["3D cube<br/>[RkCube3D.tsx]"]
  node_move_token["Move notation<br/>[RkMoveToken.tsx]"]
  node_glyph["Solver glyph<br/>[RkGlyph.tsx]"]
end

subgraph group_runtime["Arkzen Runtime"]
  node_query["Query hook<br/>[useQuery.ts]"]
  node_cache[("Response cache<br/>[cache.ts]")]
  node_auth[("Auth store<br/>[authStore.ts]")]
  node_toast["Toast provider<br/>[Toast.tsx]"]
  node_router_adapter["Router adapter<br/>[router.ts]"]
end

subgraph group_sync["Shared Sync"]
  node_sync_entry["Sync entry<br/>[sync.ts]"]
  node_shared_sync["Shared sync<br/>[shared-sync.ts]"]
end

node_user(("Cube solver user"))

node_user -->|"opens app"| node_entry
node_entry -->|"renders"| node_app
node_entry -->|"sets active slug"| node_auth
node_entry -->|"provides toasts"| node_toast
node_page -->|"renders"| node_solver_app
node_solver_app -->|"uses state"| node_state
node_solver_app -->|"renders stage"| node_scan
node_solver_app -->|"renders stage"| node_review
node_solver_app -->|"renders stage"| node_solve
node_scan -->|"captures faces"| node_state
node_scan -->|"renders preview"| node_mini_face
node_review -->|"reads and updates"| node_state
node_review -->|"renders colors"| node_swatch
node_solve -->|"reads solver state"| node_state
node_solve -->|"renders guide"| node_guide
node_guide -->|"reads solution state"| node_state
node_guide -->|"renders cube net"| node_cube_net
node_guide -->|"renders moves"| node_move_token
node_guide -->|"uses visualization"| node_cube_3d
node_page -->|"imports component"| node_cube_3d
node_page -->|"imports component"| node_glyph
node_query -->|"reads and writes"| node_cache
node_query -->|"fetches through"| node_auth
node_sync_entry -->|"imports"| node_shared_sync

click node_entry "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/main.tsx"
click node_app "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/App.tsx"
click node_page "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/index.tsx"
click node_solver_app "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkApp.tsx"
click node_scan "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkScanStage.tsx"
click node_review "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkReviewStage.tsx"
click node_solve "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkSolveStage.tsx"
click node_state "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/hooks.tsx"
click node_mini_face "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkMiniFace.tsx"
click node_swatch "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkSwatch.tsx"
click node_guide "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkGuide.tsx"
click node_cube_net "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkCubeNet.tsx"
click node_cube_3d "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkCube3D.tsx"
click node_move_token "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkMoveToken.tsx"
click node_glyph "https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkGlyph.tsx"
click node_query "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/hooks/useQuery.ts"
click node_cache "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/lib/cache.ts"
click node_auth "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/stores/authStore.ts"
click node_toast "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/components/Toast.tsx"
click node_router_adapter "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/adapters/router.ts"
click node_sync_entry "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/sync.ts"
click node_shared_sync "https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/shared-sync.ts"

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_entry,node_app,node_page,node_solver_app,node_scan,node_review,node_solve,node_state,node_mini_face,node_swatch,node_user toneBlue
class node_guide,node_cube_net,node_cube_3d,node_move_token,node_glyph toneAmber
class node_query,node_cache,node_auth,node_toast,node_router_adapter toneMint
class node_sync_entry,node_shared_sync toneRose
```

## Components

### Solve Workflow

- [Frontend entry](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [App router](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Solver page](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/index.tsx): `frontend/src/pages/index.tsx`
- [Workflow shell](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkApp.tsx): `frontend/src/pages/components/RkApp.tsx`
- [Face scanning](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkScanStage.tsx): `frontend/src/pages/components/RkScanStage.tsx`
- [Sticker review](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkReviewStage.tsx): `frontend/src/pages/components/RkReviewStage.tsx`
- [Solution stage](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkSolveStage.tsx): `frontend/src/pages/components/RkSolveStage.tsx`
- [Solver state](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/hooks.tsx): `frontend/src/pages/components/hooks.tsx`
- [Scan face preview](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkMiniFace.tsx): `frontend/src/pages/components/RkMiniFace.tsx`
- [Color swatch](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkSwatch.tsx): `frontend/src/pages/components/RkSwatch.tsx`

### Cube Guidance

- [Move-by-move guide](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkGuide.tsx): `frontend/src/pages/components/RkGuide.tsx`
- [Cube net](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkCubeNet.tsx): `frontend/src/pages/components/RkCubeNet.tsx`
- [3D cube](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkCube3D.tsx): `frontend/src/pages/components/RkCube3D.tsx`
- [Move notation](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkMoveToken.tsx): `frontend/src/pages/components/RkMoveToken.tsx`
- [Solver glyph](https://github.com/mizumi250/rubik-solver/blob/main/frontend/src/pages/components/RkGlyph.tsx): `frontend/src/pages/components/RkGlyph.tsx`

### Arkzen Runtime

- [Query hook](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/hooks/useQuery.ts): `frontend/arkzen/core/hooks/useQuery.ts`
- [Response cache](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/lib/cache.ts): `frontend/arkzen/core/lib/cache.ts`
- [Auth store](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/stores/authStore.ts): `frontend/arkzen/core/stores/authStore.ts`
- [Toast provider](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/components/Toast.tsx): `frontend/arkzen/core/components/Toast.tsx`
- [Router adapter](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/adapters/router.ts): `frontend/arkzen/core/adapters/router.ts`

### Shared Sync

- [Sync entry](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/sync.ts): `frontend/arkzen/sync.ts`
- [Shared sync](https://github.com/mizumi250/rubik-solver/blob/main/frontend/arkzen/core/shared-sync.ts): `frontend/arkzen/core/shared-sync.ts`

### Other components

- **Cube solver user**

## Connections

- Cube solver user → Frontend entry: opens app (evidence: `frontend/src/main.tsx`)
- Frontend entry → App router: renders (evidence: `frontend/src/main.tsx`)
- Frontend entry → Auth store: sets active slug (evidence: `frontend/src/main.tsx`)
- Frontend entry → Toast provider: provides toasts (evidence: `frontend/src/main.tsx`)
- Solver page → Workflow shell: renders (evidence: `frontend/src/pages/index.tsx`)
- Workflow shell → Solver state: uses state (evidence: `frontend/src/pages/components/RkApp.tsx`)
- Workflow shell → Face scanning: renders stage (evidence: `frontend/src/pages/components/RkApp.tsx`)
- Workflow shell → Sticker review: renders stage (evidence: `frontend/src/pages/components/RkApp.tsx`)
- Workflow shell → Solution stage: renders stage (evidence: `frontend/src/pages/components/RkApp.tsx`)
- Face scanning → Solver state: captures faces (evidence: `frontend/src/pages/components/hooks.tsx`)
- Face scanning → Scan face preview: renders preview (evidence: `frontend/src/pages/components/RkScanStage.tsx`)
- Sticker review → Solver state: reads and updates (evidence: `frontend/src/pages/components/RkReviewStage.tsx`)
- Sticker review → Color swatch: renders colors (evidence: `frontend/src/pages/components/RkReviewStage.tsx`)
- Solution stage → Solver state: reads solver state (evidence: `frontend/src/pages/components/RkSolveStage.tsx`)
- Solution stage → Move-by-move guide: renders guide (evidence: `frontend/src/pages/components/RkSolveStage.tsx`)
- Move-by-move guide → Solver state: reads solution state (evidence: `frontend/src/pages/components/RkGuide.tsx`)
- Move-by-move guide → Cube net: renders cube net (evidence: `frontend/src/pages/components/RkGuide.tsx`)
- Move-by-move guide → Move notation: renders moves (evidence: `frontend/src/pages/components/RkGuide.tsx`)
- Move-by-move guide → 3D cube: uses visualization (evidence: `frontend/src/pages/components/RkGuide.tsx`)
- Solver page → 3D cube: imports component (evidence: `frontend/src/pages/index.tsx`)
- Solver page → Solver glyph: imports component (evidence: `frontend/src/pages/index.tsx`)
- Query hook → Response cache: reads and writes (evidence: `frontend/arkzen/core/hooks/useQuery.ts`)
- Query hook → Auth store: fetches through (evidence: `frontend/arkzen/core/hooks/useQuery.ts`)
- Sync entry → Shared sync: imports (evidence: `frontend/arkzen/sync.ts`)