# mkarthikeya866-ops/xgbioactive architecture

> Architecture diagram of the GitHub repository mkarthikeya866-ops/xgbioactive, 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/mkarthikeya866-ops/xgbioactive
- Repository: https://github.com/mkarthikeya866-ops/xgbioactive

## Overview

This repository presents a COX-2 bioactivity prediction product: users submit a molecular SMILES string, the backend calculates descriptors, runs an XGBoost model, and returns a class and confidence while recording prediction history. It also provides compound catalog operations and a research workflow for preparing data and training the classifier. The backend call paths are supported by excerpts; research-stage links follow the README. The frontend source was indexed but not excerpted, so its connection to the API is left unverified.

Main entry points: [`Backend/app/main.py`](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/main.py) (FastAPI application), [`Backend/app/database.py`](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/database.py) (SQL database access), [`Backend/app/api/v1/router.py`](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/router.py) (API router), [`Backend/app/api/v1/endpoints/predict.py`](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/predict.py) (Prediction endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_frontend["Web frontend<br/>[script.js]"]
end

subgraph group_api["API layer"]
  node_app["FastAPI application<br/>[main.py]"]
  node_routes["API router<br/>[router.py]"]
  node_health["Health endpoint<br/>[system.py]"]
  node_settings["Application settings<br/>[config.py]"]
end

subgraph group_prediction["Prediction"]
  node_prediction_endpoint["Prediction endpoint<br/>[predict.py]"]
  node_predict_service["Descriptor and prediction service<br/>[prediction.py]"]
  node_model_artifact["COX-2 XGBoost model<br/>[xgb_cox2.joblib]"]
  node_prediction_schemas["Prediction schemas"]
end

subgraph group_catalog["Compound catalog"]
  node_compound_endpoint["Compound catalog API<br/>[compounds.py]"]
  node_compound_schemas["Compound schemas<br/>[schemas.py]"]
  node_data_models["Database models<br/>[models.py]"]
  node_database[("SQL database access<br/>[database.py]")]
  node_seed["Starter catalog seeding<br/>[seed.py]"]
end

subgraph group_research["Research workflow"]
  node_raw_data["Chemical activity data"]
  node_import_data["ChEMBL data import<br/>[import_chembl.py]"]
  node_training_data["Preprocessed COX-2 data"]
  node_training["Model training and evaluation<br/>[train_model.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"submits predictions"| node_app
node_app -->|"registers routes"| node_routes
node_app -->|"loads settings"| node_settings
node_app -->|"initializes schema"| node_database
node_app -->|"seeds catalog"| node_seed
node_routes -->|"registers endpoint"| node_health
node_routes -->|"registers endpoint"| node_compound_endpoint
node_routes -->|"registers endpoint"| node_prediction_endpoint
node_health -->|"reads settings"| node_settings
node_prediction_endpoint -->|"calls prediction"| node_predict_service
node_prediction_endpoint -->|"records and reads history"| node_database
node_prediction_endpoint -->|"validates and returns"| node_prediction_schemas
node_predict_service -->|"loads model"| node_model_artifact
node_compound_endpoint -->|"queries and updates"| node_database
node_compound_endpoint -->|"queries compounds"| node_data_models
node_compound_endpoint -->|"validates and returns"| node_compound_schemas
node_data_models -->|"uses ORM base"| node_database
node_seed -->|"creates starter compounds"| node_data_models
node_seed -->|"persists seed records"| node_database
node_raw_data -.->|"provides source data"| node_import_data
node_import_data -.->|"prepares compounds"| node_training_data
node_training_data -.->|"trains on data"| node_training
node_training -.->|"produces classifier"| node_model_artifact

click node_frontend "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Frontend/script.js"
click node_app "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/main.py"
click node_routes "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/router.py"
click node_health "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/system.py"
click node_settings "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/config.py"
click node_prediction_endpoint "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/predict.py"
click node_predict_service "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/services/prediction.py"
click node_model_artifact "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/models/xgb_cox2.joblib"
click node_prediction_schemas "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/schemas_prediction.py"
click node_compound_endpoint "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/compounds.py"
click node_compound_schemas "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/schemas.py"
click node_data_models "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/models.py"
click node_database "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/database.py"
click node_seed "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/seed.py"
click node_raw_data "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/data/CHEMBL230_RAW_DATA.csv"
click node_import_data "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/scripts/import_chembl.py"
click node_training_data "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/data/CHEMBL230_Preprocessed_Data.csv"
click node_training "https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/scripts/train_model.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_frontend,node_user toneBlue
class node_app,node_routes,node_health,node_settings toneAmber
class node_prediction_endpoint,node_predict_service,node_model_artifact,node_prediction_schemas toneMint
class node_compound_endpoint,node_compound_schemas,node_data_models,node_database,node_seed toneRose
class node_raw_data,node_import_data,node_training_data,node_training toneIndigo
```

## Components

### User interface

- [Web frontend](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Frontend/script.js): `Frontend/script.js`

### API layer

- [FastAPI application](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/main.py): `Backend/app/main.py`
- [API router](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/router.py): `Backend/app/api/v1/router.py`
- [Health endpoint](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/system.py): `Backend/app/api/v1/endpoints/system.py`
- [Application settings](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/config.py): `Backend/app/config.py`

### Prediction

- [Prediction endpoint](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/predict.py): `Backend/app/api/v1/endpoints/predict.py`
- [Descriptor and prediction service](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/services/prediction.py): `Backend/app/services/prediction.py`
- [COX-2 XGBoost model](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/models/xgb_cox2.joblib): `Backend/models/xgb_cox2.joblib`
- [Prediction schemas](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/schemas_prediction.py): `Backend/app/schemas_prediction.py`

### Compound catalog

- [Compound catalog API](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/api/v1/endpoints/compounds.py): `Backend/app/api/v1/endpoints/compounds.py`
- [Compound schemas](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/schemas.py): `Backend/app/schemas.py`
- [Database models](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/models.py): `Backend/app/models.py`
- [SQL database access](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/database.py): `Backend/app/database.py`
- [Starter catalog seeding](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/app/seed.py): `Backend/app/seed.py`

### Research workflow

- [Chemical activity data](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/data/CHEMBL230_RAW_DATA.csv): `data/CHEMBL230_RAW_DATA.csv`
- [ChEMBL data import](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/scripts/import_chembl.py): `Backend/scripts/import_chembl.py`
- [Preprocessed COX-2 data](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/data/CHEMBL230_Preprocessed_Data.csv): `Backend/data/CHEMBL230_Preprocessed_Data.csv`
- [Model training and evaluation](https://github.com/mkarthikeya866-ops/xgbioactive/blob/main/Backend/scripts/train_model.py): `Backend/scripts/train_model.py`

### Other components

- **User**

## Connections

- User → Web frontend: uses
- Web frontend → FastAPI application: submits predictions
- FastAPI application → API router: registers routes (evidence: `Backend/app/main.py`)
- FastAPI application → Application settings: loads settings (evidence: `Backend/app/main.py`)
- FastAPI application → SQL database access: initializes schema (evidence: `Backend/app/main.py`)
- FastAPI application → Starter catalog seeding: seeds catalog (evidence: `Backend/app/main.py`)
- API router → Health endpoint: registers endpoint (evidence: `Backend/app/api/v1/router.py`)
- API router → Compound catalog API: registers endpoint (evidence: `Backend/app/api/v1/router.py`)
- API router → Prediction endpoint: registers endpoint (evidence: `Backend/app/api/v1/router.py`)
- Health endpoint → Application settings: reads settings (evidence: `Backend/app/api/v1/endpoints/system.py`)
- Prediction endpoint → Descriptor and prediction service: calls prediction (evidence: `Backend/app/api/v1/endpoints/predict.py`)
- Prediction endpoint → SQL database access: records and reads history (evidence: `Backend/app/api/v1/endpoints/predict.py`)
- Prediction endpoint → Prediction schemas: validates and returns (evidence: `Backend/app/api/v1/endpoints/predict.py`)
- Descriptor and prediction service → COX-2 XGBoost model: loads model (evidence: `Backend/app/services/prediction.py`)
- Compound catalog API → SQL database access: queries and updates (evidence: `Backend/app/api/v1/endpoints/compounds.py`)
- Compound catalog API → Database models: queries compounds (evidence: `Backend/app/api/v1/endpoints/compounds.py`)
- Compound catalog API → Compound schemas: validates and returns (evidence: `Backend/app/api/v1/endpoints/compounds.py`)
- Database models → SQL database access: uses ORM base (evidence: `Backend/app/models.py`)
- Starter catalog seeding → Database models: creates starter compounds (evidence: `Backend/app/seed.py`)
- Starter catalog seeding → SQL database access: persists seed records (evidence: `Backend/app/seed.py`)
- Chemical activity data → ChEMBL data import: provides source data (evidence: `README.md`)
- ChEMBL data import → Preprocessed COX-2 data: prepares compounds (evidence: `README.md`)
- Preprocessed COX-2 data → Model training and evaluation: trains on data (evidence: `README.md`)
- Model training and evaluation → COX-2 XGBoost model: produces classifier (evidence: `README.md`)
