# vigneshreddykura/ecabsd architecture

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

## Overview

ECABSD predicts binding-site residues for a target protein chain using its structure and an optional partner chain. The principal inference flow is CLI or web request → residue-graph construction → GATv2 encoding and cross-attention → per-residue probabilities, which can be exported. Separate product capabilities include batch inference, explainability, docking integration, and model training/evaluation. The README documents the model stages; source excerpts and the index support the cited code links. Docking and some web internals are not shown in enough detail to map their connections.

Main entry points: [`models/ecabsd_v3_model.py`](https://github.com/vigneshreddykura/ecabsd/blob/main/models/ecabsd_v3_model.py) (ECABSD Model), [`cli.py`](https://github.com/vigneshreddykura/ecabsd/blob/main/cli.py) (CLI), [`predict.py`](https://github.com/vigneshreddykura/ecabsd/blob/main/predict.py) (Single Prediction), [`web/app.py`](https://github.com/vigneshreddykura/ecabsd/blob/main/web/app.py) (Web API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Web API<br/>[app.py]"]
end

subgraph group_inference["Prediction Pipeline"]
  node_batch["Batch Prediction<br/>[batch_predict.py]"]
  node_single["Single Prediction<br/>[predict.py]"]
  node_graph["Residue Graphs"]
  node_prob["Residue Probabilities<br/>[predict.py]"]
end

subgraph group_ml["Model Development"]
  node_model["ECABSD Model<br/>[ecabsd_v3_model.py]"]
  node_encoder["GATv2 Encoder<br/>[ecabsd_v3_model.py]"]
  node_attention["Cross-Attention<br/>[cross_attention.py]"]
  node_dataset[("Paired Graph Dataset<br/>[dataset.py]")]
  node_training["Training<br/>[train.py]"]
  node_evaluation["Evaluation<br/>[evaluate.py]"]
end

subgraph group_tools["Analysis and Outputs"]
  node_explain["Explainability<br/>[gradcam.py]"]
  node_rollout["Attention Rollout"]
  node_exports["Result Export<br/>[csv_export.py]"]
  node_docking["Docking Integration<br/>[vina_runner.py]"]
end

node_user(("Researcher"))

node_user -->|"runs commands"| node_cli
node_user -->|"submits structures"| node_web
node_cli -->|"runs prediction"| node_single
node_cli -->|"runs batch"| node_batch
node_batch -->|"calls prediction"| node_single
node_single -->|"builds graphs"| node_graph
node_single -->|"runs inference"| node_model
node_graph -.->|"provides graph inputs"| node_model
node_model -->|"encodes residues"| node_encoder
node_encoder -.->|"passes representations"| node_attention
node_attention -.->|"informs classification"| node_model
node_model -->|"predicts probabilities"| node_prob
node_single -.->|"produces results"| node_prob
node_web -->|"builds graphs"| node_graph
node_web -->|"serves predictions"| node_model
node_cli -->|"runs training"| node_training
node_cli -->|"runs evaluation"| node_evaluation
node_training -->|"loads samples"| node_dataset
node_training -->|"trains model"| node_model
node_evaluation -->|"loads samples"| node_dataset
node_evaluation -.->|"evaluates model"| node_model
node_cli -->|"exports results"| node_exports

click node_cli "https://github.com/vigneshreddykura/ecabsd/blob/main/cli.py"
click node_web "https://github.com/vigneshreddykura/ecabsd/blob/main/web/app.py"
click node_batch "https://github.com/vigneshreddykura/ecabsd/blob/main/batch_predict.py"
click node_single "https://github.com/vigneshreddykura/ecabsd/blob/main/predict.py"
click node_graph "https://github.com/vigneshreddykura/ecabsd/blob/main/models/graph_construction.py"
click node_prob "https://github.com/vigneshreddykura/ecabsd/blob/main/predict.py"
click node_model "https://github.com/vigneshreddykura/ecabsd/blob/main/models/ecabsd_v3_model.py"
click node_encoder "https://github.com/vigneshreddykura/ecabsd/blob/main/models/ecabsd_v3_model.py"
click node_attention "https://github.com/vigneshreddykura/ecabsd/blob/main/models/cross_attention.py"
click node_dataset "https://github.com/vigneshreddykura/ecabsd/blob/main/data/dataset.py"
click node_training "https://github.com/vigneshreddykura/ecabsd/blob/main/train.py"
click node_evaluation "https://github.com/vigneshreddykura/ecabsd/blob/main/evaluate.py"
click node_explain "https://github.com/vigneshreddykura/ecabsd/blob/main/explainability/gradcam.py"
click node_rollout "https://github.com/vigneshreddykura/ecabsd/blob/main/explainability/attention_rollout.py"
click node_exports "https://github.com/vigneshreddykura/ecabsd/blob/main/exports/csv_export.py"
click node_docking "https://github.com/vigneshreddykura/ecabsd/blob/main/docking/vina_runner.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_cli,node_web toneBlue
class node_batch,node_single,node_graph,node_prob toneAmber
class node_model,node_encoder,node_attention,node_dataset,node_training,node_evaluation toneMint
class node_explain,node_rollout,node_exports,node_docking toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/vigneshreddykura/ecabsd/blob/main/cli.py): `cli.py`
- [Web API](https://github.com/vigneshreddykura/ecabsd/blob/main/web/app.py): `web/app.py`

### Prediction Pipeline

- [Batch Prediction](https://github.com/vigneshreddykura/ecabsd/blob/main/batch_predict.py): `batch_predict.py`
- [Single Prediction](https://github.com/vigneshreddykura/ecabsd/blob/main/predict.py): `predict.py`
- [Residue Graphs](https://github.com/vigneshreddykura/ecabsd/blob/main/models/graph_construction.py): `models/graph_construction.py`
- [Residue Probabilities](https://github.com/vigneshreddykura/ecabsd/blob/main/predict.py): `predict.py`

### Model Development

- [ECABSD Model](https://github.com/vigneshreddykura/ecabsd/blob/main/models/ecabsd_v3_model.py): `models/ecabsd_v3_model.py`
- [GATv2 Encoder](https://github.com/vigneshreddykura/ecabsd/blob/main/models/ecabsd_v3_model.py): `models/ecabsd_v3_model.py`
- [Cross-Attention](https://github.com/vigneshreddykura/ecabsd/blob/main/models/cross_attention.py): `models/cross_attention.py`
- [Paired Graph Dataset](https://github.com/vigneshreddykura/ecabsd/blob/main/data/dataset.py): `data/dataset.py`
- [Training](https://github.com/vigneshreddykura/ecabsd/blob/main/train.py): `train.py`
- [Evaluation](https://github.com/vigneshreddykura/ecabsd/blob/main/evaluate.py): `evaluate.py`

### Analysis and Outputs

- [Explainability](https://github.com/vigneshreddykura/ecabsd/blob/main/explainability/gradcam.py): `explainability/gradcam.py`
- [Attention Rollout](https://github.com/vigneshreddykura/ecabsd/blob/main/explainability/attention_rollout.py): `explainability/attention_rollout.py`
- [Result Export](https://github.com/vigneshreddykura/ecabsd/blob/main/exports/csv_export.py): `exports/csv_export.py`
- [Docking Integration](https://github.com/vigneshreddykura/ecabsd/blob/main/docking/vina_runner.py): `docking/vina_runner.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: runs commands (evidence: `cli.py`)
- Researcher → Web API: submits structures (evidence: `web/app.py`)
- CLI → Single Prediction: runs prediction (evidence: `cli.py`)
- CLI → Batch Prediction: runs batch (evidence: `cli.py`)
- Batch Prediction → Single Prediction: calls prediction (evidence: `batch_predict.py`)
- Single Prediction → Residue Graphs: builds graphs (evidence: `predict.py`)
- Single Prediction → ECABSD Model: runs inference (evidence: `predict.py`)
- Residue Graphs → ECABSD Model: provides graph inputs (evidence: `README.md`)
- ECABSD Model → GATv2 Encoder: encodes residues (evidence: `README.md`)
- GATv2 Encoder → Cross-Attention: passes representations (evidence: `README.md`)
- Cross-Attention → ECABSD Model: informs classification (evidence: `README.md`)
- ECABSD Model → Residue Probabilities: predicts probabilities (evidence: `README.md`)
- Single Prediction → Residue Probabilities: produces results (evidence: `predict.py`)
- Web API → Residue Graphs: builds graphs (evidence: `web/app.py`)
- Web API → ECABSD Model: serves predictions (evidence: `web/app.py`)
- CLI → Training: runs training (evidence: `cli.py`)
- CLI → Evaluation: runs evaluation (evidence: `cli.py`)
- Training → Paired Graph Dataset: loads samples (evidence: `train.py`)
- Training → ECABSD Model: trains model (evidence: `train.py`)
- Evaluation → Paired Graph Dataset: loads samples (evidence: `evaluate.py`)
- Evaluation → ECABSD Model: evaluates model
- CLI → Result Export: exports results (evidence: `cli.py`)
