# yahiyav/generative-ai-for-drug-discovery architecture

> Architecture diagram of the GitHub repository yahiyav/generative-ai-for-drug-discovery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yahiyav/generative-ai-for-drug-discovery
- Repository: https://github.com/yahiyav/generative-ai-for-drug-discovery

## Overview

#### Purpose and entry points
This is an end-to-end molecular-generation workflow: train a character-level SMILES VAE, generate candidate molecules, predict their properties with a graph neural network, evaluate chemical quality, and expose generation through a Flask dashboard.

Primary entry points:
- Data acquisition/preprocessing: `data/download_data.py`
- VAE training: `src/train_vae.py`
- GNN training: `src/train_gnn.py`
- Batch generation/evaluation: `src/evaluate.py`
- Web/API runtime: `server.py` (with `app.py` also present as an application-level module)

#### 1. Dataset and chemical feature boundary
The pipeline starts from ZINC250K drug-like molecules, downloads/cleans them, and computes molecular descriptors into the persisted training dataset at `data/processed/molecules.csv`.

Cheminformatics conversion is centralized in `src/mol_utils.py`: it bridges SMILES text, RDKit molecules, graph representations, fingerprints, and tokenization. This is the key boundary between chemistry-domain objects and ML-ready tensors.

Paths: `data/download_data.py`, `data/processed/molecules.csv`, `src/mol_utils.py`.

#### 2. Shared experiment configuration
Central hyperparameters—including dataset size, VAE latent dimension/batching/epochs, and GNN hidden size/epochs—are defined in `src/config.py`. Training and evaluation stages should consume this module rather than independently defining model/data assumptions.

Path: `src/config.py`.

#### 3. SMILES variational autoencoder
The generative model encodes tokenized SMILES into a continuous latent distribution, samples from that space, and decodes token sequences back into candidate SMILES. Its architecture resides in `src/vae_model.py`; training is orchestrated by `src/train_vae.py`.

The VAE output is textual molecular candidates, not directly graph tensors. Generated SMILES must therefore pass RDKit validation and graph conversion before downstream property prediction.

Paths: `src/vae_model.py`, `src/train_vae.py`, `src/mol_utils.py`.

#### 4. Molecular graph property predictor
The predictor consumes molecular graphs derived from valid SMILES and produces multiple molecular property estimates: molecular weight, LogP, TPSA, and QED. Model definition and optimization are separated into `src/gnn_model.py` and `src/train_gnn.py`.

This stage depends on consistent atom/bond graph featurization from `src/mol_utils.py`, creating a contract between generation, preprocessing, and inference.

Paths: `src/gnn_model.py`, `src/train_gnn.py`, `src/mol_utils.py`.

#### 5. Generation and evaluation pipeline
`src/evaluate.py` composes trained VAE generation, validity filtering, novelty checks against the processed dataset, structural similarity/fingerprint analysis, Lipinski drug-likeness assessment, and GNN property inference.

It materializes reproducible artifacts rather than only console output: aggregate metrics in `results/evaluation_metrics.json`, generated SMILES in `results/generated_molecules.csv`, and predicted properties in `results/generated_properties.csv`.

Paths: `src/evaluate.py`, `results/evaluation_metrics.json`, `results/generated_properties.csv`.

#### 6. Interactive serving layer
The Flask server provides the interactive runtime on port 7860, serving the static dashboard and connecting browser actions to molecule generation/evaluation behavior. The browser client is a static HTML/CSS/JavaScript UI rather than a separate frontend build system.

Paths: `server.py`, `static/index.html`, `static/script.js`.

#### 7. Runtime and infrastructure
The core runtime is Python 3.9+ with PyTorch for VAE training/inference, PyTorch Geometric for graph convolution, RDKit for chemistry parsing/descriptors/fingerprints, and Flask for HTTP serving. GPU acceleration is supported, while CPU training is supported but slower.

The repository is intended for Docker-based Hugging Face Spaces deployment, where the Flask process is exposed on port 7860. ZINC is the external source dataset; no database, message queue, or remote model-serving dependency is indicated.

