# shubhampatil11/rubiks-cube-solver architecture

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

- Interactive diagram: https://gitdiagram.com/shubhampatil11/rubiks-cube-solver
- Repository: https://github.com/shubhampatil11/rubiks-cube-solver

## Overview

1. This is a C++ Rubik’s Cube solving project built with CMake. The codebase is organized around three main concerns: cube state modeling, search-based solving, and pattern-database support for heuristic lookup.

2. The entry point is `main.cpp`, which likely wires together a chosen cube representation, solver strategy, and optional database loading/generation. The repository does not show a UI or service layer; it is primarily an algorithmic/CLI-style application.

3. The `Model/` subtree defines the cube domain model. `RubiksCube.h/.cpp` appears to be the core abstraction, while `RubiksCube1dArray.cpp`, `RubiksCube3dArray.cpp`, and `RubiksCubeBitboard.cpp` suggest multiple internal state representations for the same cube logic. This is an important architectural boundary: the solver can operate against different state encodings depending on performance tradeoffs.

4. `Model/PatternDatabase/PatternDatabase.h` indicates a model-facing interface for heuristic databases. This sits at the boundary between the cube state layer and the solver layer, allowing search algorithms to ask for estimated distances or lookup values rather than directly reasoning about cube geometry.

5. The `Solver/` directory contains several search strategies: `BFSSolver`, `DFSSolver`, `IDAstarSolver`, and `IDDFSSolver`. These are distinct algorithm modules rather than one monolithic solver, implying the application can choose between exhaustive search, depth-first search, iterative deepening variants, and heuristic-guided A* style solving.

6. The architecture likely flows from `main.cpp` into one of these solver implementations, which then manipulates a `RubiksCube` instance and optionally consults a pattern database. The solver layer is therefore the orchestration point, while the model layer owns cube state transitions and legality of moves.

7. The `PatternDatabases/` directory is a separate subsystem for building and using heuristic tables. It includes `CornerDBMaker.cpp/.h`, `CornerPatternDatabase.cpp/.h`, `PatternDatabase.cpp/.h`, `PermutationIndexer.h`, `NibbleArray.cpp/.h`, and small math helpers. This suggests a compact encoded database structure, likely optimized for storing heuristic distances for cube corner permutations/orientations.

8. `CornerDBMaker` implies offline or precomputation-style database generation, while `CornerPatternDatabase` and `PatternDatabase` are the runtime lookup components. The presence of `PermutationIndexer` and `NibbleArray` indicates the database is indexed combinatorially and stored densely to reduce memory footprint.

9. The `Databases/` folder contains at least one concrete artifact, `cornerDepth5V1.txt`. This is likely a generated heuristic table or precomputed state-depth dataset consumed by the pattern-database code, which means the repository separates database generation from database usage.

10. The project has a clear layering boundary: model code knows cube state and moves, pattern-database code knows compact heuristic indexing/storage, and solver code knows search strategy. That separation is important for an architecture diagram because the solver depends on both lower layers, but those lower layers do not depend on the solver.

11. The multiple cube representations suggest performance experimentation is a key design goal. An architecture diagram should show these as alternative implementations behind a common cube interface or common behavior set, rather than as separate applications.

12. Overall, the system is best understood as an offline/algorithmic solver pipeline: build or load a heuristic database, instantiate a cube state in a chosen representation, run a selected search algorithm, and produce a solved move sequence. There are no obvious external services, persistence systems, or network boundaries beyond local file-based database artifacts.

