# richardoberdieck/opti_fit architecture

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

- Interactive diagram: https://gitdiagram.com/richardoberdieck/opti_fit
- Repository: https://github.com/richardoberdieck/opti_fit

## Overview

##### Project Type and Purpose
- This is an open-source Python CLI tool/library (“opti_fit”) for computing optimal string-matching thresholds via various mathematical models (simple, relaxed, combination) using Gurobi as the solver. It bundles:
- Data (raw CSV/.mst)
- Model definitions (Python modules under `opti_fit/models`)
- Runner scripts (CLI entrypoints under `opti_fit/runners`)
- Utility functions (`opti_fit/utils`)
- Documentation site powered by MkDocs (`mkdocs.yml` + `docs/…`)
- Tests and CI workflows

##### Key Components
a. CLI Layer
- hatch-managed entrypoints (`hatch run simple|relaxed|combination|compare`)
- Shell wrapper (`runs.sh`)
b. Runner Modules (`opti_fit/runners/*.py`)
- Parse CLI args
- Invoke dataset loading & model building
- Dispatch job to solver (Gurobi)
- Collect and persist results (JSON under `results/`)
c. Model Layer (`opti_fit/models/*.py`)
- `simple_model.py`, `relaxed_model.py`, `models.py` (algorithm-combination)
- Variables, constraints, objectives for each variant
d. Utility Layer (`opti_fit/utils/*.py`)
- `dataset_utils`: load/compress/prepare datasets
- `model_utils`: common model-building helpers
- `runner_utils`: result formatting & storage
e. Data & Results
- Raw data in `data/`
- Output JSON in `results/`
f. Documentation & CI
- MkDocs site (`docs/`, `mkdocs.yml`)
- GitHub Actions workflows (`.github/workflows/*.yaml`)
- Pre-commit config, tests under `tests/`

##### Relationships & Data Flow
1. User invokes CLI (`hatch run …` or `runs.sh`)
2. Runner module parses options → calls dataset_utils to load data
3. Runner passes data + parameters to the chosen Model class
4. Model module constructs a Gurobi model via model_utils
5. Model is solved by Gurobi (external service)
6. runner_utils formats and writes the output JSON to `results/`
7. Optionally, generate images via `generate_images.py` or build docs via MkDocs

##### Architectural Patterns & Principles
- Layered architecture (CLI → Runners → Models → Utils → Solver)
- Separation of concerns: data loading vs. model definition vs. result handling
- Extensibility: add new model by dropping in `opti_fit/models/new_model.py` and corresponding runner
- Configuration via `pyproject.toml` and environment variables (`gurobi.env`)
- CI/CD pipeline for tests, linting, and docs publishing

- “opti_fit” package containing Models / Runners / Utils
- “Infrastructure” containing Gurobi, file system (data/results), CI/CD, Docs host

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "opti_fit (Code Modules)"
        subgraph "CLI Layer"
            CLI["hatch run entrypoints\n(pyproject.toml)"]:::code
            Shell["runs.sh"]:::code
        end
        subgraph "Runners"
            RunSimple["run_simple_model.py"]:::code
            RunRelaxed["run_relaxed_model.py"]:::code
            RunCombo["run_algorithm_combination.py"]:::code
            RunCompare["run_solver_comparison.py"]:::code
        end
        subgraph "Models"
            SimpleModel["simple_model.py"]:::code
            RelaxedModel["relaxed_model.py"]:::code
            ComboModel["models.py"]:::code
        end
        subgraph "Utils"
            DataUtils["dataset_utils.py"]:::code
            ModelUtils["model_utils.py"]:::code
            RunnerUtils["runner_utils.py"]:::code
        end
    end

    subgraph "Infrastructure"
        DataStore[("Data Store\n(CSV/MST)")]:::data
        ResultsStore[("Results Store\n(JSON)")]:::data
        Gurobi(("Gurobi Solver")):::external
        DocsSite[/"Docs Site (MkDocs)"/]:::docs
        MkdocsConf["mkdocs.yml"]:::docs
        DocsDir["docs/"]:::docs
        subgraph "CI/CD"
            Checks["automatic_checks.yaml"]:::docs
            DocsCI["docs.yaml"]:::docs
            PreCommit[".pre-commit-config.yaml"]:::docs
        end
    end

    CLI -->|invoke| RunSimple
    CLI -->|invoke| RunRelaxed
    CLI -->|invoke| RunCombo
    CLI -->|invoke| RunCompare
    Shell -->|invoke| RunSimple
    Shell -->|invoke| RunRelaxed
    Shell -->|invoke| RunCombo
    Shell -->|invoke| RunCompare

    RunSimple -->|parse args| DataUtils
    RunRelaxed -->|parse args| DataUtils
    RunCombo -->|parse args| DataUtils
    RunCompare -->|parse args| DataUtils

    DataUtils -->|load CSV/MST| DataStore

    RunSimple -->|call| ModelUtils
    RunRelaxed -->|call| ModelUtils
    RunCombo -->|call| ModelUtils
    RunCompare -->|call| ModelUtils

    ModelUtils -->|build model| SimpleModel
    ModelUtils -->|build model| RelaxedModel
    ModelUtils -->|build model| ComboModel

    SimpleModel -->|solve| Gurobi
    RelaxedModel -->|solve| Gurobi
    ComboModel -->|solve| Gurobi

    Gurobi -->|return solution| RunnerUtils

    RunSimple -->|format| RunnerUtils
    RunRelaxed -->|format| RunnerUtils
    RunCombo -->|format| RunnerUtils
    RunCompare -->|format| RunnerUtils

    RunnerUtils -->|write JSON| ResultsStore

    MkdocsConf -.-> DocsSite
    DocsDir -.-> DocsSite

    Checks -.-> DocsSite
    DocsCI -.-> DocsSite
    PreCommit -.-> DocsSite

    click CLI "https://github.com/richardoberdieck/opti_fit/blob/main/pyproject.toml"
    click Shell "https://github.com/richardoberdieck/opti_fit/blob/main/runs.sh"
    click RunSimple "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/runners/run_simple_model.py"
    click RunRelaxed "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/runners/run_relaxed_model.py"
    click RunCombo "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/runners/run_algorithm_combination.py"
    click RunCompare "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/runners/run_solver_comparison.py"
    click SimpleModel "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/models/simple_model.py"
    click RelaxedModel "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/models/relaxed_model.py"
    click ComboModel "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/models/models.py"
    click DataUtils "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/utils/dataset_utils.py"
    click ModelUtils "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/utils/model_utils.py"
    click RunnerUtils "https://github.com/richardoberdieck/opti_fit/blob/main/opti_fit/utils/runner_utils.py"
    click DataStore "https://github.com/richardoberdieck/opti_fit/blob/main/data/full_dataset.csv.gz"
    click ResultsStore "https://github.com/richardoberdieck/opti_fit/tree/main/results/"
    click MkdocsConf "https://github.com/richardoberdieck/opti_fit/blob/main/mkdocs.yml"
    click DocsDir "https://github.com/richardoberdieck/opti_fit/tree/main/docs/"
    click Checks "https://github.com/richardoberdieck/opti_fit/blob/main/.github/workflows/automatic_checks.yaml"
    click DocsCI "https://github.com/richardoberdieck/opti_fit/blob/main/.github/workflows/docs.yaml"
    click PreCommit "https://github.com/richardoberdieck/opti_fit/blob/main/.pre-commit-config.yaml"

    classDef code fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef data fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef external fill:#FAD7A0,stroke:#CA6F1E,color:#78281F
    classDef docs fill:#EBEDEF,stroke:#566573,color:#1C2833
```
