# fikisipi/elkai architecture

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

- Interactive diagram: https://gitdiagram.com/fikisipi/elkai
- Repository: https://github.com/fikisipi/elkai

## Overview

##### Project type and purpose
- elkai is a Python library for solving Travelling Salesman Problems (TSP), wrapping and refactoring the C-based LKH heuristic solver.
- It exposes a clean Python API (`Coordinates2D`, `DistanceMatrix`, `solve_tsp()`) while embedding the LKH codebase as a C extension.

##### File structure
- Top-level:
- `elkai/` – Python package (wrapper code, types, utilities)
- `LKH-3.0.8/` – upstream LKH C solver source (Makefile, `.c` + `.h` files)
- `pyproject.toml`, `CMakeLists.txt` – build and packaging (scikit-build/CMake)
- `tests/` – pytest test suite
- `README.md`, `LICENSE` – documentation and license
- Key patterns:
- Native C library compiled via CMake (`LKH-3.0.8/SRC`)
- C extension glue (`elkai/_elkai.c`) exposing C functions as Python-callable
- Python API layer (`elkai/utils.py`, `elkai/types.py`)
- Build/deploy:
- `pyproject.toml` declares dependencies/build backend
- `CMakeLists.txt` integrates LKH source into the extension target

##### README for architecture insights
- Describes refactoring of LKH to eliminate global state
- Hook in `ReadProblem` to feed problems from memory
- Solution extracted from in-memory `Tour` structure into Python list
- Warning about GIL during solve phase
- Tests ensure correctness of wrapper and solver

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User/Application"
        PythonClient["Python Client"]:::python
    end

    subgraph "Elkai Python Package"
        Init["__init__.py"]:::python
        Types["types.py"]:::python
        Utils["utils.py"]:::python
        Deprecated["deprecated.py"]:::python
    end

    CE["_elkai.c"]:::c

    subgraph "LKH Native Solver"
        SRC["SRC"]:::c
    end

    subgraph "Build System"
        PyProj["pyproject.toml"]:::build
        CMake["CMakeLists.txt"]:::build
        UpMake["Makefile"]:::build
        Man["MANIFEST.in"]:::build
    end

    subgraph "Test Suite"
        Tests["tests/"]:::test
        PyIni["pytest.ini"]:::test
    end

    %% Data & Control Flows
    PythonClient -->|"calls API"| Types
    PythonClient -->|"calls API"| Utils
    Types -->|"uses glue"| CE
    Utils -->|"uses glue"| CE
    CE -->|"invokes functions"| SRC
    SRC -->|"Tour data"| CE
    CE -->|"returns solution"| Types

    %% Build Flows
    PyProj -->|defines build| CMake
    CMake -->|builds| CE
    CMake -->|compiles| SRC
    UpMake -->|builds upstream| SRC
    Man -->|includes manifests| PyProj

    %% Test Flows
    Tests -->|imports| Types
    Tests -->|imports| Utils
    Tests -->|calls C ext| CE
    PyIni -->|configures pytest| Tests

    %% Click Events
    click Init "https://github.com/fikisipi/elkai/blob/master/elkai/__init__.py"
    click Types "https://github.com/fikisipi/elkai/blob/master/elkai/types.py"
    click Utils "https://github.com/fikisipi/elkai/blob/master/elkai/utils.py"
    click Deprecated "https://github.com/fikisipi/elkai/blob/master/elkai/deprecated.py"
    click CE "https://github.com/fikisipi/elkai/blob/master/elkai/_elkai.c"
    click SRC "https://github.com/fikisipi/elkai/tree/master/LKH-3.0.8/SRC/"
    click CMake "https://github.com/fikisipi/elkai/blob/master/CMakeLists.txt"
    click PyProj "https://github.com/fikisipi/elkai/blob/master/pyproject.toml"
    click UpMake "https://github.com/fikisipi/elkai/tree/master/LKH-3.0.8/Makefile"
    click Tests "https://github.com/fikisipi/elkai/tree/master/tests/"
    click PyIni "https://github.com/fikisipi/elkai/blob/master/pytest.ini"
    click Man "https://github.com/fikisipi/elkai/blob/master/MANIFEST.in"

    %% Styles
    classDef python fill:#E0F7FA,stroke:#00796B,color:#004D40
    classDef c fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef build fill:#ECEFF1,stroke:#546E7A,color:#37474F
    classDef test fill:#FFEBEE,stroke:#C62828,color:#B71C1C
```
