# hoob028/math-solver architecture

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

- Interactive diagram: https://gitdiagram.com/hoob028/math-solver
- Repository: https://github.com/hoob028/math-solver

## Overview

1. **Repository purpose**
   - This is a small **Python command-line application** for solving nonlinear equations.
   - It supports three numerical methods: **bisection**, **Newton**, and **secant**.
   - In addition to computing a root, it also **records iteration history** and **produces plots**.

2. **Top-level orchestration**
   - `main.py` is the application entry point.
   - It likely coordinates the full flow: read user input, parse the equation and parameters, run the selected solver, save iteration data, and trigger plot generation.

3. **Parsing / input boundary**
   - `core/parser.py` is the input-validation and transformation layer.
   - Its role is to take the interactive text input from the user and convert it into a form the numerical methods can use, likely including the function expression and numeric bounds/guesses.

4. **Numerical computation core**
   - `core/methods.py` contains the actual root-finding algorithms.
   - This is the computational heart of the repo and is the main subsystem that should be shown as isolated from UI and storage.
   - The methods probably return both the final approximation and a structured iteration trace.

5. **Persistence / history storage**
   - `data/storage.py` is the data persistence layer.
   - Based on the README, the app saves files into an `output` directory, so this module likely writes iteration history and/or computed results there.
   - This is a separate boundary from computation: solvers generate data, storage handles file output.

6. **Visualization layer**
   - `ui/plotter.py` is responsible for graphing results.
   - It likely takes the function, intervals/guesses, and iteration history, then produces a plot saved to disk in `output`.
   - This is a presentation layer, not part of the numerical core.

7. **Data flow through the system**
   - The main flow is: **interactive input → parser → selected method in `core/methods.py` → iteration history/result → storage and plotting**.
   - The solver layer is the central dependency; parser, storage, and plotter are supporting layers around it.

8. **Boundary between computation and presentation**
   - The architecture clearly separates **math logic** from **I/O concerns**.
   - `core/` is the algorithmic layer, `data/` is for persistence, and `ui/` is for visualization.
   - This makes the code easier to test because the algorithms can be validated independently of file generation and plotting.

9. **Testing structure**
   - The `tests/` directory includes:
     - `test_methods.py` for solver correctness,
     - `test_parser.py` for input parsing/validation,
     - `test_integration.py` for end-to-end behavior.
   - This mirrors the architecture and suggests the repo is designed around separable units plus a full pipeline test.

10. **Runtime and tooling**
    - The project is a **Python** application, with dependencies declared in `requirements.txt`.
    - It is containerized with a `Dockerfile`, so the intended runtime environment is reproducible and isolated.
    - The README indicates interactive execution inside Docker with a mounted `output` directory for generated artifacts.

11. **Outputs and artifacts**
    - The application produces tangible artifacts rather than serving network requests:
      - saved iteration history,
      - generated graphs,
      - possibly result summaries in files under `output`.
    - That makes this more of a computation/analysis tool than a service application.

12. **What an architecture diagram should show**
    - Place `main.py` at the top as the orchestrator.
    - Show `core/parser.py` feeding into `core/methods.py`.
    - Show `core/methods.py` producing results to both `data/storage.py` and `ui/plotter.py`.
    - Show both storage and plotting writing to the `output` folder.
    - Show `tests/` as a parallel validation layer covering parser, methods, and full integration.

