# martinmenchon/move_the_box_solver architecture

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

- Interactive diagram: https://gitdiagram.com/martinmenchon/move_the_box_solver
- Repository: https://github.com/martinmenchon/move_the_box_solver

## Overview

##### Main Components
- Data Sources:
- The “data” directory holds CSV files that define game levels (e.g., level_22-3.csv in the Miami folder under North_America).
- The “assets” and “imgs” directories store visual resources used in the UI and for level illustrations.
- Core Application Modules (located in the “src” directory):
- UI Module (src/UI.py): Manages user interaction, displays images or level states, and possibly collects input.
- BFS Module (src/bfs.py): Implements the breadth-first search algorithm that likely drives the puzzle-solving logic.
- Constants (src/constants.py): Contains configuration values or game rules needed across the modules.
- Main Module (src/main.py): Serves as the entry point, wiring up all necessary modules and coordinating the workflow.
- External Visual and Configuration Elements:
- README and LICENSE files serve as documentation.
- .gitattributes and .gitignore for version control configuration.

##### Establish Relationships and Interactions
- Data Flow:
- The “data” component feeds level definitions into the core application via the “main” module, which then uses the “board” module to build a game state.
- Functional Flow:
- The main module is the orchestrating component: it initially loads level data, instantiates a board, invokes BFS to solve the puzzle, and then calls the UI module to show the results.
- The BFS algorithm (solver) interacts with the board module to evaluate moves by checking valid states using predefined constants.
- Interaction Patterns:
- There is a clear separation of concerns: the data/input part (levels and assets) is separated from the logic (BFS and board handling) and the presentation (UI). This loosely resembles a layered or modular architecture.

##### Architectural Patterns and Design Principles
- Modularity: The system is split into independent functional modules (UI, BFS, board, constants) that communicate through well-defined interfaces.
- Separation of Concerns: Input (data files and assets) is clearly separated from processing (board and BFS) and presentation (UI).
- Extensibility: Adding new levels or adjusting game rules is straightforward due to the modular design.

##### Relevant Technologies and Frameworks
- Python is the primary programming language.
- The use of CSV files and file directories to store levels indicates a file-based approach for configuration.

##### Detailed Steps
- “Board (src/board.py)”
- “BFS Solver (src/bfs.py)”
- “Constants (src/constants.py)”
These, showing that Main uses them.
e. Optionally, show bidirectional communication where needed (e.g., UI could send commands or updates back if there’s interactivity).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Assets Layer
    subgraph "Data & Assets Layer"
        CSV["CSV Level File"]:::dataLayer
        Assets["Assets Directory"]:::dataLayer
        Imgs["Imgs Directory"]:::dataLayer
    end

    %% Core Logic / Processing Layer
    subgraph "Logic/Processing Layer"
        Main["Main Module (src/main.py)"]:::logicLayer
        Board["Game Board (src/board.py)"]:::logicLayer
        BFS["BFS Solver (src/bfs.py)"]:::logicLayer
        Constants["Constants (src/constants.py)"]:::logicLayer
    end

    %% Presentation/UI Layer
    subgraph "Presentation Layer"
        UI["UI Module (src/UI.py)"]:::uiLayer
    end

    %% Documentation & Versioning
    subgraph "Documentation & Config"
        README["README.md"]:::docLayer
        LICENSE["LICENSE"]:::docLayer
        GitAttr[".gitattributes"]:::docLayer
        GitIgnore[".gitignore"]:::docLayer
    end

    %% Data Flow Connections
    CSV -->|"loads"| Main
    Assets -->|"provides visuals"| UI
    Imgs -->|"provides images"| UI

    Main -->|"initializes"| Board
    Main -->|"calls"| BFS
    Main -->|"uses"| Constants

    Board -->|"renders state"| UI

    %% Documentation relation (informational)
    Main ---|"documented_by"| README

    %% Click Events
    click CSV "https://github.com/martinmenchon/move_the_box_solver/blob/master/data/levels/North_America/Miami/level_22-3.csv"
    click Assets "https://github.com/martinmenchon/move_the_box_solver/tree/master/assets"
    click Imgs "https://github.com/martinmenchon/move_the_box_solver/tree/master/imgs"
    click UI "https://github.com/martinmenchon/move_the_box_solver/blob/master/src/UI.py"
    click BFS "https://github.com/martinmenchon/move_the_box_solver/blob/master/src/bfs.py"
    click Board "https://github.com/martinmenchon/move_the_box_solver/blob/master/src/board.py"
    click Constants "https://github.com/martinmenchon/move_the_box_solver/blob/master/src/constants.py"
    click Main "https://github.com/martinmenchon/move_the_box_solver/blob/master/src/main.py"
    click README "https://github.com/martinmenchon/move_the_box_solver/blob/master/README.md"
    click LICENSE "https://github.com/martinmenchon/move_the_box_solver/tree/master/LICENSE"
    click GitAttr "https://github.com/martinmenchon/move_the_box_solver/blob/master/.gitattributes"
    click GitIgnore "https://github.com/martinmenchon/move_the_box_solver/blob/master/.gitignore"

    %% Style Definitions
    classDef dataLayer fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef logicLayer fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef uiLayer fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;
    classDef docLayer fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
```
