# uttkarsh779/knf-molecular-descriptors architecture

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

- Interactive diagram: https://gitdiagram.com/uttkarsh779/knf-molecular-descriptors
- Repository: https://github.com/uttkarsh779/knf-molecular-descriptors

## Overview

KNF Studio is a desktop application that accepts molecular structure files and presents computed KNF descriptors and interaction visualizations. The main workflow runs from the user’s run-management interface through Electron and the Python API, then through geometry optimization, NCI analysis, descriptor and fingerprint generation, and persisted results to the Results and Explorer views. The README documents the scientific stages; source excerpts confirm selected internal calls. Some UI-to-API and backend orchestration details are not shown, so those links are marked unverified.

Main entry points: [`backend/NCIForge/knf_core/pipeline.py`](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/pipeline.py) (KNF pipeline), [`backend/NCIForge/knf_core/nci_torch/pipeline.py`](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/pipeline.py) (NCI pipeline), [`frontend/src/pages/RunManager.tsx`](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/RunManager.tsx) (Run manager), [`backend/NCIForge/server.py`](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/server.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_runmanager["Run manager<br/>[RunManager.tsx]"]
  node_electron["Electron shell<br/>[main.ts]"]
  node_bridge["Backend launcher<br/>[backend.ts]"]
  node_results["Results table<br/>[Results.tsx]"]
  node_explorer["Molecule explorer<br/>[Explorer.tsx]"]
  node_analysis["Analysis view<br/>[Analysis.tsx]"]
end

subgraph group_service["Run service"]
  node_api["Python API<br/>[server.py]"]
end

subgraph group_science["Scientific computation"]
  node_orchestrator["KNF pipeline<br/>[pipeline.py]"]
  node_geometry["Geometry handling<br/>[geometry.py]"]
  node_xtb["xTB optimizer<br/>[xtb.py]"]
  node_converter["Structure conversion<br/>[converter.py]"]
  node_knf["KNF descriptors<br/>[knf_vector.py]"]
  node_autoconfig["Tool configuration<br/>[autoconfig.py]"]
  node_fingerprint["KUID fingerprint<br/>[kuid.py]"]
  node_quadrants["Quadrant classification<br/>[main.py]"]
end

subgraph group_nci["NCI analysis"]
  node_nci_pipeline["NCI pipeline<br/>[pipeline.py]"]
  node_molden["Molden parser<br/>[molden.py]"]
  node_grid["Density grid<br/>[grid.py]"]
  node_engine["NCI engine<br/>[engine.py]"]
  node_router["Device router<br/>[router.py]"]
end

subgraph group_persistence["Results and storage"]
  node_runsdb[("Run database<br/>[database.py]")]
end

node_user(("KNF Studio user"))

node_user -->|"starts runs"| node_runmanager
node_runmanager -.->|"submits run"| node_electron
node_electron -->|"starts backend"| node_bridge
node_runmanager -.->|"requests runs"| node_api
node_api -.->|"dispatches computation"| node_orchestrator
node_orchestrator -->|"prepares geometry"| node_geometry
node_orchestrator -->|"optimizes geometry"| node_xtb
node_orchestrator -->|"converts structures"| node_converter
node_orchestrator -->|"runs NCI"| node_nci_pipeline
node_nci_pipeline -->|"reads wavefunction"| node_molden
node_nci_pipeline -->|"builds grid"| node_grid
node_nci_pipeline -->|"computes fields"| node_engine
node_orchestrator -->|"computes descriptors"| node_knf
node_orchestrator -.->|"routes device"| node_router
node_orchestrator -.->|"configures tools"| node_autoconfig
node_orchestrator -.->|"creates fingerprint"| node_fingerprint
node_orchestrator -.->|"classifies results"| node_quadrants
node_api -->|"reads and writes"| node_runsdb
node_runsdb -.->|"serves run results"| node_results
node_results -->|"shows descriptors"| node_user
node_explorer -->|"plots molecules"| node_user
node_analysis -.->|"presents analysis"| node_user

click node_runmanager "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/RunManager.tsx"
click node_electron "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/electron/main.ts"
click node_bridge "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/electron/backend.ts"
click node_results "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/Results.tsx"
click node_explorer "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/Explorer.tsx"
click node_analysis "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/Analysis.tsx"
click node_api "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/server.py"
click node_runsdb "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/database.py"
click node_orchestrator "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/pipeline.py"
click node_geometry "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/geometry.py"
click node_xtb "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/xtb.py"
click node_converter "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/converter.py"
click node_nci_pipeline "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/pipeline.py"
click node_molden "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/molden.py"
click node_grid "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/grid.py"
click node_engine "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/engine.py"
click node_router "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/router.py"
click node_knf "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/knf_vector.py"
click node_autoconfig "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/autoconfig.py"
click node_fingerprint "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/kuid.py"
click node_quadrants "https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/main.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_runmanager,node_electron,node_bridge,node_results,node_explorer,node_analysis,node_user toneBlue
class node_api toneAmber
class node_orchestrator,node_geometry,node_xtb,node_converter,node_knf,node_autoconfig,node_fingerprint,node_quadrants toneMint
class node_nci_pipeline,node_molden,node_grid,node_engine,node_router toneRose
class node_runsdb toneIndigo
```

## Components

### Desktop interface

- [Run manager](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/RunManager.tsx): `frontend/src/pages/RunManager.tsx`
- [Electron shell](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/electron/main.ts): `frontend/electron/main.ts`
- [Backend launcher](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/electron/backend.ts): `frontend/electron/backend.ts`
- [Results table](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/Results.tsx): `frontend/src/pages/Results.tsx`
- [Molecule explorer](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/Explorer.tsx): `frontend/src/pages/Explorer.tsx`
- [Analysis view](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/frontend/src/pages/Analysis.tsx): `frontend/src/pages/Analysis.tsx`

### Run service

- [Python API](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/server.py): `backend/NCIForge/server.py`

### Scientific computation

- [KNF pipeline](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/pipeline.py): `backend/NCIForge/knf_core/pipeline.py`
- [Geometry handling](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/geometry.py): `backend/NCIForge/knf_core/geometry.py`
- [xTB optimizer](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/xtb.py): `backend/NCIForge/knf_core/xtb.py`
- [Structure conversion](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/converter.py): `backend/NCIForge/knf_core/converter.py`
- [KNF descriptors](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/knf_vector.py): `backend/NCIForge/knf_core/knf_vector.py`
- [Tool configuration](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/autoconfig.py): `backend/NCIForge/knf_core/autoconfig.py`
- [KUID fingerprint](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/kuid.py): `backend/NCIForge/knf_core/kuid.py`
- [Quadrant classification](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/main.py): `backend/NCIForge/knf_core/main.py`

### NCI analysis

- [NCI pipeline](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/pipeline.py): `backend/NCIForge/knf_core/nci_torch/pipeline.py`
- [Molden parser](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/molden.py): `backend/NCIForge/knf_core/nci_torch/molden.py`
- [Density grid](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/grid.py): `backend/NCIForge/knf_core/nci_torch/grid.py`
- [NCI engine](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/engine.py): `backend/NCIForge/knf_core/nci_torch/engine.py`
- [Device router](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/knf_core/nci_torch/router.py): `backend/NCIForge/knf_core/nci_torch/router.py`

### Results and storage

- [Run database](https://github.com/uttkarsh779/knf-molecular-descriptors/blob/main/backend/NCIForge/database.py): `backend/NCIForge/database.py`

### Other components

- **KNF Studio user**

## Connections

- KNF Studio user → Run manager: starts runs (evidence: `README.md`)
- Run manager → Electron shell: submits run
- Electron shell → Backend launcher: starts backend (evidence: `frontend/electron/main.ts`)
- Run manager → Python API: requests runs
- Python API → KNF pipeline: dispatches computation
- KNF pipeline → Geometry handling: prepares geometry (evidence: `backend/NCIForge/knf_core/pipeline.py`)
- KNF pipeline → xTB optimizer: optimizes geometry (evidence: `backend/NCIForge/knf_core/pipeline.py`)
- KNF pipeline → Structure conversion: converts structures (evidence: `backend/NCIForge/knf_core/pipeline.py`)
- KNF pipeline → NCI pipeline: runs NCI (evidence: `backend/NCIForge/knf_core/pipeline.py`)
- NCI pipeline → Molden parser: reads wavefunction (evidence: `backend/NCIForge/knf_core/nci_torch/pipeline.py`)
- NCI pipeline → Density grid: builds grid (evidence: `backend/NCIForge/knf_core/nci_torch/pipeline.py`)
- NCI pipeline → NCI engine: computes fields (evidence: `backend/NCIForge/knf_core/nci_torch/pipeline.py`)
- KNF pipeline → KNF descriptors: computes descriptors (evidence: `backend/NCIForge/knf_core/pipeline.py`)
- KNF pipeline → Device router: routes device
- KNF pipeline → Tool configuration: configures tools
- KNF pipeline → KUID fingerprint: creates fingerprint
- KNF pipeline → Quadrant classification: classifies results (evidence: `backend/NCIForge/knf_core/main.py`)
- Python API → Run database: reads and writes (evidence: `backend/NCIForge/server.py`)
- Run database → Results table: serves run results
- Results table → KNF Studio user: shows descriptors (evidence: `README.md`)
- Molecule explorer → KNF Studio user: plots molecules (evidence: `README.md`)
- Analysis view → KNF Studio user: presents analysis
