# kumaryash-2808/cube_solver architecture

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

- Interactive diagram: https://gitdiagram.com/kumaryash-2808/cube_solver
- Repository: https://github.com/kumaryash-2808/cube_solver

## Overview

This is a full-stack Rubik’s Cube solver: users edit or randomize a cube in a 3D browser interface, then request a solution through the Python server and its documented Kociemba API bridge. Separately, the repository includes an interactive C++ console solver that validates sticker input, converts it to cubie state, and runs the two-phase search. The C++ flow is supported by excerpts and the source index; frontend/server links rely on README descriptions, so details of their internal wiring are not asserted.

Main entry points: [`backend/main.cpp`](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/main.cpp) (Console solver), [`backend/bfstable/heuristictable.cpp`](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/heuristictable.cpp) (Pruning heuristics), [`frontend/script.js`](https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/script.js) (3D cube UI), [`backend/kociemba/kociemba_ph1.cpp`](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/kociemba_ph1.cpp) (Phase one search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_web_app["3D cube UI<br/>[script.js]"]
  node_web_layout["UI controls<br/>[index.html]"]
  node_web_style["3D presentation<br/>[style.css]"]
end

subgraph group_service["Solver service"]
  node_http_server["HTTP/API bridge<br/>[server.py]"]
  node_py_solver["Python Kociemba"]
end

subgraph group_decode["Cube representation"]
  node_sticker_input["Sticker entry<br/>[cube_inp.cpp]"]
  node_sticker_mapping["Sticker conversion<br/>[main.cpp]"]
  node_cubie_decode["Cubie inference<br/>[stk_to_cub.cpp]"]
  node_cubie_state["Cubie state<br/>[cubie.hpp]"]
end

subgraph group_search["C++ search"]
  node_cpp_entry["Console solver<br/>[main.cpp]"]
  node_move_engine["Move engine<br/>[cubemove.cpp]"]
  node_phase1["Phase one search<br/>[kociemba_ph1.cpp]"]
  node_phase1_dfs["Phase one DFS<br/>[DFS.cpp]"]
  node_phase2["Phase two search<br/>[DFS2.cpp]"]
  node_heuristic["Pruning heuristics<br/>[heuristictable.cpp]"]
  node_coordinate_encoder["Coordinate encoding<br/>[encoder.cpp]"]
  node_table_builder["Pruning table BFS<br/>[bfs.cpp]"]
  node_pruning_data[("Pruning tables")]
end

node_browser_user(("Cube user"))
node_console_user(("Console user"))

node_browser_user -->|"edits cube"| node_web_app
node_web_app -->|"uses controls"| node_web_layout
node_web_app -->|"renders with"| node_web_style
node_web_app -->|"requests solution"| node_http_server
node_http_server -->|"bridges to"| node_py_solver
node_console_user -->|"enters stickers"| node_cpp_entry
node_cpp_entry -->|"opens editor"| node_sticker_input
node_cpp_entry -->|"maps colors"| node_sticker_mapping
node_cpp_entry -->|"infers cubies"| node_cubie_decode
node_cubie_decode -->|"produces state"| node_cubie_state
node_cpp_entry -->|"starts search"| node_phase1
node_cpp_entry -->|"loads tables"| node_heuristic
node_phase1 -->|"dispatches DFS"| node_phase1_dfs
node_phase1_dfs -->|"applies moves"| node_move_engine
node_phase1_dfs -->|"starts phase two"| node_phase2
node_phase1 -->|"encodes coordinates"| node_coordinate_encoder
node_phase1 -->|"reads estimates"| node_heuristic
node_phase2 -->|"encodes coordinates"| node_coordinate_encoder
node_phase2 -->|"reads estimates"| node_heuristic
node_phase2 -->|"applies moves"| node_move_engine
node_heuristic -->|"generates tables"| node_table_builder
node_heuristic -->|"loads or saves"| node_pruning_data
node_table_builder -->|"traverses moves"| node_move_engine

click node_web_app "https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/script.js"
click node_web_layout "https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/index.html"
click node_web_style "https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/style.css"
click node_http_server "https://github.com/kumaryash-2808/cube_solver/blob/main/server.py"
click node_cpp_entry "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/main.cpp"
click node_sticker_input "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/inputproc/cube_inp.cpp"
click node_sticker_mapping "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/main.cpp"
click node_cubie_decode "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/inputproc/stk_to_cub.cpp"
click node_cubie_state "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/inputproc/cubie.hpp"
click node_move_engine "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/rubicsmove/cubemove.cpp"
click node_phase1 "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/kociemba_ph1.cpp"
click node_phase1_dfs "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/DFS.cpp"
click node_phase2 "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/DFS2.cpp"
click node_heuristic "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/heuristictable.cpp"
click node_coordinate_encoder "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/encoder.cpp"
click node_table_builder "https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/bfs.cpp"
click node_pruning_data "https://github.com/kumaryash-2808/cube_solver/tree/main/backend/tables"

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_web_app,node_web_layout,node_web_style,node_browser_user,node_console_user toneBlue
class node_http_server,node_py_solver toneAmber
class node_sticker_input,node_sticker_mapping,node_cubie_decode,node_cubie_state toneMint
class node_cpp_entry,node_move_engine,node_phase1,node_phase1_dfs,node_phase2,node_heuristic,node_coordinate_encoder,node_table_builder,node_pruning_data toneRose
```

## Components

### Web interface

- [3D cube UI](https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/script.js): `frontend/script.js`
- [UI controls](https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/index.html): `frontend/index.html`
- [3D presentation](https://github.com/kumaryash-2808/cube_solver/blob/main/frontend/style.css): `frontend/style.css`

### Solver service

- [HTTP/API bridge](https://github.com/kumaryash-2808/cube_solver/blob/main/server.py): `server.py`
- **Python Kociemba**

### Cube representation

- [Sticker entry](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/inputproc/cube_inp.cpp): `backend/inputproc/cube_inp.cpp`
- [Sticker conversion](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/main.cpp): `backend/main.cpp`
- [Cubie inference](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/inputproc/stk_to_cub.cpp): `backend/inputproc/stk_to_cub.cpp`
- [Cubie state](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/inputproc/cubie.hpp): `backend/inputproc/cubie.hpp`

### C++ search

- [Console solver](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/main.cpp): `backend/main.cpp`
- [Move engine](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/rubicsmove/cubemove.cpp): `backend/rubicsmove/cubemove.cpp`
- [Phase one search](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/kociemba_ph1.cpp): `backend/kociemba/kociemba_ph1.cpp`
- [Phase one DFS](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/DFS.cpp): `backend/kociemba/DFS.cpp`
- [Phase two search](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/kociemba/DFS2.cpp): `backend/kociemba/DFS2.cpp`
- [Pruning heuristics](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/heuristictable.cpp): `backend/bfstable/heuristictable.cpp`
- [Coordinate encoding](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/encoder.cpp): `backend/bfstable/encoder.cpp`
- [Pruning table BFS](https://github.com/kumaryash-2808/cube_solver/blob/main/backend/bfstable/bfs.cpp): `backend/bfstable/bfs.cpp`
- [Pruning tables](https://github.com/kumaryash-2808/cube_solver/tree/main/backend/tables): `backend/tables`

### Other components

- **Cube user**
- **Console user**

## Connections

- Cube user → 3D cube UI: edits cube (evidence: `README.md`)
- 3D cube UI → UI controls: uses controls (evidence: `README.md`)
- 3D cube UI → 3D presentation: renders with (evidence: `README.md`)
- 3D cube UI → HTTP/API bridge: requests solution (evidence: `README.md`)
- HTTP/API bridge → Python Kociemba: bridges to (evidence: `README.md`)
- Console user → Console solver: enters stickers (evidence: `backend/main.cpp`)
- Console solver → Sticker entry: opens editor (evidence: `backend/main.cpp`)
- Console solver → Sticker conversion: maps colors (evidence: `backend/main.cpp`)
- Console solver → Cubie inference: infers cubies (evidence: `backend/main.cpp`)
- Cubie inference → Cubie state: produces state (evidence: `backend/inputproc/stk_to_cub.cpp`)
- Console solver → Phase one search: starts search (evidence: `backend/main.cpp`)
- Console solver → Pruning heuristics: loads tables (evidence: `backend/main.cpp`)
- Phase one search → Phase one DFS: dispatches DFS (evidence: `backend/kociemba/kociemba_ph1.cpp`)
- Phase one DFS → Move engine: applies moves (evidence: `backend/kociemba/DFS.cpp`)
- Phase one DFS → Phase two search: starts phase two (evidence: `backend/kociemba/DFS.cpp`)
- Phase one search → Coordinate encoding: encodes coordinates (evidence: `backend/kociemba/kociemba_ph1.cpp`)
- Phase one search → Pruning heuristics: reads estimates (evidence: `backend/kociemba/kociemba_ph1.cpp`)
- Phase two search → Coordinate encoding: encodes coordinates (evidence: `backend/kociemba/DFS2.cpp`)
- Phase two search → Pruning heuristics: reads estimates (evidence: `backend/kociemba/DFS2.cpp`)
- Phase two search → Move engine: applies moves (evidence: `backend/kociemba/DFS2.cpp`)
- Pruning heuristics → Pruning table BFS: generates tables (evidence: `backend/bfstable/heuristictable.cpp`)
- Pruning heuristics → Pruning tables: loads or saves (evidence: `README.md`)
- Pruning table BFS → Move engine: traverses moves (evidence: `backend/bfstable/bfs.cpp`)
