# tumo505/grail-heart architecture

> Architecture diagram of the GitHub repository tumo505/grail-heart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tumo505/grail-heart
- Repository: https://github.com/tumo505/grail-heart

## Overview

GRAIL-Heart is a cardiac spatial-transcriptomics analysis framework. Its main workflow takes expression and spatial data, constructs a cell graph, predicts ligand–receptor activity, and supports inverse analysis to rank signals associated with cell fates. The README also documents model training, curated interaction resources, pathway analysis, and an interactive app. The sampled excerpts do not expose all package wiring, so uncertain implementation links are omitted.

Main entry points: [`src/grail_heart/models/grail_heart.py`](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/grail_heart.py) (GRAIL-Heart model), [`src/grail_heart/inference.py`](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/inference.py) (Inference API), [`app/app.py`](https://github.com/tumo505/grail-heart/blob/main/app/app.py) (Interactive web app), [`src/grail_heart/data/cellchat_database.py`](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/cellchat_database.py) (L–R resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Data and interactions"]
  node_datasets["Dataset loading<br/>[datasets.py]"]
  node_graph["Spatial graph<br/>[graph_builder.py]"]
  node_lrdb["L–R resources"]
  node_expanded_lr["Expanded L–R pairs"]
end

subgraph group_model["GNN and inference"]
  node_trainer["Training<br/>[trainer.py]"]
  node_encoders["Feature encoders<br/>[encoders.py]"]
  node_gat["Graph attention<br/>[gat_layers.py]"]
  node_core_model["GRAIL-Heart model<br/>[grail_heart.py]"]
  node_heads["Prediction heads<br/>[predictors.py]"]
  node_inverse["Inverse modeling"]
  node_inference["Inference API<br/>[inference.py]"]
end

subgraph group_analysis["Analysis and visualization"]
  node_pathways["Pathway resources"]
  node_visualization["Spatial visualization<br/>[spatial_viz.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_webapp["Interactive web app<br/>[app.py]"]
  node_cli["Command-line entry<br/>[cli.py]"]
end

node_researcher(("Researcher"))
node_spatial_data["Spatial data"]
node_results["Analysis results"]
node_omnipath(("OmniPath"))

node_researcher -->|"uploads data"| node_webapp
node_researcher -->|"runs analysis"| node_cli
node_spatial_data -->|"loads"| node_datasets
node_datasets -->|"constructs graph"| node_graph
node_omnipath -.->|"provides interactions"| node_lrdb
node_expanded_lr -->|"supplements pairs"| node_lrdb
node_trainer -->|"trains"| node_core_model
node_encoders -->|"encodes features"| node_core_model
node_gat -->|"performs message passing"| node_core_model
node_core_model -->|"produces predictions"| node_heads
node_core_model -->|"supports fate analysis"| node_inverse
node_inference -->|"runs model"| node_core_model
node_inference -->|"scores interactions"| node_lrdb
node_inference -->|"returns predictions"| node_results
node_inverse -->|"ranks causal signals"| node_results
node_pathways -->|"supports enrichment"| node_results
node_visualization -->|"renders networks"| node_results
node_webapp -->|"runs inference"| node_inference
node_webapp -->|"presents analysis"| node_results
node_cli -->|"invokes predictions"| node_inference

click node_datasets "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/datasets.py"
click node_graph "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/graph_builder.py"
click node_lrdb "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/cellchat_database.py"
click node_expanded_lr "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/expanded_lr_database.py"
click node_trainer "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/training/trainer.py"
click node_encoders "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/encoders.py"
click node_gat "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/gat_layers.py"
click node_core_model "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/grail_heart.py"
click node_heads "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/predictors.py"
click node_inverse "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/inverse_modelling.py"
click node_inference "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/inference.py"
click node_pathways "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/cellchat_database.py"
click node_visualization "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/visualization/spatial_viz.py"
click node_webapp "https://github.com/tumo505/grail-heart/blob/main/app/app.py"
click node_cli "https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/cli.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_datasets,node_graph,node_lrdb,node_expanded_lr toneBlue
class node_trainer,node_encoders,node_gat,node_core_model,node_heads,node_inverse,node_inference toneAmber
class node_pathways,node_visualization toneMint
class node_webapp,node_cli toneRose
class node_researcher,node_spatial_data,node_results,node_omnipath toneIndigo
```

## Components

### Data and interactions

- [Dataset loading](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/datasets.py): `src/grail_heart/data/datasets.py`
- [Spatial graph](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/graph_builder.py): `src/grail_heart/data/graph_builder.py`
- [L–R resources](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/cellchat_database.py): `src/grail_heart/data/cellchat_database.py`
- [Expanded L–R pairs](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/expanded_lr_database.py): `src/grail_heart/data/expanded_lr_database.py`

### GNN and inference

- [Training](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/training/trainer.py): `src/grail_heart/training/trainer.py`
- [Feature encoders](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/encoders.py): `src/grail_heart/models/encoders.py`
- [Graph attention](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/gat_layers.py): `src/grail_heart/models/gat_layers.py`
- [GRAIL-Heart model](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/grail_heart.py): `src/grail_heart/models/grail_heart.py`
- [Prediction heads](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/predictors.py): `src/grail_heart/models/predictors.py`
- [Inverse modeling](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/models/inverse_modelling.py): `src/grail_heart/models/inverse_modelling.py`
- [Inference API](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/inference.py): `src/grail_heart/inference.py`

### Analysis and visualization

- [Pathway resources](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/data/cellchat_database.py): `src/grail_heart/data/cellchat_database.py`
- [Spatial visualization](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/visualization/spatial_viz.py): `src/grail_heart/visualization/spatial_viz.py`

### User interfaces

- [Interactive web app](https://github.com/tumo505/grail-heart/blob/main/app/app.py): `app/app.py`
- [Command-line entry](https://github.com/tumo505/grail-heart/blob/main/src/grail_heart/cli.py): `src/grail_heart/cli.py`

### Other components

- **Researcher**
- **Spatial data**
- **Analysis results**
- **OmniPath**

## Connections

- Researcher → Interactive web app: uploads data
- Researcher → Command-line entry: runs analysis
- Spatial data → Dataset loading: loads
- Dataset loading → Spatial graph: constructs graph
- OmniPath → L–R resources: provides interactions
- Expanded L–R pairs → L–R resources: supplements pairs
- Training → GRAIL-Heart model: trains
- Feature encoders → GRAIL-Heart model: encodes features
- Graph attention → GRAIL-Heart model: performs message passing
- GRAIL-Heart model → Prediction heads: produces predictions
- GRAIL-Heart model → Inverse modeling: supports fate analysis
- Inference API → GRAIL-Heart model: runs model
- Inference API → L–R resources: scores interactions
- Inference API → Analysis results: returns predictions
- Inverse modeling → Analysis results: ranks causal signals
- Pathway resources → Analysis results: supports enrichment
- Spatial visualization → Analysis results: renders networks
- Interactive web app → Inference API: runs inference
- Interactive web app → Analysis results: presents analysis
- Command-line entry → Inference API: invokes predictions