Main entry points: [`core/methods.py`](https://github.com/hoob028/math-solver/blob/main/core/methods.py) (Solvers), [`main.py`](https://github.com/hoob028/math-solver/blob/main/main.py) (Main), [`core/parser.py`](https://github.com/hoob028/math-solver/blob/main/core/parser.py) (Parser), [`data/storage.py`](https://github.com/hoob028/math-solver/blob/main/data/storage.py) (Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_docker["Docker<br/>container"]
end

subgraph group_core["Core"]
  node_parser["Parser<br/>input validation<br/>[parser.py]"]
  node_methods{{"Solvers<br/>numerical core<br/>[methods.py]"}}
end

subgraph group_io["I/O"]
  node_storage[("Storage<br/>persistence<br/>[storage.py]")]
  node_plotter["Plotter<br/>visualization<br/>[plotter.py]"]
  node_output["Output<br/>artifact dir"]
end

subgraph group_verification["Verification"]
  node_test_parser["Parser tests<br/>[test_parser.py]"]
  node_test_methods["Solver tests<br/>[test_methods.py]"]
  node_test_integration["Integration test"]
end

node_docker -->|"run"| node_main
node_main -->|"parse input"| node_parser
node_main -->|"select solver"| node_methods
node_parser -->|"parameters"| node_methods
node_methods -->|"history"| node_storage
node_methods -->|"results"| node_plotter
node_storage -->|"write files"| node_output
node_plotter -->|"save plots"| node_output
node_test_parser -.->|"verify"| node_parser
node_test_methods -.->|"verify"| node_methods
node_test_integration -.->|"exercise"| node_main

click node_main "https://github.com/hoob028/math-solver/blob/main/main.py"
click node_docker "https://github.com/hoob028/math-solver/tree/main/Dockerfile"
click node_parser "https://github.com/hoob028/math-solver/blob/main/core/parser.py"
click node_methods "https://github.com/hoob028/math-solver/blob/main/core/methods.py"
click node_storage "https://github.com/hoob028/math-solver/blob/main/data/storage.py"
click node_plotter "https://github.com/hoob028/math-solver/blob/main/ui/plotter.py"
click node_test_parser "https://github.com/hoob028/math-solver/blob/main/tests/test_parser.py"
click node_test_methods "https://github.com/hoob028/math-solver/blob/main/tests/test_methods.py"
click node_test_integration "https://github.com/hoob028/math-solver/blob/main/tests/test_integration.py"

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_docker toneBlue
class node_parser,node_methods toneAmber
class node_storage,node_plotter,node_output toneMint
class node_test_parser,node_test_methods,node_test_integration toneRose
```

## Components

### Runtime

Entry point and execution environment

- [Main](https://github.com/hoob028/math-solver/blob/main/main.py): entrypoint · CLI entry point that orchestrates parsing, solving, saving, and plotting · `main.py`
- [Docker](https://github.com/hoob028/math-solver/tree/main/Dockerfile): container · Reproducible runtime for interactive execution · `Dockerfile`

### Core

Input parsing and numerical solvers

- [Parser](https://github.com/hoob028/math-solver/blob/main/core/parser.py): input validation · Transforms interactive user input into solver-ready parameters · `core/parser.py`
- [Solvers](https://github.com/hoob028/math-solver/blob/main/core/methods.py): numerical core · Implements bisection, Newton, and secant root-finding algorithms · `core/methods.py`

### I/O

Persistence and visualization

- [Storage](https://github.com/hoob028/math-solver/blob/main/data/storage.py): persistence · Writes iteration history and results to files · `data/storage.py`
- [Plotter](https://github.com/hoob028/math-solver/blob/main/ui/plotter.py): visualization · Generates plots from the function, parameters, and iteration history · `ui/plotter.py`
- **Output**: artifact dir · Generated files and plots produced by the application

### Verification

Tests covering units and end-to-end flow

- [Parser tests](https://github.com/hoob028/math-solver/blob/main/tests/test_parser.py): test · Validates parsing and input handling · `tests/test_parser.py`
- [Solver tests](https://github.com/hoob028/math-solver/blob/main/tests/test_methods.py): test · Checks numerical method correctness · `tests/test_methods.py`
- [Integration test](https://github.com/hoob028/math-solver/blob/main/tests/test_integration.py): test · Exercises the full CLI-to-artifacts pipeline · `tests/test_integration.py`

## Connections

- Docker → Main: run · Containerized execution starts the CLI
- Main → Parser: parse input · Entry point validates and converts user input
- Main → Solvers: select solver · Main dispatches to the chosen numerical method
- Parser → Solvers: parameters · Parsed function and numeric arguments feed the solver layer
- Solvers → Storage: history · Solvers emit iteration traces for persistence
- Solvers → Plotter: results · Solvers provide data for plotting
- Storage → Output: write files · Persistence layer writes artifacts to the output directory
- Plotter → Output: save plots · Visualization layer writes generated graphs to the output directory
- Parser tests → Parser: verify · Parser unit tests cover validation and transformation behavior
- Solver tests → Solvers: verify · Solver tests cover the root-finding algorithms
- Integration test → Main: exercise · Integration tests validate the end-to-end application flow
