# hanhtrang256/gem-hunter-cnf architecture

> Architecture diagram of the GitHub repository hanhtrang256/gem-hunter-cnf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanhtrang256/gem-hunter-cnf
- Repository: https://github.com/hanhtrang256/gem-hunter-cnf

## Overview

##### Main Components
- Input/Testing Component:
– Use the “testcases” directory which holds the input files (input_*.txt) and expected output files (output_*.txt).
– This represents the various game instances and the solution benchmarks.
- Core Application (Main Driver):
– Represent the “src/main.py” as the central coordinator. It is responsible for taking inputs, triggering grid generation, calling one of the solving algorithms, and then possibly managing statistics.
- Grid and CNF Preparation:
– “src/grid_generate.py” is responsible for generating the game grids.
– The “src/util” folder contains modules such as “grid_function.py” and “cnf_function.py” that are used for handling grid operations and CNF-related functionalities.
- Algorithm Modules:
– Under “src/algorithm”, there are three core modules:
▪ “brute_force_sol.py” for the brute force solution.
▪ “backtrack_sol.py” for the backtracking solution.
▪ “pysat_sol.py” which leverages an external library (pysat) to solve the CNF formulation.
– These modules represent distinct strategies or algorithms that can be selected depending on the game’s instance or experimental comparison.
- Statistics and Reporting:
– “src/statistics.py” (and its accompanying “statistics.txt”) likely track performance metrics, execution time, or other aspects of the solution process.
- External Dependencies:
– The README also highlights the use of the “pysat” library, so this should be noted as an external service or tool integrated via the pysat solution pathway.

##### Relationships and Data Flow
– The grid generation module (grid_generate.py) for preparing game representations.
– The utility modules (within src/util) that prepare data transformations, such as generating CNF formulas.
– The algorithm modules (under src/algorithm), where main.py selects or routes data to the appropriate solving strategy (brute force, backtrack, or pysat).
- After processing, results might be collected and logged by the statistics module.
- That the pysat module interfaces with an external library; drawing an edge labeled “pysat library” from the pysat solution component to an “External Library” node is advisable.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each folder (algorithm, util, etc.) is responsibly segregated by its function.
- Modularity: The various algorithm implementations allow easy swapping and comparative analysis.
- Extensibility: The clear separation of algorithmic components makes it straightforward to add more solving techniques in the future.
- That while there isn’t a traditional MVC layout, the system does reflect a layered approach—input handling, processing (grid + CNF conversion), algorithm execution, and result / statistics collection.

## Diagram (Mermaid)

```mermaid
flowchart TB
    A["User/Test Cases"]:::input
    B["Main Driver (main.py)"]:::core
    C["Grid Generation (grid_generate.py)"]:::core
    D["Utility Functions (grid_function.py, cnf_function.py)"]:::utility

    subgraph "Algorithm Modules"
        E["Brute Force Solver (brute_force_sol.py)"]:::algorithm
        F["Backtracking Solver (backtrack_sol.py)"]:::algorithm
        G["Pysat Solver (pysat_sol.py)"]:::algorithm
    end

    H["External Library (pysat)"]:::external
    I["Statistics and Reporting (statistics.py)"]:::stats

    %% Connections
    A -->|"InputGrid"| B
    B -->|"TriggerGridGen"| C
    C -->|"GenerateGrid"| D
    D -->|"SolveWithBrute"| E
    D -->|"SolveWithBacktrack"| F
    D -->|"SolveWithPysat"| G
    G -->|"UsesPysat"| H
    E -->|"ReportResults"| I
    F -->|"ReportResults"| I
    G -->|"ReportResults"| I

    %% Click Events
    click A "https://github.com/hanhtrang256/gem-hunter-cnf/tree/main/testcases/"
    click B "https://github.com/hanhtrang256/gem-hunter-cnf/blob/main/src/main.py"
    click C "https://github.com/hanhtrang256/gem-hunter-cnf/blob/main/src/grid_generate.py"
    click D "https://github.com/hanhtrang256/gem-hunter-cnf/tree/main/src/util/"
    click E "https://github.com/hanhtrang256/gem-hunter-cnf/blob/main/src/algorithm/brute_force_sol.py"
    click F "https://github.com/hanhtrang256/gem-hunter-cnf/blob/main/src/algorithm/backtrack_sol.py"
    click G "https://github.com/hanhtrang256/gem-hunter-cnf/blob/main/src/algorithm/pysat_sol.py"
    click I "https://github.com/hanhtrang256/gem-hunter-cnf/blob/main/src/statistics.py"

    %% Styles
    classDef input fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#b3cde0,stroke:#333,stroke-width:2px;
    classDef utility fill:#ccebc5,stroke:#333,stroke-width:2px;
    classDef algorithm fill:#decbe4,stroke:#333,stroke-width:2px;
    classDef external fill:#fbb4ae,stroke:#333,stroke-width:2px;
    classDef stats fill:#fed9a6,stroke:#333,stroke-width:2px;
```
