# antoine93/a2026-6gei608-lab2 architecture

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

- Interactive diagram: https://gitdiagram.com/antoine93/a2026-6gei608-lab2
- Repository: https://github.com/antoine93/a2026-6gei608-lab2

## Overview

This repository is a command-line AI lab with two distinct workflows: solving 8-puzzles using uninformed search or A*, and experimenting with Sudoku hill-climbing and genetic solvers. In the 8-puzzle flow, a user selects an input and algorithm; the program parses and checks the puzzle, runs repeated searches, and writes per-run measurements. The Sudoku runner parses and validates puzzles, invokes an algorithm supplied by its module, and records run logs and statistics. Connections for unsampled algorithm internals are omitted; Sudoku solver-to-runner dispatch is not shown in the excerpts.

Main entry points: [`main.py`](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/main.py) (8-Puzzle CLI), [`src/sudoku/runner.py`](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/runner.py) (Sudoku Runner), [`src/sudoku/commun.py`](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/commun.py) (Sudoku Primitives), [`src/solvers/commun.py`](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/commun.py) (Search Primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_eight["8-Puzzle Search"]
  node_main["8-Puzzle CLI<br/>[main.py]"]
  node_puzzle_inputs["Puzzle Inputs"]
  node_bfs["BFS Solver<br/>[bfs.py]"]
  node_dfs["DFS Solver<br/>[dfs.py]"]
  node_ids["IDS Solver<br/>[ids.py]"]
  node_astar["A* Solver<br/>[a_star.py]"]
  node_search_common["Search Primitives<br/>[commun.py]"]
  node_puzzle_results["Search Results"]
end

subgraph group_sudoku["Sudoku Search"]
  node_sudoku_inputs["Sudoku Inputs"]
  node_sudoku_parser["Sudoku Parser<br/>[parser.py]"]
  node_sudoku_runner["Sudoku Runner<br/>[runner.py]"]
  node_sudoku_common["Sudoku Primitives<br/>[commun.py]"]
  node_sudoku_hc["Hill Climbing<br/>[hill_climbing.py]"]
  node_genetic_hc["Genetic HC<br/>[genetic_hc.py]"]
  node_genetic_tournament["Genetic Tournament"]
  node_genetic_truncation["Genetic Truncation"]
  node_sudoku_results["Sudoku Results"]
end

subgraph group_shared["Shared Utilities"]
  node_puzzle_parser["Puzzle Parser<br/>[parser.py]"]
  node_solvability["Solvability Check<br/>[solvability.py]"]
  node_run_formatter["Run Formatter<br/>[formatter.py]"]
end

node_user(("CLI User"))

node_user -->|"selects puzzle"| node_main
node_main -->|"reads input"| node_puzzle_inputs
node_main -->|"parses puzzle"| node_puzzle_parser
node_main -->|"checks solvability"| node_solvability
node_main -->|"dispatches search"| node_bfs
node_main -->|"dispatches search"| node_dfs
node_main -->|"dispatches search"| node_ids
node_main -->|"dispatches search"| node_astar
node_bfs -->|"uses primitives"| node_search_common
node_dfs -->|"uses primitives"| node_search_common
node_ids -->|"uses primitives"| node_search_common
node_astar -->|"returns solution"| node_puzzle_results
node_main -->|"writes measurements"| node_run_formatter
node_main -->|"writes run files"| node_puzzle_results
node_user -->|"starts runs"| node_sudoku_runner
node_sudoku_runner -->|"loads puzzles"| node_sudoku_inputs
node_sudoku_runner -->|"parses puzzle"| node_sudoku_parser
node_sudoku_runner -->|"validates configuration"| node_sudoku_common
node_sudoku_runner -->|"writes run data"| node_run_formatter
node_sudoku_runner -->|"records statistics"| node_sudoku_results
node_sudoku_hc -->|"uses primitives"| node_sudoku_common
node_genetic_hc -->|"uses primitives"| node_sudoku_common
node_genetic_tournament -->|"uses primitives"| node_sudoku_common
node_genetic_truncation -->|"uses primitives"| node_sudoku_common

click node_main "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/main.py"
click node_puzzle_inputs "https://github.com/antoine93/a2026-6gei608-lab2/tree/main/data"
click node_puzzle_parser "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/utils/parser.py"
click node_solvability "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/utils/solvability.py"
click node_bfs "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/bfs.py"
click node_dfs "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/dfs.py"
click node_ids "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/ids.py"
click node_astar "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/a_star.py"
click node_search_common "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/commun.py"
click node_run_formatter "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/utils/formatter.py"
click node_puzzle_results "https://github.com/antoine93/a2026-6gei608-lab2/tree/main/results"
click node_sudoku_inputs "https://github.com/antoine93/a2026-6gei608-lab2/tree/main/data/input-sudoku"
click node_sudoku_parser "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/parser.py"
click node_sudoku_runner "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/runner.py"
click node_sudoku_common "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/commun.py"
click node_sudoku_hc "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/hill_climbing.py"
click node_genetic_hc "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/genetic_hc.py"
click node_genetic_tournament "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/genetic_tournament.py"
click node_genetic_truncation "https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/genetic_truncation.py"
click node_sudoku_results "https://github.com/antoine93/a2026-6gei608-lab2/tree/main/results/sudoku"

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,node_puzzle_inputs,node_bfs,node_dfs,node_ids,node_astar,node_search_common,node_puzzle_results,node_user toneBlue
class node_sudoku_inputs,node_sudoku_parser,node_sudoku_runner,node_sudoku_common,node_sudoku_hc,node_genetic_hc,node_genetic_tournament,node_genetic_truncation,node_sudoku_results toneAmber
class node_puzzle_parser,node_solvability,node_run_formatter toneMint
```

## Components

### 8-Puzzle Search

- [8-Puzzle CLI](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/main.py): `main.py`
- [Puzzle Inputs](https://github.com/antoine93/a2026-6gei608-lab2/tree/main/data): `data`
- [BFS Solver](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/bfs.py): `src/solvers/bfs.py`
- [DFS Solver](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/dfs.py): `src/solvers/dfs.py`
- [IDS Solver](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/ids.py): `src/solvers/ids.py`
- [A* Solver](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/a_star.py): `src/solvers/a_star.py`
- [Search Primitives](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/solvers/commun.py): `src/solvers/commun.py`
- [Search Results](https://github.com/antoine93/a2026-6gei608-lab2/tree/main/results): `results`

### Sudoku Search

- [Sudoku Inputs](https://github.com/antoine93/a2026-6gei608-lab2/tree/main/data/input-sudoku): `data/input-sudoku`
- [Sudoku Parser](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/parser.py): `src/sudoku/parser.py`
- [Sudoku Runner](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/runner.py): `src/sudoku/runner.py`
- [Sudoku Primitives](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/commun.py): `src/sudoku/commun.py`
- [Hill Climbing](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/hill_climbing.py): `src/sudoku/hill_climbing.py`
- [Genetic HC](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/genetic_hc.py): `src/sudoku/genetic_hc.py`
- [Genetic Tournament](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/genetic_tournament.py): `src/sudoku/genetic_tournament.py`
- [Genetic Truncation](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/sudoku/genetic_truncation.py): `src/sudoku/genetic_truncation.py`
- [Sudoku Results](https://github.com/antoine93/a2026-6gei608-lab2/tree/main/results/sudoku): `results/sudoku`

### Shared Utilities

- [Puzzle Parser](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/utils/parser.py): `src/utils/parser.py`
- [Solvability Check](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/utils/solvability.py): `src/utils/solvability.py`
- [Run Formatter](https://github.com/antoine93/a2026-6gei608-lab2/blob/main/src/utils/formatter.py): `src/utils/formatter.py`

### Other components

- **CLI User**

## Connections

- CLI User → 8-Puzzle CLI: selects puzzle (evidence: `README.md`)
- 8-Puzzle CLI → Puzzle Inputs: reads input (evidence: `README.md`)
- 8-Puzzle CLI → Puzzle Parser: parses puzzle (evidence: `main.py`)
- 8-Puzzle CLI → Solvability Check: checks solvability (evidence: `main.py`)
- 8-Puzzle CLI → BFS Solver: dispatches search (evidence: `main.py`)
- 8-Puzzle CLI → DFS Solver: dispatches search (evidence: `main.py`)
- 8-Puzzle CLI → IDS Solver: dispatches search (evidence: `main.py`)
- 8-Puzzle CLI → A* Solver: dispatches search (evidence: `main.py`)
- BFS Solver → Search Primitives: uses primitives (evidence: `src/solvers/bfs.py`)
- DFS Solver → Search Primitives: uses primitives (evidence: `src/solvers/dfs.py`)
- IDS Solver → Search Primitives: uses primitives (evidence: `src/solvers/ids.py`)
- A* Solver → Search Results: returns solution (evidence: `README.md`)
- 8-Puzzle CLI → Run Formatter: writes measurements (evidence: `main.py`)
- 8-Puzzle CLI → Search Results: writes run files (evidence: `README.md`)
- CLI User → Sudoku Runner: starts runs (evidence: `src/sudoku/runner.py`)
- Sudoku Runner → Sudoku Inputs: loads puzzles (evidence: `src/sudoku/runner.py`)
- Sudoku Runner → Sudoku Parser: parses puzzle (evidence: `src/sudoku/runner.py`)
- Sudoku Runner → Sudoku Primitives: validates configuration (evidence: `src/sudoku/runner.py`)
- Sudoku Runner → Run Formatter: writes run data (evidence: `src/sudoku/runner.py`)
- Sudoku Runner → Sudoku Results: records statistics (evidence: `src/sudoku/runner.py`)
- Hill Climbing → Sudoku Primitives: uses primitives (evidence: `src/sudoku/hill_climbing.py`)
- Genetic HC → Sudoku Primitives: uses primitives (evidence: `src/sudoku/genetic_hc.py`)
- Genetic Tournament → Sudoku Primitives: uses primitives (evidence: `src/sudoku/genetic_tournament.py`)
- Genetic Truncation → Sudoku Primitives: uses primitives (evidence: `src/sudoku/genetic_truncation.py`)
