# loki59484/kistwrap architecture

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

- Interactive diagram: https://gitdiagram.com/loki59484/kistwrap
- Repository: https://github.com/loki59484/kistwrap

## Overview

Kistwrap automates the KiSThelP chemistry engine through a Python CLI or interactive TUI. The workflow accepts a single calculation or a batch job, checks for cached work, invokes the Java engine asynchronously, and presents results as CSV-derived terminal plots. The Java sources also contain the underlying statistical-mechanics and reaction-kinetics domain model. The documented rate-constant and equilibrium wrapper pipelines remain roadmap items, so they are not represented as implemented Python stages. Relationships follow README statements and the supplied source index; Java internals were only partly sampled.

Main entry points: [`src/kistwrap/core.py`](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py) (Engine worker), [`src/kistwrap/tui.py`](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/tui.py) (Terminal dashboard), [`kisthelp_engine/src/CLIinterface.java`](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/CLIinterface.java) (Java CLI), [`kisthelp_engine/src/ChemicalSystem.java`](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/ChemicalSystem.java) (Molecular properties)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI router<br/>[cli.py]"]
  node_tui["Terminal dashboard<br/>[tui.py]"]
end

subgraph group_automation["Automation"]
  node_batch["Job-file batch<br/>[core.py]"]
  node_cache["Result cache<br/>[core.py]"]
  node_worker["Engine worker<br/>[core.py]"]
end

subgraph group_engine["Chemistry engine"]
  node_java_cli["Java CLI<br/>[CLIinterface.java]"]
  node_chem_system["Molecular properties"]
  node_inert_system["Statistical system"]
  node_reaction["Reaction kinetics"]
  node_bimolecular["Bimolecular reactions"]
  node_file_read["Input detection"]
  node_session["Session state<br/>[Session.java]"]
end

subgraph group_results["Results"]
  node_csv["CSV results<br/>[core.py]"]
  node_plots["Terminal plots<br/>[tui.py]"]
end

node_user(("User"))

node_user -->|"runs command"| node_cli
node_user -->|"opens dashboard"| node_tui
node_cli -->|"routes TUI"| node_tui
node_cli -->|"starts calculation"| node_worker
node_tui -->|"submits work"| node_worker
node_worker -.->|"parses jobs"| node_batch
node_worker -->|"checks prior results"| node_cache
node_worker -->|"launches subprocess"| node_java_cli
node_java_cli -.->|"runs calculation"| node_chem_system
node_chem_system -.->|"reads chemistry input"| node_file_read
node_chem_system -.->|"uses statistical model"| node_inert_system
node_java_cli -.->|"dispatches reaction work"| node_reaction
node_java_cli -.->|"dispatches reaction work"| node_bimolecular
node_worker -->|"streams output"| node_csv
node_tui -->|"parses results"| node_csv
node_tui -->|"renders plots"| node_plots
node_session -.->|"stores calculation state"| node_chem_system

click node_cli "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/cli.py"
click node_tui "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/tui.py"
click node_batch "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py"
click node_cache "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py"
click node_worker "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py"
click node_java_cli "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/CLIinterface.java"
click node_chem_system "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/ChemicalSystem.java"
click node_inert_system "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/InertStatisticalSystem.java"
click node_reaction "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/UnimolecularReaction.java"
click node_bimolecular "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/BiMolecularReaction.java"
click node_file_read "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/kisthep/file/ActionOnFileRead.java"
click node_session "https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/Session.java"
click node_csv "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py"
click node_plots "https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/tui.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_cli,node_tui,node_user toneBlue
class node_batch,node_cache,node_worker toneAmber
class node_java_cli,node_chem_system,node_inert_system,node_reaction,node_bimolecular,node_file_read,node_session toneMint
class node_csv,node_plots toneRose
```

## Components

### User interfaces

- [CLI router](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/cli.py): `src/kistwrap/cli.py`
- [Terminal dashboard](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/tui.py): `src/kistwrap/tui.py`

### Automation

- [Job-file batch](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py): `src/kistwrap/core.py`
- [Result cache](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py): `src/kistwrap/core.py`
- [Engine worker](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py): `src/kistwrap/core.py`

### Chemistry engine

- [Java CLI](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/CLIinterface.java): `kisthelp_engine/src/CLIinterface.java`
- [Molecular properties](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/ChemicalSystem.java): `kisthelp_engine/src/ChemicalSystem.java`
- [Statistical system](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/InertStatisticalSystem.java): `kisthelp_engine/src/InertStatisticalSystem.java`
- [Reaction kinetics](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/UnimolecularReaction.java): `kisthelp_engine/src/UnimolecularReaction.java`
- [Bimolecular reactions](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/BiMolecularReaction.java): `kisthelp_engine/src/BiMolecularReaction.java`
- [Input detection](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/kisthep/file/ActionOnFileRead.java): `kisthelp_engine/src/kisthep/file/ActionOnFileRead.java`
- [Session state](https://github.com/loki59484/kistwrap/blob/main/kisthelp_engine/src/Session.java): `kisthelp_engine/src/Session.java`

### Results

- [CSV results](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/core.py): `src/kistwrap/core.py`
- [Terminal plots](https://github.com/loki59484/kistwrap/blob/main/src/kistwrap/tui.py): `src/kistwrap/tui.py`

### Other components

- **User**

## Connections

- User → CLI router: runs command (evidence: `README.md`)
- User → Terminal dashboard: opens dashboard (evidence: `README.md`)
- CLI router → Terminal dashboard: routes TUI (evidence: `src/kistwrap/cli.py`)
- CLI router → Engine worker: starts calculation (evidence: `README.md`)
- Terminal dashboard → Engine worker: submits work (evidence: `src/kistwrap/tui.py`)
- Engine worker → Job-file batch: parses jobs (evidence: `src/kistwrap/core.py`)
- Engine worker → Result cache: checks prior results (evidence: `README.md`)
- Engine worker → Java CLI: launches subprocess (evidence: `README.md`)
- Java CLI → Molecular properties: runs calculation
- Molecular properties → Input detection: reads chemistry input (evidence: `kisthelp_engine/src/ChemicalSystem.java`)
- Molecular properties → Statistical system: uses statistical model (evidence: `kisthelp_engine/src/InertStatisticalSystem.java`)
- Java CLI → Reaction kinetics: dispatches reaction work
- Java CLI → Bimolecular reactions: dispatches reaction work
- Engine worker → CSV results: streams output (evidence: `README.md`)
- Terminal dashboard → CSV results: parses results (evidence: `README.md`)
- Terminal dashboard → Terminal plots: renders plots (evidence: `README.md`)
- Session state → Molecular properties: stores calculation state (evidence: `kisthelp_engine/src/ChemicalSystem.java`)