# nanborg/rubik architecture

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

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

## Overview

Rubik is a Python 3×3×3 solver using CFOP: a scramble enters the command-line solver, which applies the scramble to the cube model, solves the cross, F2L, OLL and PLL, then returns a move sequence. A separate optional renderer animates a supplied scramble and moves read from stdin; the README says it does not participate in solving. The graph also preserves the documented benchmark tool and algorithm-table capability. Edges reflect the excerpts, source index and README; unsampled command-line and benchmark internals are described only at the documented level.

Main entry points: [`solving/cfop.py`](https://github.com/nanborg/rubik/blob/main/solving/cfop.py) (CFOP orchestration), [`common/cube.py`](https://github.com/nanborg/rubik/blob/main/common/cube.py) (Cube state), [`render.py`](https://github.com/nanborg/rubik/blob/main/render.py) (Renderer entry), [`solving/f2l.py`](https://github.com/nanborg/rubik/blob/main/solving/f2l.py) (F2L solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_solver_cli["Solver CLI"]
  node_solution["Solution output"]
  node_benchmark["Benchmark tool"]
end

subgraph group_model["Cube model"]
  node_colors["Cube colors<br/>[colors.py]"]
  node_cube["Cube state<br/>[cube.py]"]
  node_moves["Moves and tables<br/>[moves.py]"]
end

subgraph group_solver["CFOP solving"]
  node_cfop["CFOP orchestration<br/>[cfop.py]"]
  node_cross["Cross solver<br/>[cross.py]"]
  node_f2l["F2L solver<br/>[f2l.py]"]
  node_oll["OLL solver<br/>[oll.py]"]
  node_pll["PLL solver<br/>[pll.py]"]
  node_search["Bidirectional search<br/>[search.py]"]
  node_f2l_data["F2L algorithms<br/>[f2l.txt]"]
  node_oll_data["OLL algorithms<br/>[oll.txt]"]
  node_pll_data["PLL algorithms<br/>[pll.txt]"]
end

subgraph group_visual["3D visualization"]
  node_renderer_cli["Renderer entry<br/>[render.py]"]
  node_mapping["Polygon mapping<br/>[mapping.py]"]
  node_animation["Animated cube"]
end

node_user(("User"))
node_pygame["Pygame"]

node_user -->|"provides scramble"| node_solver_cli
node_solver_cli -->|"requests solution"| node_cfop
node_cfop -->|"applies scramble"| node_cube
node_cfop -->|"solves cross"| node_cross
node_cfop -->|"solves F2L"| node_f2l
node_cfop -->|"solves OLL"| node_oll
node_cfop -->|"solves PLL"| node_pll
node_cfop -->|"returns moves"| node_solution
node_solver_cli -->|"prints solution"| node_solution
node_cross -->|"uses search"| node_search
node_f2l -->|"uses search"| node_search
node_f2l -->|"checks cross"| node_cross
node_f2l -->|"loads algorithms"| node_f2l_data
node_oll -->|"checks F2L"| node_f2l
node_oll -->|"loads algorithms"| node_oll_data
node_pll -->|"checks OLL"| node_oll
node_pll -->|"loads algorithms"| node_pll_data
node_cube -->|"uses colors"| node_colors
node_cube -->|"uses move turns"| node_moves
node_moves -->|"uses cube model"| node_cube
node_solver_cli -.->|"runs separately"| node_benchmark
node_user -->|"starts renderer"| node_renderer_cli
node_renderer_cli -->|"applies scramble"| node_cube
node_renderer_cli -->|"draws polygons"| node_mapping
node_renderer_cli -->|"animates moves"| node_animation
node_renderer_cli -.->|"uses optional library"| node_pygame
node_mapping -->|"maps positions"| node_cube
node_mapping -->|"maps colors"| node_colors

click node_solver_cli "https://github.com/nanborg/rubik/blob/main/rubik"
click node_benchmark "https://github.com/nanborg/rubik/blob/main/rubik_perf"
click node_colors "https://github.com/nanborg/rubik/blob/main/common/colors.py"
click node_cube "https://github.com/nanborg/rubik/blob/main/common/cube.py"
click node_moves "https://github.com/nanborg/rubik/blob/main/common/moves.py"
click node_cfop "https://github.com/nanborg/rubik/blob/main/solving/cfop.py"
click node_cross "https://github.com/nanborg/rubik/blob/main/solving/cross.py"
click node_f2l "https://github.com/nanborg/rubik/blob/main/solving/f2l.py"
click node_oll "https://github.com/nanborg/rubik/blob/main/solving/oll.py"
click node_pll "https://github.com/nanborg/rubik/blob/main/solving/pll.py"
click node_search "https://github.com/nanborg/rubik/blob/main/solving/search.py"
click node_f2l_data "https://github.com/nanborg/rubik/blob/main/data/cfop/f2l.txt"
click node_oll_data "https://github.com/nanborg/rubik/blob/main/data/cfop/oll.txt"
click node_pll_data "https://github.com/nanborg/rubik/blob/main/data/cfop/pll.txt"
click node_renderer_cli "https://github.com/nanborg/rubik/blob/main/render.py"
click node_mapping "https://github.com/nanborg/rubik/blob/main/rendering/mapping.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_solver_cli,node_solution,node_benchmark,node_user toneBlue
class node_colors,node_cube,node_moves toneAmber
class node_cfop,node_cross,node_f2l,node_oll,node_pll,node_search,node_f2l_data,node_oll_data,node_pll_data toneMint
class node_renderer_cli,node_mapping,node_animation toneRose
class node_pygame toneIndigo
```

## Components

### User interfaces

- [Solver CLI](https://github.com/nanborg/rubik/blob/main/rubik): `rubik`
- **Solution output**
- [Benchmark tool](https://github.com/nanborg/rubik/blob/main/rubik_perf): `rubik_perf`

### Cube model

- [Cube colors](https://github.com/nanborg/rubik/blob/main/common/colors.py): `common/colors.py`
- [Cube state](https://github.com/nanborg/rubik/blob/main/common/cube.py): `common/cube.py`
- [Moves and tables](https://github.com/nanborg/rubik/blob/main/common/moves.py): `common/moves.py`

### CFOP solving

- [CFOP orchestration](https://github.com/nanborg/rubik/blob/main/solving/cfop.py): `solving/cfop.py`
- [Cross solver](https://github.com/nanborg/rubik/blob/main/solving/cross.py): `solving/cross.py`
- [F2L solver](https://github.com/nanborg/rubik/blob/main/solving/f2l.py): `solving/f2l.py`
- [OLL solver](https://github.com/nanborg/rubik/blob/main/solving/oll.py): `solving/oll.py`
- [PLL solver](https://github.com/nanborg/rubik/blob/main/solving/pll.py): `solving/pll.py`
- [Bidirectional search](https://github.com/nanborg/rubik/blob/main/solving/search.py): `solving/search.py`
- [F2L algorithms](https://github.com/nanborg/rubik/blob/main/data/cfop/f2l.txt): `data/cfop/f2l.txt`
- [OLL algorithms](https://github.com/nanborg/rubik/blob/main/data/cfop/oll.txt): `data/cfop/oll.txt`
- [PLL algorithms](https://github.com/nanborg/rubik/blob/main/data/cfop/pll.txt): `data/cfop/pll.txt`

### 3D visualization

- [Renderer entry](https://github.com/nanborg/rubik/blob/main/render.py): `render.py`
- [Polygon mapping](https://github.com/nanborg/rubik/blob/main/rendering/mapping.py): `rendering/mapping.py`
- **Animated cube**

### Other components

- **User**
- **Pygame**

## Connections

- User → Solver CLI: provides scramble (evidence: `README.md`)
- Solver CLI → CFOP orchestration: requests solution (evidence: `README.md`)
- CFOP orchestration → Cube state: applies scramble (evidence: `solving/cfop.py`)
- CFOP orchestration → Cross solver: solves cross (evidence: `solving/cfop.py`)
- CFOP orchestration → F2L solver: solves F2L (evidence: `solving/cfop.py`)
- CFOP orchestration → OLL solver: solves OLL (evidence: `solving/cfop.py`)
- CFOP orchestration → PLL solver: solves PLL (evidence: `solving/cfop.py`)
- CFOP orchestration → Solution output: returns moves (evidence: `solving/cfop.py`)
- Solver CLI → Solution output: prints solution (evidence: `README.md`)
- Cross solver → Bidirectional search: uses search (evidence: `solving/cross.py`)
- F2L solver → Bidirectional search: uses search (evidence: `solving/f2l.py`)
- F2L solver → Cross solver: checks cross (evidence: `solving/f2l.py`)
- F2L solver → F2L algorithms: loads algorithms (evidence: `solving/f2l.py`)
- OLL solver → F2L solver: checks F2L (evidence: `solving/oll.py`)
- OLL solver → OLL algorithms: loads algorithms (evidence: `solving/oll.py`)
- PLL solver → OLL solver: checks OLL (evidence: `solving/pll.py`)
- PLL solver → PLL algorithms: loads algorithms (evidence: `solving/pll.py`)
- Cube state → Cube colors: uses colors (evidence: `common/cube.py`)
- Cube state → Moves and tables: uses move turns (evidence: `common/cube.py`)
- Moves and tables → Cube state: uses cube model (evidence: `common/moves.py`)
- Solver CLI → Benchmark tool: runs separately (evidence: `README.md`)
- User → Renderer entry: starts renderer (evidence: `README.md`)
- Renderer entry → Cube state: applies scramble (evidence: `render.py`)
- Renderer entry → Polygon mapping: draws polygons (evidence: `render.py`)
- Renderer entry → Animated cube: animates moves (evidence: `render.py`)
- Renderer entry → Pygame: uses optional library (evidence: `README.md`)
- Polygon mapping → Cube state: maps positions (evidence: `rendering/mapping.py`)
- Polygon mapping → Cube colors: maps colors (evidence: `rendering/mapping.py`)
