# kastakin/pyes architecture

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

- Interactive diagram: https://gitdiagram.com/kastakin/pyes
- Repository: https://github.com/kastakin/pyes

## Overview

##### Project Type and Purpose
- PyES is an open-source desktop application, designed to compute chemical equilibria and simulate titration curves even for complex systems with precipitable species.
- The README highlights its installation on multiple operating systems and references a user manual for the GUI interface. It is clearly aimed at researchers in chemistry.

##### Key Components and Their Roles
- User Interface Layer:
- Located in src/main/python/pyes/ui and its subdirectories (including dialogs, widgets, and windows).
- Contains all .ui files (e.g., PyES_main.ui, PyES_dataExport.ui etc.) and related Python code that drives the front-end.
- Application Core / Business Logic:
- Found in src/main/python/pyes/main.py and supporting modules (commands, optimizers, workers, viewmodels). This is the engine that processes user actions, performs calculations and coordinates between the UI and the computational backend.
- Build and Configuration:
- Under src/build/settings and various JSON files, as well as scripts that include compile_ui.sh, icon_creator.py, and profile.sh.
- Resources and Assets:
- Testing and Benchmarking:
- A dedicated tests directory (with test_data and test files) ensuring that both simulation and UI components are covered.
- Documentation:
- The docs directory holds a complete user manual with images and source files, which is essential for user guidance.
- Auxiliary Scripts & Pre-commit Config:
- CI/CD and release workflows indicated by .github and pre-commit configuration ensure consistent quality and deployment processes.

##### Relationships & Interactions
- Build & Configuration components provide necessary settings for the core and UI components depending on the target OS and platform-specific requirements (depicted as configuration inputs affecting both the UI and backend).
- Testing and Benchmarking functions should be connected to the Application Core (and possibly the UI) to highlight automated testing flows.
- Documentation is external but essential to link with the overall user experience.

##### Architectural Patterns & Design Principles
- A modular design is visible. There is a clear separation of concerns: UI is isolated from business logic, and resources are externalized.
- The separation indicates an architectural pattern similar to MVC (Model-View-Controller) or MVVM (Model-View-ViewModel) where business logic, UI and data models are loosely coupled.
- The use of build scripts and cross-platform configuration files emphasizes maintainability and scalability, ensuring that extensions (or plug-ins) can be added as needed.

##### Detailed Component Mapping
- A high-level node representing the “PyES Application” at the center.
- Create sub-nodes for:
- “User Interface” (linking to dialogs, widgets, and main windows).
- “Core Computation Engine” (which includes commands, optimizers, and workers).
- “Configuration/Build” (showing platform specific configs—base, linux.json, mac.json).
- “Testing & Benchmarking” (modules under tests & benchmark directories).
- “Documentation & Support” (docs and user manual).
- The UI sends actions/commands to the Core.
- The Core accesses resources/configuration settings.
- Testing modules continuously verify functionality across UI and Core.
- Benchmarking scripts feed performance metrics back to the Core.

##### Final Recommendations
- Maintain clear and detailed labels for each component.
- Elements, even down to utility scripts if they play a key role in configuration or maintenance (these can be noted as auxiliary components).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["User Interface"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Core["Application Core"]:::core
        Commands["Commands Module"]:::core
        Optimizers["Optimizers Module"]:::core
        ViewModels["View Models"]:::core
        Workers["Workers Module"]:::core
        Windows["Windows Module"]:::core
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        BuildSettings["Build Settings"]:::config
        compileUI["Build Script: compile_ui.sh"]:::config
        iconCreator["Build Script: icon_creator.py"]:::config
        profileScript["Build Script: profile.sh"]:::config
    end

    %% Resources & Assets
    subgraph "Resources & Assets"
        Resources["Resource Files"]:::resource
        Icons["Icons"]:::resource
    end

    %% Support Components
    subgraph "Support"
        Testing["Testing"]:::support
        Benchmarking["Benchmarking"]:::support
        Documentation["Documentation & User Manual"]:::support
        PreCommit["Pre-commit Config"]:::support
        CICD["CI/CD Workflows"]:::support
        AuxScripts["Auxiliary Scripts"]:::support
    end

    %% Relationships & Interactions
    UI -->|"triggers"| Core

    Core -->|"executes"| Commands
    Core -->|"executes"| Optimizers
    Core -->|"executes"| ViewModels
    Core -->|"executes"| Workers
    Core -->|"integrates"| Windows

    BuildSettings -->|"configures"| UI
    BuildSettings -->|"configures"| Core

    compileUI -->|"assists"| UI
    compileUI -->|"assists"| Core

    iconCreator -->|"assists"| UI
    iconCreator -->|"assists"| Core

    profileScript -->|"assists"| UI
    profileScript -->|"assists"| Core

    Resources -->|"supplies"| UI
    Resources -->|"supplies"| Core

    Icons -->|"suppliesVisualsTo"| UI

    UI -->|"verifiedBy"| Testing
    Core -->|"verifiedBy"| Testing

    UI -->|"monitoredBy"| Benchmarking
    Core -->|"monitoredBy"| Benchmarking

    Documentation -->|"guides"| UI

    PreCommit -->|"supports"| BuildSettings
    CICD -->|"supports"| BuildSettings
    AuxScripts -->|"supports"| compileUI

    %% Click Events
    click UI "https://github.com/kastakin/pyes/tree/master/src/main/python/pyes/ui"
    click Core "https://github.com/kastakin/pyes/blob/master/src/main/python/pyes/main.py"
    click Commands "https://github.com/kastakin/pyes/tree/master/src/main/python/pyes/commands"
    click Optimizers "https://github.com/kastakin/pyes/tree/master/src/main/python/pyes/optimizers"
    click ViewModels "https://github.com/kastakin/pyes/tree/master/src/main/python/pyes/viewmodels"
    click Windows "https://github.com/kastakin/pyes/tree/master/src/main/python/pyes/windows"
    click Workers "https://github.com/kastakin/pyes/blob/master/src/main/python/pyes/workers.py"
    click BuildSettings "https://github.com/kastakin/pyes/tree/master/src/build/settings"
    click compileUI "https://github.com/kastakin/pyes/blob/master/scripts/compile_ui.sh"
    click iconCreator "https://github.com/kastakin/pyes/blob/master/scripts/icon_creator.py"
    click profileScript "https://github.com/kastakin/pyes/blob/master/scripts/profile.sh"
    click Resources "https://github.com/kastakin/pyes/tree/master/src/main/resources"
    click Icons "https://github.com/kastakin/pyes/tree/master/src/main/icons"
    click Testing "https://github.com/kastakin/pyes/tree/master/tests"
    click Benchmarking "https://github.com/kastakin/pyes/tree/master/benchmark"
    click Documentation "https://github.com/kastakin/pyes/tree/master/docs/user_manual"
    click PreCommit "https://github.com/kastakin/pyes/blob/master/.pre-commit-config.yaml"
    click CICD "https://github.com/kastakin/pyes/tree/master/.github/workflows"
    click AuxScripts "https://github.com/kastakin/pyes/tree/master/scripts"

    %% Styles
    classDef ui fill:#bbe1fa,stroke:#000,stroke-width:1px;
    classDef core fill:#b8e994,stroke:#000,stroke-width:1px;
    classDef config fill:#f6e58d,stroke:#000,stroke-width:1px;
    classDef resource fill:#e056fd,stroke:#000,stroke-width:1px;
    classDef support fill:#ff9ff3,stroke:#000,stroke-width:1px;
```