Main entry points: [`Model/RubiksCube.h`](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube.h) (Rubik's Cube), [`main.cpp`](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/main.cpp) (main.cpp), [`PatternDatabases/CornerDBMaker.h`](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/CornerDBMaker.h) (DB Maker), [`PatternDatabases/CornerPatternDatabase.h`](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/CornerPatternDatabase.h) (Corner PDB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["main.cpp<br/>entrypoint<br/>[main.cpp]"]
end

subgraph group_model["Cube Model"]
  node_rubiks_cube["Rubik's Cube<br/>cube interface<br/>[RubiksCube.h]"]
  node_cube_1d["1D Array<br/>cube state"]
  node_cube_3d["3D Array<br/>cube state"]
  node_cube_bitboard["Bitboard<br/>cube state"]
  node_model_pdb_iface["Model PDB<br/>heuristic interface<br/>[PatternDatabase.h]"]
end

subgraph group_solver["Search Solvers"]
  node_bfs["BFS<br/>search solver<br/>[BFSSolver.h]"]
  node_dfs["DFS<br/>search solver<br/>[DFSSolver.h]"]
  node_idastar["IDA*<br/>heuristic solver<br/>[IDAstarSolver.h]"]
  node_iddfs["IDDFS<br/>search solver<br/>[IDDFSSolver.h]"]
end

subgraph group_pdb["Pattern Databases"]
  node_pdb_base["PDB Base<br/>database core<br/>[PatternDatabase.h]"]
  node_corner_pdb["Corner PDB<br/>heuristic db"]
  node_corner_maker["DB Maker<br/>offline builder<br/>[CornerDBMaker.h]"]
  node_perm_indexer["Indexer<br/>combinatorics"]
  node_nibble_array["Nibble Array<br/>packed storage<br/>[NibbleArray.h]"]
  node_math_helpers["Math Helpers<br/>support library<br/>[math.h]"]
end

subgraph group_data["Database Artifact"]
  node_corner_db_file["cornerDepth5V1.txt<br/>data artifact<br/>[cornerDepth5V1.txt]"]
end

node_main -->|"creates"| node_rubiks_cube
node_main -->|"selects"| node_bfs
node_main -->|"selects"| node_dfs
node_main -->|"selects"| node_idastar
node_main -->|"selects"| node_iddfs
node_main -->|"loads"| node_corner_pdb
node_main -->|"builds"| node_corner_maker
node_rubiks_cube -.->|"impl"| node_cube_1d
node_rubiks_cube -.->|"impl"| node_cube_3d
node_rubiks_cube -.->|"impl"| node_cube_bitboard
node_bfs -->|"searches"| node_rubiks_cube
node_dfs -->|"searches"| node_rubiks_cube
node_idastar -->|"searches"| node_rubiks_cube
node_iddfs -->|"searches"| node_rubiks_cube
node_idastar -->|"heuristic"| node_model_pdb_iface
node_corner_pdb -->|"extends"| node_pdb_base
node_corner_pdb -->|"adapts"| node_model_pdb_iface
node_corner_maker -->|"generates"| node_corner_pdb
node_corner_maker -->|"indexes"| node_perm_indexer
node_corner_maker -->|"stores"| node_nibble_array
node_corner_maker -->|"uses"| node_math_helpers
node_corner_pdb -->|"reads"| node_corner_db_file
node_pdb_base -->|"uses"| node_perm_indexer
node_pdb_base -->|"uses"| node_nibble_array

click node_main "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/main.cpp"
click node_rubiks_cube "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube.h"
click node_cube_1d "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube1dArray.cpp"
click node_cube_3d "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube3dArray.cpp"
click node_cube_bitboard "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCubeBitboard.cpp"
click node_model_pdb_iface "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/PatternDatabase/PatternDatabase.h"
click node_bfs "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/BFSSolver.h"
click node_dfs "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/DFSSolver.h"
click node_idastar "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/IDAstarSolver.h"
click node_iddfs "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/IDDFSSolver.h"
click node_pdb_base "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/PatternDatabase.h"
click node_corner_pdb "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/CornerPatternDatabase.h"
click node_corner_maker "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/CornerDBMaker.h"
click node_perm_indexer "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/PermutationIndexer.h"
click node_nibble_array "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/NibbleArray.h"
click node_math_helpers "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/math.h"
click node_corner_db_file "https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Databases/cornerDepth5V1.txt"

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_main toneBlue
class node_rubiks_cube,node_cube_1d,node_cube_3d,node_cube_bitboard,node_model_pdb_iface toneAmber
class node_bfs,node_dfs,node_idastar,node_iddfs toneMint
class node_pdb_base,node_corner_pdb,node_corner_maker,node_perm_indexer,node_nibble_array,node_math_helpers toneRose
class node_corner_db_file toneIndigo
```

## Components

### Application

CLI entry and top-level wiring.

- [main.cpp](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/main.cpp): entrypoint · Program entry point that selects cube state, solver, and database use. · `main.cpp`

### Cube Model

Cube state abstraction and alternative internal representations.

- [Rubik's Cube](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube.h): cube interface · Core cube abstraction shared across the solver and representations. · `Model/RubiksCube.h`
- [1D Array](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube1dArray.cpp): cube state · One concrete cube representation optimized around a flat array layout. · `Model/RubiksCube1dArray.cpp`
- [3D Array](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCube3dArray.cpp): cube state · One concrete cube representation using a 3D array layout. · `Model/RubiksCube3dArray.cpp`
- [Bitboard](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/RubiksCubeBitboard.cpp): cube state · Compact bit-level cube representation for performance experimentation. · `Model/RubiksCubeBitboard.cpp`
- [Model PDB](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Model/PatternDatabase/PatternDatabase.h): heuristic interface · Model-facing pattern-database abstraction used by solving code. · `Model/PatternDatabase/PatternDatabase.h`

### Search Solvers

Alternative search strategies for solving the cube.

- [BFS](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/BFSSolver.h): search solver · Breadth-first search solver implementation. · `Solver/BFSSolver.h`
- [DFS](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/DFSSolver.h): search solver · Depth-first search solver implementation. · `Solver/DFSSolver.h`
- [IDA*](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/IDAstarSolver.h): heuristic solver · Iterative deepening A* solver using heuristic guidance. · `Solver/IDAstarSolver.h`
- [IDDFS](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Solver/IDDFSSolver.h): search solver · Iterative deepening depth-first solver implementation. · `Solver/IDDFSSolver.h`

### Pattern Databases

Heuristic database interfaces, encodings, and builders.

- [PDB Base](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/PatternDatabase.h): database core · Shared pattern-database infrastructure and storage logic. · `PatternDatabases/PatternDatabase.h`
- [Corner PDB](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/CornerPatternDatabase.h): heuristic db · Runtime corner-pattern database used for heuristic lookup. · `PatternDatabases/CornerPatternDatabase.h`
- [DB Maker](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/CornerDBMaker.h): offline builder · Generates pattern-database tables from cube-state exploration. · `PatternDatabases/CornerDBMaker.h`
- [Indexer](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/PermutationIndexer.h): combinatorics · Maps permutations or orientations to dense database indices. · `PatternDatabases/PermutationIndexer.h`
- [Nibble Array](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/NibbleArray.h): packed storage · Compact packed array used to store small database values densely. · `PatternDatabases/NibbleArray.h`
- [Math Helpers](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/PatternDatabases/math.h): support library · Small utility math routines for database indexing and generation. · `PatternDatabases/math.h`

### Database Artifact

Generated heuristic data stored on disk.

- [cornerDepth5V1.txt](https://github.com/shubhampatil11/rubiks-cube-solver/blob/main/Databases/cornerDepth5V1.txt): data artifact · Generated depth table consumed by pattern-database code. · `Databases/cornerDepth5V1.txt`

## Connections

- main.cpp → Rubik's Cube: creates · Entry point instantiates the cube model used by the chosen solver.
- main.cpp → BFS: selects · Main can dispatch to the BFS solver.
- main.cpp → DFS: selects · Main can dispatch to the DFS solver.
- main.cpp → IDA*: selects · Main can dispatch to the heuristic IDA* solver.
- main.cpp → IDDFS: selects · Main can dispatch to the IDDFS solver.
- main.cpp → Corner PDB: loads · Main can load a heuristic database for solving.
- main.cpp → DB Maker: builds · Main can invoke database generation tooling.
- Rubik's Cube → 1D Array: impl · One concrete cube representation behind the common cube abstraction.
- Rubik's Cube → 3D Array: impl · One concrete cube representation behind the common cube abstraction.
- Rubik's Cube → Bitboard: impl · One concrete cube representation behind the common cube abstraction.
- BFS → Rubik's Cube: searches · Breadth-first search expands cube states.
- DFS → Rubik's Cube: searches · Depth-first search expands cube states.
- IDA* → Rubik's Cube: searches · IDA* explores cube states while evaluating heuristic cost.
- IDDFS → Rubik's Cube: searches · IDDFS explores cube states with iterative deepening.
- IDA* → Model PDB: heuristic · Heuristic solver queries the model-facing pattern database interface.
- Corner PDB → PDB Base: extends · Corner database builds on shared pattern-database infrastructure.
- Corner PDB → Model PDB: adapts · Runtime database exposes the model-level heuristic interface.
- DB Maker → Corner PDB: generates · Offline builder produces the concrete corner database.
- DB Maker → Indexer: indexes · Database generation relies on combinatorial indexing.
- DB Maker → Nibble Array: stores · Generated values are packed into compact storage.
- DB Maker → Math Helpers: uses · Builder uses helper math routines for table construction.
- Corner PDB → cornerDepth5V1.txt: reads · Runtime database loads generated depth data from disk.
- PDB Base → Indexer: uses · Shared database logic depends on combinatorial indexing.
- PDB Base → Nibble Array: uses · Shared database logic uses packed storage.
