# sumaia-a-k/sa-2026 architecture

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

- Interactive diagram: https://gitdiagram.com/sumaia-a-k/sa-2026
- Repository: https://github.com/sumaia-a-k/sa-2026

## Overview

SA-2026 is a multilingual teaching codebase for modeling search problems and comparing search algorithms. Its principal workflow is a program entry point selecting a problem and algorithm, solving through the problem’s search interface, and printing a solution or search statistics. The graph emphasizes the sampled Java workflow and the shared core abstractions; the README documents matching Python and C++ versions and additional problem examples. Greedy and A* are described as learning topics, but corresponding implementations are not present in the supplied tree. Links between unsampled algorithm implementations and problem models are omitted where the excerpts do not establish calls.

Main entry points: [`src/sa2026/Main.java`](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/Main.java) (Java Main), [`src/sa2026/core/Node.java`](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/Node.java) (Search node), [`src/sa2026/core/SearchAlgorithm.java`](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/SearchAlgorithm.java) (Search contract), [`src/sa2026/problems/maze/MazeProblem.java`](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/maze/MazeProblem.java) (Maze model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Program entry"]
  node_main["Java Main<br/>[Main.java]"]
end

subgraph group_core["Search core"]
  node_problem["Problem contract<br/>[Problem.java]"]
  node_algorithm["Search contract"]
  node_node["Search node<br/>[Node.java]"]
  node_state["State contract<br/>[State.java]"]
  node_action["Action contract<br/>[IAction.java]"]
end

subgraph group_algorithms["Search methods"]
  node_bfs["BFS variants<br/>[BFS.java]"]
  node_dfs["DFS variants<br/>[DFS.java]"]
  node_dls["Depth-limited DFS"]
  node_ids["Iterative deepening"]
  node_ucs["Uniform cost<br/>[UCS.java]"]
end

subgraph group_problems["Problem models"]
  node_maze["Maze model<br/>[MazeProblem.java]"]
  node_mazegrid["Maze grid<br/>[Maze.java]"]
  node_city["City map"]
  node_citydata["Road network<br/>[CityMap.java]"]
  node_puzzle["N-puzzle"]
  node_ladder["Word ladder"]
  node_dictionary["Word dictionary"]
end

node_student(("Student"))

node_student -->|"starts"| node_main
node_main -->|"selects"| node_bfs
node_main -->|"selects"| node_dfs
node_main -->|"selects"| node_dls
node_main -->|"selects"| node_ids
node_main -->|"selects"| node_ucs
node_main -->|"chooses"| node_maze
node_main -->|"chooses"| node_city
node_main -->|"chooses"| node_puzzle
node_main -->|"chooses"| node_ladder
node_problem -->|"delegates search"| node_algorithm
node_algorithm -->|"returns result"| node_node
node_node -->|"holds"| node_state
node_node -->|"records"| node_action
node_maze -->|"uses"| node_mazegrid
node_city -->|"uses"| node_citydata
node_ladder -->|"uses"| node_dictionary

click node_main "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/Main.java"
click node_problem "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/Problem.java"
click node_algorithm "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/SearchAlgorithm.java"
click node_node "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/Node.java"
click node_state "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/State.java"
click node_action "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/IAction.java"
click node_bfs "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/BFS.java"
click node_dfs "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/DFS.java"
click node_dls "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/DepthLimitedDFS.java"
click node_ids "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/IterativeDeepening.java"
click node_ucs "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/UCS.java"
click node_maze "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/maze/MazeProblem.java"
click node_mazegrid "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/maze/Maze.java"
click node_city "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/citymap/CityMapProblem.java"
click node_citydata "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/citymap/CityMap.java"
click node_puzzle "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/npuzzle/NpuzzleProblem.java"
click node_ladder "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/wordladder/WordLadderProblem.java"
click node_dictionary "https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/wordladder/WordDictionary.java"

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_problem,node_algorithm,node_node,node_state,node_action toneAmber
class node_bfs,node_dfs,node_dls,node_ids,node_ucs toneMint
class node_maze,node_mazegrid,node_city,node_citydata,node_puzzle,node_ladder,node_dictionary toneRose
class node_student toneIndigo
```

## Components

### Program entry

- [Java Main](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/Main.java): `src/sa2026/Main.java`

### Search core

- [Problem contract](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/Problem.java): `src/sa2026/core/Problem.java`
- [Search contract](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/SearchAlgorithm.java): `src/sa2026/core/SearchAlgorithm.java`
- [Search node](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/Node.java): `src/sa2026/core/Node.java`
- [State contract](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/State.java): `src/sa2026/core/State.java`
- [Action contract](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/core/IAction.java): `src/sa2026/core/IAction.java`

### Search methods

- [BFS variants](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/BFS.java): `src/sa2026/algorithms/BFS.java`
- [DFS variants](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/DFS.java): `src/sa2026/algorithms/DFS.java`
- [Depth-limited DFS](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/DepthLimitedDFS.java): `src/sa2026/algorithms/DepthLimitedDFS.java`
- [Iterative deepening](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/IterativeDeepening.java): `src/sa2026/algorithms/IterativeDeepening.java`
- [Uniform cost](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/algorithms/UCS.java): `src/sa2026/algorithms/UCS.java`

### Problem models

- [Maze model](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/maze/MazeProblem.java): `src/sa2026/problems/maze/MazeProblem.java`
- [Maze grid](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/maze/Maze.java): `src/sa2026/problems/maze/Maze.java`
- [City map](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/citymap/CityMapProblem.java): `src/sa2026/problems/citymap/CityMapProblem.java`
- [Road network](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/citymap/CityMap.java): `src/sa2026/problems/citymap/CityMap.java`
- [N-puzzle](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/npuzzle/NpuzzleProblem.java): `src/sa2026/problems/npuzzle/NpuzzleProblem.java`
- [Word ladder](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/wordladder/WordLadderProblem.java): `src/sa2026/problems/wordladder/WordLadderProblem.java`
- [Word dictionary](https://github.com/sumaia-a-k/sa-2026/blob/main/src/sa2026/problems/wordladder/WordDictionary.java): `src/sa2026/problems/wordladder/WordDictionary.java`

### Other components

- **Student**

## Connections

- Student → Java Main: starts (evidence: `README.md`)
- Java Main → BFS variants: selects (evidence: `src/sa2026/Main.java`)
- Java Main → DFS variants: selects (evidence: `src/sa2026/Main.java`)
- Java Main → Depth-limited DFS: selects (evidence: `src/sa2026/Main.java`)
- Java Main → Iterative deepening: selects (evidence: `src/sa2026/Main.java`)
- Java Main → Uniform cost: selects (evidence: `src/sa2026/Main.java`)
- Java Main → Maze model: chooses (evidence: `src/sa2026/Main.java`)
- Java Main → City map: chooses (evidence: `src/sa2026/Main.java`)
- Java Main → N-puzzle: chooses (evidence: `src/sa2026/Main.java`)
- Java Main → Word ladder: chooses (evidence: `src/sa2026/Main.java`)
- Problem contract → Search contract: delegates search (evidence: `src/sa2026/core/Problem.java`)
- Search contract → Search node: returns result (evidence: `src/sa2026/core/SearchAlgorithm.java`)
- Search node → State contract: holds (evidence: `src/sa2026/core/Node.java`)
- Search node → Action contract: records (evidence: `src/sa2026/core/Node.java`)
- Maze model → Maze grid: uses
- City map → Road network: uses
- Word ladder → Word dictionary: uses
