# marreco202/slidingpuzzlesolver architecture

> Architecture diagram of the GitHub repository marreco202/slidingpuzzlesolver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marreco202/slidingpuzzlesolver
- Repository: https://github.com/marreco202/slidingpuzzlesolver

## Overview

##### Project type and purpose
- This is a single‐language open‐source tool (Python) whose sole responsibility is to solve the 3×3 sliding puzzle.
- It generates the complete state graph (all 9! states), links valid moves as edges, runs a BFS traversal to compute metrics (max depth, node count, edge count, connected components), and outputs results to the console.

##### File structure
- Top level:
- main.py – the entry point and orchestrator.
- requirements.txt – Python dependencies (e.g., networkx or any graph library).
- README.md – project description, algorithms, and math.
- images/ – sample puzzle images for documentation only.
- .gitignore – standard VCS excludes.
- No backend/frontend split, no database or external service. All work is done in-memory via Python data structures.

##### Key insights from README
- Graph of size 362,880 vertices (9!).
- Recursive permutation generator without a conventional base case but driven by target length.
- Edge creation based on blank-tile adjacency (up/down/left/right).
- BFS used for solving and for computing graph properties.
- Two connected components arise from parity considerations in permutation groups.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input/Output Components
    CLI["Command-Line Interface\n(argparse)"]:::io
    OutputFormatter["Output Formatter\nprints results"]:::io

    %% Processing Stages
    PermutationGen["Permutation Generator\nDFS-style recursion"]:::processing
    GraphBuilder["Graph Builder\nbuilds adjacency dict"]:::processing
    BFSSolver["BFS Solver & Metrics Collector\nBFS queue loop"]:::processing
    AStar["A* Solver (extension)"]:::processing

    %% Documentation and Config
    subgraph Documentation
        README["README.md\nproject docs"]:::doc
        Images["images/"]:::doc
        Requirements["requirements.txt"]:::doc
        Gitignore[".gitignore"]:::doc
    end

    %% Workflow
    CLI -->|"initial input"| PermutationGen
    PermutationGen -->|"state list (list of 9-element tuples)"| GraphBuilder
    GraphBuilder -->|"adjacency map (dict)"| BFSSolver
    BFSSolver -->|"metrics, solved path"| OutputFormatter

    %% Extension Path
    GraphBuilder -.->|"state graph"| AStar
    AStar -->|"metrics, solved path"| OutputFormatter

    %% Click Events
    click CLI "https://github.com/marreco202/slidingpuzzlesolver/blob/main/main.py"
    click PermutationGen "https://github.com/marreco202/slidingpuzzlesolver/blob/main/main.py"
    click GraphBuilder "https://github.com/marreco202/slidingpuzzlesolver/blob/main/main.py"
    click BFSSolver "https://github.com/marreco202/slidingpuzzlesolver/blob/main/main.py"
    click OutputFormatter "https://github.com/marreco202/slidingpuzzlesolver/blob/main/main.py"
    click README "https://github.com/marreco202/slidingpuzzlesolver/blob/main/README.md"
    click Images "https://github.com/marreco202/slidingpuzzlesolver/tree/main/images/"
    click Requirements "https://github.com/marreco202/slidingpuzzlesolver/blob/main/requirements.txt"
    click Gitignore "https://github.com/marreco202/slidingpuzzlesolver/blob/main/.gitignore"

    %% Styles
    classDef io fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef doc fill:#F0E68C,stroke:#333,stroke-width:1px
```
