# banchaoruan/molecular-research-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/banchaoruan/molecular-research-toolkit
- Repository: https://github.com/banchaoruan/molecular-research-toolkit

## Overview

The Molecular Research Toolkit supports either individual tasks or a traceable paper-to-computation workflow: prepare molecule images, identify and review structures, organize master-table and literature evidence, export selected molecules, and generate Barkla results. The graph preserves the README’s major capabilities and the sampled internal layers. Several subsystems, especially literature extraction, are represented at their documented directory level because implementation excerpts were not provided; documented links use the README as evidence.

Main entry points: [`skills/molecular-research-toolkit/scripts/master_schema.mjs`](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/master_schema.mjs) (Master table), [`skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py`](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py) (SMILES workflow), [`tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py`](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py) (Failed-job recovery), [`skills/modules/molecule-image-prep/scripts/prepare_images_core.py`](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/molecule-image-prep/scripts/prepare_images_core.py) (Image preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Image preparation"]
  node_imageprep["Image preparation"]
  node_cropreview["Crop review bundle<br/>[build_review.py]"]
  node_singleimages["Molecule images"]
end

subgraph group_identity["Structure identification"]
  node_smilesworkflow["SMILES workflow"]
  node_recognition["Structure prediction"]
  node_candidatecore["Candidate records<br/>[smiles_core.py]"]
  node_structurereview["Structure review<br/>[render_smiles.py]"]
  node_molfallback["ChemDraw fallback"]
  node_reviewedstructures["Reviewed structures"]
end

subgraph group_research["Research tables"]
  node_mastertable["Master table<br/>[master_schema.mjs]"]
  node_tableops["Table operations<br/>[data_core.mjs]"]
  node_smiexport["SMI export<br/>[build_smi.mjs]"]
  node_literature["Literature extraction"]
  node_solventevidence["Solvent evidence"]
end

subgraph group_compute["Barkla computation"]
  node_barkla["Barkla preparation<br/>[make_com.py]"]
  node_slurm["Slurm jobs<br/>[make_slurm.py]"]
  node_recovery["Failed-job recovery<br/>[recover_no_g298.py]"]
  node_extract["G298 extraction"]
  node_g298["G298 results"]
end

node_paper["Paper figures"]
node_user(("Researcher"))
node_hpc{{"Barkla HPC"}}

node_paper -->|"provides figures"| node_imageprep
node_imageprep -->|"builds review"| node_cropreview
node_imageprep -->|"produces images"| node_singleimages
node_singleimages -->|"supplies images"| node_smilesworkflow
node_smilesworkflow -->|"requests predictions"| node_recognition
node_smilesworkflow -->|"uses contracts"| node_candidatecore
node_smilesworkflow -->|"uses fallback"| node_molfallback
node_recognition -->|"records candidates"| node_candidatecore
node_user -->|"reviews candidates"| node_structurereview
node_structurereview -->|"produces reviewed data"| node_reviewedstructures
node_molfallback -->|"prepares MOL inputs"| node_reviewedstructures
node_reviewedstructures -->|"fills structure pairs"| node_mastertable
node_user -->|"provides workbook"| node_mastertable
node_mastertable -->|"reads and updates"| node_tableops
node_mastertable -->|"supplies master"| node_literature
node_literature -->|"records evidence"| node_solventevidence
node_user -->|"reviews evidence"| node_solventevidence
node_mastertable -->|"selects molecules"| node_smiexport
node_solventevidence -->|"provides solvent choices"| node_smiexport
node_smiexport -->|"supplies reviewed SMI"| node_barkla
node_barkla -->|"prepares job scripts"| node_slurm
node_slurm -->|"runs Gaussian jobs"| node_hpc
node_hpc -->|"provides outputs"| node_extract
node_extract -->|"writes results"| node_g298
node_recovery -->|"prepares retries"| node_barkla
node_recovery -->|"prepares retries"| node_slurm
node_recovery -->|"uses extraction logic"| node_extract

click node_imageprep "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/molecule-image-prep/scripts/prepare_images_core.py"
click node_cropreview "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/molecule-image-prep/scripts/build_review.py"
click node_smilesworkflow "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py"
click node_recognition "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/structure_predict.py"
click node_candidatecore "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/smiles_core.py"
click node_structurereview "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/render_smiles.py"
click node_molfallback "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/chemdraw_fallback.py"
click node_mastertable "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/master_schema.mjs"
click node_tableops "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/data_core.mjs"
click node_smiexport "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/build_smi.mjs"
click node_literature "https://github.com/banchaoruan/molecular-research-toolkit/tree/main/skills/modules/literature-solvent-extraction"
click node_barkla "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/make_com.py"
click node_slurm "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/make_slurm.py"
click node_recovery "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py"
click node_extract "https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/extract_G298_batch.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_imageprep,node_cropreview,node_singleimages toneBlue
class node_smilesworkflow,node_recognition,node_candidatecore,node_structurereview,node_molfallback,node_reviewedstructures toneAmber
class node_mastertable,node_tableops,node_smiexport,node_literature,node_solventevidence toneMint
class node_barkla,node_slurm,node_recovery,node_extract,node_g298 toneRose
class node_paper,node_user,node_hpc toneIndigo
```

## Components

### Image preparation

- [Image preparation](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/molecule-image-prep/scripts/prepare_images_core.py): `skills/modules/molecule-image-prep/scripts/prepare_images_core.py`
- [Crop review bundle](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/molecule-image-prep/scripts/build_review.py): `skills/modules/molecule-image-prep/scripts/build_review.py`
- **Molecule images**

### Structure identification

- [SMILES workflow](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py): `skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py`
- [Structure prediction](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/structure_predict.py): `skills/modules/image-to-smiles/scripts/structure_predict.py`
- [Candidate records](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/smiles_core.py): `skills/modules/image-to-smiles/scripts/smiles_core.py`
- [Structure review](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/render_smiles.py): `skills/modules/image-to-smiles/scripts/render_smiles.py`
- [ChemDraw fallback](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/modules/image-to-smiles/scripts/chemdraw_fallback.py): `skills/modules/image-to-smiles/scripts/chemdraw_fallback.py`
- **Reviewed structures**

### Research tables

- [Master table](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/master_schema.mjs): `skills/molecular-research-toolkit/scripts/master_schema.mjs`
- [Table operations](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/data_core.mjs): `skills/molecular-research-toolkit/scripts/data_core.mjs`
- [SMI export](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/skills/molecular-research-toolkit/scripts/build_smi.mjs): `skills/molecular-research-toolkit/scripts/build_smi.mjs`
- [Literature extraction](https://github.com/banchaoruan/molecular-research-toolkit/tree/main/skills/modules/literature-solvent-extraction): `skills/modules/literature-solvent-extraction`
- **Solvent evidence**

### Barkla computation

- [Barkla preparation](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/make_com.py): `tools/barkla_redox/barkla_redox/scripts/make_com.py`
- [Slurm jobs](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/make_slurm.py): `tools/barkla_redox/barkla_redox/scripts/make_slurm.py`
- [Failed-job recovery](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py): `tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py`
- [G298 extraction](https://github.com/banchaoruan/molecular-research-toolkit/blob/main/tools/barkla_redox/barkla_redox/scripts/extract_G298_batch.py): `tools/barkla_redox/barkla_redox/scripts/extract_G298_batch.py`
- **G298 results**

### Other components

- **Paper figures**
- **Researcher**
- **Barkla HPC**

## Connections

- Paper figures → Image preparation: provides figures (evidence: `README.md`)
- Image preparation → Crop review bundle: builds review (evidence: `README.md`)
- Image preparation → Molecule images: produces images (evidence: `README.md`)
- Molecule images → SMILES workflow: supplies images (evidence: `README.md`)
- SMILES workflow → Structure prediction: requests predictions (evidence: `skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py`)
- SMILES workflow → Candidate records: uses contracts (evidence: `skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py`)
- SMILES workflow → ChemDraw fallback: uses fallback (evidence: `skills/modules/image-to-smiles/scripts/run_source_folder_to_smiles.py`)
- Structure prediction → Candidate records: records candidates (evidence: `skills/modules/image-to-smiles/scripts/structure_predict.py`)
- Researcher → Structure review: reviews candidates (evidence: `README.md`)
- Structure review → Reviewed structures: produces reviewed data (evidence: `README.md`)
- ChemDraw fallback → Reviewed structures: prepares MOL inputs (evidence: `README.md`)
- Reviewed structures → Master table: fills structure pairs (evidence: `README.md`)
- Researcher → Master table: provides workbook (evidence: `README.md`)
- Master table → Table operations: reads and updates (evidence: `skills/molecular-research-toolkit/scripts/master_schema.mjs`)
- Master table → Literature extraction: supplies master (evidence: `README.md`)
- Literature extraction → Solvent evidence: records evidence (evidence: `README.md`)
- Researcher → Solvent evidence: reviews evidence (evidence: `README.md`)
- Master table → SMI export: selects molecules (evidence: `README.md`)
- Solvent evidence → SMI export: provides solvent choices (evidence: `README.md`)
- SMI export → Barkla preparation: supplies reviewed SMI (evidence: `README.md`)
- Barkla preparation → Slurm jobs: prepares job scripts (evidence: `tools/barkla_redox/barkla_redox/scripts/make_slurm.py`)
- Slurm jobs → Barkla HPC: runs Gaussian jobs (evidence: `README.md`)
- Barkla HPC → G298 extraction: provides outputs (evidence: `README.md`)
- G298 extraction → G298 results: writes results (evidence: `README.md`)
- Failed-job recovery → Barkla preparation: prepares retries (evidence: `tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py`)
- Failed-job recovery → Slurm jobs: prepares retries (evidence: `tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py`)
- Failed-job recovery → G298 extraction: uses extraction logic (evidence: `tools/barkla_redox/barkla_redox/scripts/recover_no_g298.py`)
