# cagelmi/mccabe-thiele-method architecture

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

- Interactive diagram: https://gitdiagram.com/cagelmi/mccabe-thiele-method
- Repository: https://github.com/cagelmi/mccabe-thiele-method

## Overview

##### Project Type and Purpose
- This is a single‐window desktop GUI application (Python/Tkinter) for performing and visualizing McCabe-Thiele graphical method calculations.

##### File Structure Analysis
- Top level:
- mccabe_thiele_gui.py – contains all GUI, calculation logic, plotting, and I/O
- requirements.txt – lists Python dependencies (Tkinter, NumPy, Matplotlib)
- images/ – static example screenshots
- README.md, LICENSE, .gitignore

- No separate src/, lib/, or test/ directories – code is monolithic but conceptually splits into these components:
- GUI layer (Tkinter widgets, event handlers)
- Calculation engine (equilibrium, q-line, ROL/SOL, stepping algorithm)
- Plotting module (Matplotlib integration, interactive tooltips)
- Persistence module (save/load JSON parameters, export plot image)
- External libraries (NumPy, Matplotlib, JSON, OS)

##### README Insights
- Confirms use of Tkinter, NumPy, Matplotlib.
- Explains input validation, calculation formulas, plot elements, interactive features, and export functionality.

a. Main Components
1. GUI Layer
– Input Form (entries for zf, q, xd, xb, R, α)
– Control Buttons (Calculate, Save Params, Load Params, Reset, Export Plot)
– Plot Canvas + Matplotlib Toolbar
2. Calculation Engine
– Input Validator
– Equilibrium Curve Calculator
– q-Line / ROL / SOL Calculator
– Stage-Stepping Algorithm
– Intersection & Feasibility Checker
3. Plotting Module
– Matplotlib Figure & Axes
– Plot Element Renderers (curves, lines, steps, labels)
– Interactive Hover Tooltips
4. Persistence Module
– Parameter JSON Reader/Writer
– Image Exporter (PNG/JPG/PDF) with annotation
5. External Libraries & Runtime
– Python Interpreter & Standard Library (json, os)
– Tkinter
– NumPy
– Matplotlib
6. File System & Resources
– images/ (static screenshots)
– User-generated JSON files & exported images

b. Relationships & Data Flow
- User interacts with GUI → event triggers Calculation Engine → produces numeric data (x/y arrays, plate counts, intersection point) → passed to Plotting Module → plot rendered in GUI.
- Save/Load buttons in GUI ↔ Persistence Module ↔ file system (JSON).
- Export Plot uses Plotting Module output → Persistence Module → writes image file.
- All modules rely on External Libraries.

c. Architectural Patterns & Principles
- Model–View–Controller (MVC) style:
- Model = Calculation Engine + Persistence Module
- View = Tkinter GUI + Matplotlib Canvas
- Controller = event handlers/glue code in main script
- Separation of concerns: Input validation, computation logic, plotting logic, and I/O logic are distinct conceptual layers.

d. Key Technologies
- Python 3.x
- Tkinter (GUI)
- NumPy (numerical calculations)
- Matplotlib (plotting & interactivity)
- JSON & OS modules for file I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GUI Layer"
        GUI["GUI Layer\n(Tkinter Widgets & Event Handlers)"]:::gui
    end

    subgraph "Core Logic Modules"
        CE["Calculation Engine"]:::core
        PM["Plotting Module"]:::core
        PSM["Persistence Module"]:::core
    end

    subgraph "External Libraries & Runtime"
        LIB["Python Interpreter & Libs\n(json, os, NumPy, Matplotlib, Tkinter)"]:::ext
    end

    FS["File System\n(JSON & Image files, images/)"]:::fs

    subgraph "Project Artifacts"
        DOC["README.md"]:::ext
        LIC["LICENSE"]:::ext
        GIT[".gitignore"]:::ext
    end

    subgraph "Legend"
        G1["Green = GUI Layer"]
        B1["Blue = Core Logic Modules"]
        G2["Gray = External Libraries/Runtime & Docs"]
        Y1["Yellow = File System"]
    end

    GUI -->|"user inputs"| CE
    CE -->|"data arrays"| PM
    PM -->|"render plot"| GUI
    GUI <-->|"save/load params"| PSM
    PM -->|"export_plot()"| PSM

    CE -->|"uses"| LIB
    PM -->|"uses"| LIB
    PSM -->|"uses"| LIB

    PSM -->|"read/write files"| FS

    click GUI "https://github.com/cagelmi/mccabe-thiele-method/blob/main/mccabe_thiele_gui.py"
    click CE "https://github.com/cagelmi/mccabe-thiele-method/blob/main/mccabe_thiele_gui.py"
    click PM "https://github.com/cagelmi/mccabe-thiele-method/blob/main/mccabe_thiele_gui.py"
    click PSM "https://github.com/cagelmi/mccabe-thiele-method/blob/main/mccabe_thiele_gui.py"
    click FS "https://github.com/cagelmi/mccabe-thiele-method/tree/main/images/"
    click LIB "https://github.com/cagelmi/mccabe-thiele-method/blob/main/requirements.txt"
    click DOC "https://github.com/cagelmi/mccabe-thiele-method/blob/main/README.md"
    click LIC "https://github.com/cagelmi/mccabe-thiele-method/tree/main/LICENSE"
    click GIT "https://github.com/cagelmi/mccabe-thiele-method/blob/main/.gitignore"

    classDef gui fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef core fill:#aaaaff,stroke:#333,stroke-width:1px
    classDef ext fill:#dddddd,stroke:#333,stroke-width:1px
    classDef fs fill:#ffffaa,stroke:#333,stroke-width:1px
    classDef gui,core,ext,fs G1,B1,G2,Y1
```
