# ali1810/water_solubility architecture

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

- Interactive diagram: https://gitdiagram.com/ali1810/water_solubility
- Repository: https://github.com/ali1810/water_solubility

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Python application built around a machine-learning model and served via Streamlit.
- Purpose: accept SMILES strings (or CSV uploads) in a web UI, preprocess them into molecular descriptors/fingerprints, feed them to an XGBoost model, and return water-solubility predictions.

##### File structure
- Top-level code:
- Water-Solubility.py – the Streamlit entry point
- pages/02_Project.py, 03_Contact.py, etc. – Streamlit multipage sub-apps
- utilities.py, footer.py – helper modules (preprocessing, UI footer)
- feature_order.json, xgboost_model_298_4045.json – model artifacts
- training_set_vectors.npy – precomputed vectors for metadata or reference
- Config & deployment: Dockerfile, Procfile, runtime.txt, requirements.txt
- Virtual environment dir (env/) with installed Python packages

##### README for additional insights
- Confirms ML pipeline: descriptor extraction + fingerprinting → preprocessing → XGBoost model → evaluation
- Mentions Streamlit Cloud deployment in addition to local run

a. Main components
1. Client (Web Browser)
2. Streamlit Server (HTTP/WebSocket layer)
3. Application Code
- Presentation Layer: Water-Solubility.py + pages/*.py
- Business Logic Layer: utilities.py (preprocess SMILES, load feature order, vectorize)
- Model Layer: loads xgboost_model*.json, performs predict()
4. Data & Artifacts
- feature_order.json, model JSON, training_set_vectors.npy
5. External Libraries & Services
- RDKit (molecular descriptors), XGBoost, NumPy, Pandas
- Deployment Platform: local Python env or Streamlit Cloud

b. Relationships & interactions
- Browser ↔ Streamlit Server: HTTP/WebSocket requests for UI events
- Streamlit Server → Presentation Layer: calls Water-Solubility.py / pages code
- Presentation Layer → Business Logic: passes raw SMILES or DataFrame to utilities module
- Business Logic → Model Layer: constructs feature vector, calls XGB predict
- Model Layer → Data Artifacts: reads model JSON, feature_order.json, optional .npy file
- Predictive output flows back up to the UI and to the browser

c. Architectural patterns / design principles
- Three-tier separation: presentation / logic / data
- Modularization: helper modules for preprocessing and UI elements
- Configuration-as-code: JSON artifacts, training vectors externalized

d. Key technologies/frameworks
- Python 3.9.5
- Streamlit for UI
- XGBoost for model inference
- RDKit or python-fingerprint libraries via utilities.py
- NumPy, Pandas for data management

##### Additional recommendations
- Notes for deployment steps: “Docker build”, “Streamlit Cloud URL”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        Browser["Web Browser"]:::ui
    end

    %% Server Tier
    subgraph "Server Tier"
        StreamlitServer["Streamlit Server"]:::server
        subgraph "Presentation Layer"
            Entry["Water-Solubility.py"]:::frontend
            Page1["02_Project.py"]:::frontend
            Page2["03_Contact.py"]:::frontend
            Page3["04_Data_Privacy.py"]:::frontend
            Page4["05_Directive.py"]:::frontend
        end
        subgraph "Business Logic Layer"
            Utils["utilities.py"]:::logic
            Footer["footer.py"]:::logic
        end
        subgraph "Model Layer"
            Model["XGBoost Model"]:::model
        end
    end

    %% Data & Artifacts
    subgraph "Data & Artifacts"
        FeatureOrder["feature_order.json"]:::data
        ModelJSON["xgboost_model_298_4045.json"]:::data
        Vectors["training_set_vectors.npy"]:::data
    end

    %% External Libraries
    subgraph "External Libraries"
        RDKit["RDKit"]:::external
        XGBoostLib["XGBoost"]:::external
        NumPy["NumPy"]:::external
        Pandas["Pandas"]:::external
    end

    %% Deployment Configuration
    subgraph "Deployment"
        Dockerfile["Dockerfile"]:::deploy
        Procfile["Procfile"]:::deploy
        Runtime["runtime.txt"]:::deploy
        Requirements["requirements.txt"]:::deploy
    end

    %% Connections
    Browser -->|"UI events"| StreamlitServer
    StreamlitServer -->|"loads entrypoint"| Entry
    StreamlitServer -->|"routes to multipage"| Page1
    StreamlitServer --> Page2
    StreamlitServer --> Page3
    StreamlitServer --> Page4

    Entry -->|"calls preprocessing"| Utils
    Page1 --> Utils
    Page2 --> Utils
    Page3 --> Utils
    Page4 --> Utils
    Page1 --> Footer
    Page2 --> Footer
    Page3 --> Footer
    Page4 --> Footer

    Utils -->|"constructs features"| Model
    Utils -->|"loads config"| FeatureOrder
    Utils -->|"reads vectors"| Vectors
    Model -->|"loads model JSON"| ModelJSON
    Model -->|"returns prediction"| Utils
    Utils -->|"sends results"| StreamlitServer
    StreamlitServer -->|"render output"| Browser

    %% External Libraries Connections
    RDKit --> Utils
    NumPy --> Utils
    Pandas --> Utils
    XGBoostLib --> Model

    %% Deployment flows
    Dockerfile --> StreamlitServer
    Procfile --> StreamlitServer
    Runtime --> StreamlitServer
    Requirements --> StreamlitServer

    %% Click Events
    click Entry "https://github.com/ali1810/water_solubility/blob/main/Water-Solubility.py"
    click Page1 "https://github.com/ali1810/water_solubility/blob/main/pages/02_Project.py"
    click Page2 "https://github.com/ali1810/water_solubility/blob/main/pages/03_Contact.py"
    click Page3 "https://github.com/ali1810/water_solubility/blob/main/pages/04_Data_Privacy.py"
    click Page4 "https://github.com/ali1810/water_solubility/blob/main/pages/05_Directive.py"
    click Utils "https://github.com/ali1810/water_solubility/blob/main/utilities.py"
    click Footer "https://github.com/ali1810/water_solubility/blob/main/footer.py"
    click ModelJSON "https://github.com/ali1810/water_solubility/blob/main/xgboost_model_298_4045.json"
    click FeatureOrder "https://github.com/ali1810/water_solubility/blob/main/feature_order.json"
    click Vectors "https://github.com/ali1810/water_solubility/blob/main/training_set_vectors.npy"
    click Dockerfile "https://github.com/ali1810/water_solubility/tree/main/Dockerfile"
    click Procfile "https://github.com/ali1810/water_solubility/tree/main/Procfile"
    click Runtime "https://github.com/ali1810/water_solubility/blob/main/runtime.txt"
    click Requirements "https://github.com/ali1810/water_solubility/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef server fill:#A9DFBF,stroke:#1D8348,color:#145A32;
    classDef frontend fill:#ABEBC6,stroke:#196F3D,color:#0E5303;
    classDef logic fill:#82E0AA,stroke:#1D8348,color:#0E3311;
    classDef model fill:#76D7C4,stroke:#148F77,color:#0B5345;
    classDef data fill:#F5CBA7,stroke:#B9770E,color:#784212;
    classDef external fill:#D5DBDB,stroke:#566573,color:#1B2631;
    classDef deploy fill:#D7BDE2,stroke:#884EA0,color:#4A235A;
```