Main entry points: [`src/evaluate.py`](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/evaluate.py) (Batch evaluation), [`data/processed/molecules.csv`](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/data/processed/molecules.csv) (Processed molecules), [`src/mol_utils.py`](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/mol_utils.py) (Chemistry conversion), [`src/train_vae.py`](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/train_vae.py) (VAE training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data & chemistry"]
  node_zinc[("ZINC250K<br/>external dataset")]
  node_download["Download &amp; preprocess<br/>data pipeline<br/>[download_data.py]"]
  node_dataset[("Processed molecules<br/>training dataset<br/>[molecules.csv]")]
  node_mol_utils{{"Chemistry conversion<br/>RDKit feature boundary<br/>[mol_utils.py]"}}
end

subgraph group_training["Model training"]
  node_config["Experiment config<br/>shared configuration<br/>[config.py]"]
  node_vae_train["VAE training<br/>training entry point<br/>[train_vae.py]"]
  node_vae["SMILES VAE<br/>generative model<br/>[vae_model.py]"]
  node_gnn_train["GNN training<br/>training entry point<br/>[train_gnn.py]"]
  node_gnn["Property GNN<br/>multi-property predictor<br/>[gnn_model.py]"]
end

subgraph group_evaluation["Generation &amp; evaluation"]
  node_evaluate["Batch evaluation<br/>pipeline entry point<br/>[evaluate.py]"]
  node_candidates["Valid candidate SMILES<br/>generated molecules"]
  node_properties["Generated properties<br/>prediction artifact"]
  node_metrics["Evaluation metrics<br/>quality artifact"]
end

subgraph group_serving["Interactive serving"]
  node_server["Flask server<br/>HTTP runtime<br/>[server.py]"]
  node_dashboard["Browser dashboard<br/>static client<br/>[index.html]"]
  node_client_logic["Dashboard actions<br/>browser JavaScript<br/>[script.js]"]
end

node_zinc -->|"download"| node_download
node_download -->|"clean and persist"| node_dataset
node_download -->|"compute descriptors"| node_mol_utils
node_config -->|"hyperparameters"| node_vae_train
node_config -->|"hyperparameters"| node_gnn_train
node_dataset -->|"training SMILES"| node_vae_train
node_mol_utils -->|"tokenization"| node_vae_train
node_vae_train -->|"optimize"| node_vae
node_dataset -->|"molecules"| node_gnn_train
node_mol_utils -->|"graph features"| node_gnn_train
node_gnn_train -->|"optimize"| node_gnn
node_vae -->|"generate SMILES"| node_evaluate
node_dataset -->|"novelty reference"| node_evaluate
node_mol_utils -->|"validate, graph, fingerprints"| node_evaluate
node_evaluate -->|"valid molecular graphs"| node_gnn
node_evaluate -->|"write"| node_candidates
node_evaluate -->|"write predictions"| node_properties
node_evaluate -->|"write quality metrics"| node_metrics
node_dashboard -->|"loads"| node_client_logic
node_client_logic -->|"generation requests"| node_server
node_server -->|"invoke generation"| node_evaluate

click node_download "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/data/download_data.py"
click node_dataset "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/data/processed/molecules.csv"
click node_mol_utils "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/mol_utils.py"
click node_config "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/config.py"
click node_vae_train "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/train_vae.py"
click node_vae "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/vae_model.py"
click node_gnn_train "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/train_gnn.py"
click node_gnn "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/gnn_model.py"
click node_evaluate "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/evaluate.py"
click node_candidates "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/results/generated_molecules.csv"
click node_properties "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/results/generated_properties.csv"
click node_metrics "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/results/evaluation_metrics.json"
click node_server "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/server.py"
click node_dashboard "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/static/index.html"
click node_client_logic "https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/static/script.js"

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_zinc,node_download,node_dataset,node_mol_utils toneBlue
class node_config,node_vae_train,node_vae,node_gnn_train,node_gnn toneAmber
class node_evaluate,node_candidates,node_properties,node_metrics toneMint
class node_server,node_dashboard,node_client_logic toneRose
```

## Components

### Data & chemistry

- **ZINC250K**: external dataset · Source of drug-like molecules.
- [Download & preprocess](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/data/download_data.py): data pipeline · `data/download_data.py`
- [Processed molecules](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/data/processed/molecules.csv): training dataset · Cleaned SMILES and molecular descriptors. · `data/processed/molecules.csv`
- [Chemistry conversion](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/mol_utils.py): RDKit feature boundary · Converts SMILES, molecules, graphs, fingerprints, and tokens. · `src/mol_utils.py`

### Model training

- [Experiment config](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/config.py): shared configuration · `src/config.py`
- [VAE training](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/train_vae.py): training entry point · `src/train_vae.py`
- [SMILES VAE](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/vae_model.py): generative model · Encodes tokenized SMILES to latent distributions and decodes candidates. · `src/vae_model.py`
- [GNN training](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/train_gnn.py): training entry point · `src/train_gnn.py`
- [Property GNN](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/gnn_model.py): multi-property predictor · Predicts molecular weight, LogP, TPSA, and QED. · `src/gnn_model.py`

### Generation & evaluation

- [Batch evaluation](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/src/evaluate.py): pipeline entry point · Generates, validates, assesses quality, and predicts properties. · `src/evaluate.py`
- [Valid candidate SMILES](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/results/generated_molecules.csv): generated molecules · VAE output after RDKit validation and novelty checks. · `results/generated_molecules.csv`
- [Generated properties](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/results/generated_properties.csv): prediction artifact · `results/generated_properties.csv`
- [Evaluation metrics](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/results/evaluation_metrics.json): quality artifact · Validity, novelty, similarity, and Lipinski assessment results. · `results/evaluation_metrics.json`

### Interactive serving

- [Flask server](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/server.py): HTTP runtime · Serves generation behavior on port 7860. · `server.py`
- [Browser dashboard](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/static/index.html): static client · `static/index.html`
- [Dashboard actions](https://github.com/yahiyav/generative-ai-for-drug-discovery/blob/main/static/script.js): browser JavaScript · `static/script.js`

## Connections

- ZINC250K → Download & preprocess: download
- Download & preprocess → Processed molecules: clean and persist
- Download & preprocess → Chemistry conversion: compute descriptors
- Experiment config → VAE training: hyperparameters
- Experiment config → GNN training: hyperparameters
- Processed molecules → VAE training: training SMILES
- Chemistry conversion → VAE training: tokenization
- VAE training → SMILES VAE: optimize
- Processed molecules → GNN training: molecules
- Chemistry conversion → GNN training: graph features
- GNN training → Property GNN: optimize
- SMILES VAE → Batch evaluation: generate SMILES
- Processed molecules → Batch evaluation: novelty reference
- Chemistry conversion → Batch evaluation: validate, graph, fingerprints
- Batch evaluation → Property GNN: valid molecular graphs
- Batch evaluation → Valid candidate SMILES: write
- Batch evaluation → Generated properties: write predictions
- Batch evaluation → Evaluation metrics: write quality metrics
- Browser dashboard → Dashboard actions: loads
- Dashboard actions → Flask server: generation requests
- Flask server → Batch evaluation: invoke generation