# joshua12-5/biopinn architecture

> Architecture diagram of the GitHub repository joshua12-5/biopinn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshua12-5/biopinn
- Repository: https://github.com/joshua12-5/biopinn

## Overview

BIOPINN models drug transport and biological response in a three-zone tumor, trains a parametric PINN surrogate, and uses it for evaluation, treatment optimization, and interactive results exploration. The main workflow is synthetic FDM data generation → PINN training → surrogate-based biological prediction and analysis. The graph also preserves the documented ablation and manuscript-results branches. Some analysis and dashboard details are documented or indexed but not fully excerpted, so their connections are limited to visible references and README statements.

Main entry points: [`app/server.py`](https://github.com/joshua12-5/biopinn/blob/main/app/server.py) (Dashboard Service), [`src/evaluate.py`](https://github.com/joshua12-5/biopinn/blob/main/src/evaluate.py) (Model Evaluation), [`src/optimize.py`](https://github.com/joshua12-5/biopinn/blob/main/src/optimize.py) (Dose Optimization), [`src/train.py`](https://github.com/joshua12-5/biopinn/blob/main/src/train.py) (Training Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_physics["Tumor Physics"]
  node_config["Configuration<br/>[config.py]"]
  node_microenv["Microenvironment"]
  node_fdm["FDM Solver<br/>[fdm_solver.py]"]
end

subgraph group_learning["PINN Learning"]
  node_dataset["Dataset Pipeline<br/>[data_pipeline.py]"]
  node_model["BIOPINN Model<br/>[model.py]"]
  node_losses["Physics Losses<br/>[losses.py]"]
  node_training["Training Engine<br/>[train.py]"]
end

subgraph group_analysis["Analysis"]
  node_biology["Biological Response<br/>[biology.py]"]
  node_evaluation["Model Evaluation<br/>[evaluate.py]"]
  node_optimization["Dose Optimization<br/>[optimize.py]"]
  node_ablation["Physics Ablation<br/>[ablation.py]"]
  node_visualization["Scientific Plots<br/>[visualize.py]"]
  node_manuscript["Manuscript Assets<br/>[results.py]"]
end

subgraph group_delivery["Results Interface"]
  node_dashboard["Dashboard Service<br/>[server.py]"]
  node_dashboard_ui["Dashboard UI<br/>[dashboard.js]"]
end

node_researcher(("Researcher"))

node_researcher -->|"generates data"| node_dataset
node_dataset -->|"solves simulations"| node_fdm
node_fdm -->|"gets fields"| node_microenv
node_dataset -->|"provides tensors"| node_training
node_training -->|"trains"| node_model
node_training -->|"computes losses"| node_losses
node_losses -->|"uses fields"| node_microenv
node_researcher -->|"trains model"| node_training
node_biology -->|"predicts with"| node_model
node_evaluation -->|"predicts fields"| node_biology
node_evaluation -->|"resolves reference"| node_fdm
node_evaluation -->|"measures residuals"| node_losses
node_optimization -->|"evaluates response"| node_biology
node_optimization -->|"compares solver"| node_fdm
node_optimization -->|"uses fields"| node_microenv
node_ablation -->|"trains baseline"| node_training
node_ablation -->|"compares models"| node_evaluation
node_visualization -->|"uses radial grid"| node_microenv
node_manuscript -->|"builds assets from"| node_optimization
node_manuscript -->|"builds assets from"| node_evaluation
node_manuscript -->|"builds assets from"| node_ablation
node_manuscript -->|"builds assets from"| node_biology
node_researcher -->|"explores results"| node_dashboard
node_dashboard -->|"requests response"| node_biology
node_dashboard -->|"requests evaluation"| node_evaluation
node_dashboard -->|"requests optimization"| node_optimization
node_dashboard -->|"requests ablation"| node_ablation
node_dashboard_ui -.->|"calls service"| node_dashboard
node_config -.->|"configures"| node_fdm
node_config -.->|"configures"| node_training
node_config -.->|"configures"| node_optimization

click node_config "https://github.com/joshua12-5/biopinn/blob/main/src/config.py"
click node_microenv "https://github.com/joshua12-5/biopinn/blob/main/src/microenvironment.py"
click node_fdm "https://github.com/joshua12-5/biopinn/blob/main/src/fdm_solver.py"
click node_dataset "https://github.com/joshua12-5/biopinn/blob/main/src/data_pipeline.py"
click node_model "https://github.com/joshua12-5/biopinn/blob/main/src/model.py"
click node_losses "https://github.com/joshua12-5/biopinn/blob/main/src/losses.py"
click node_training "https://github.com/joshua12-5/biopinn/blob/main/src/train.py"
click node_biology "https://github.com/joshua12-5/biopinn/blob/main/src/biology.py"
click node_evaluation "https://github.com/joshua12-5/biopinn/blob/main/src/evaluate.py"
click node_optimization "https://github.com/joshua12-5/biopinn/blob/main/src/optimize.py"
click node_ablation "https://github.com/joshua12-5/biopinn/blob/main/src/ablation.py"
click node_visualization "https://github.com/joshua12-5/biopinn/blob/main/src/visualize.py"
click node_manuscript "https://github.com/joshua12-5/biopinn/blob/main/src/results.py"
click node_dashboard "https://github.com/joshua12-5/biopinn/blob/main/app/server.py"
click node_dashboard_ui "https://github.com/joshua12-5/biopinn/blob/main/app/static/js/dashboard.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_config,node_microenv,node_fdm toneBlue
class node_dataset,node_model,node_losses,node_training toneAmber
class node_biology,node_evaluation,node_optimization,node_ablation,node_visualization,node_manuscript toneMint
class node_dashboard,node_dashboard_ui toneRose
class node_researcher toneIndigo
```

## Components

### Tumor Physics

- [Configuration](https://github.com/joshua12-5/biopinn/blob/main/src/config.py): `src/config.py`
- [Microenvironment](https://github.com/joshua12-5/biopinn/blob/main/src/microenvironment.py): `src/microenvironment.py`
- [FDM Solver](https://github.com/joshua12-5/biopinn/blob/main/src/fdm_solver.py): `src/fdm_solver.py`

### PINN Learning

- [Dataset Pipeline](https://github.com/joshua12-5/biopinn/blob/main/src/data_pipeline.py): `src/data_pipeline.py`
- [BIOPINN Model](https://github.com/joshua12-5/biopinn/blob/main/src/model.py): `src/model.py`
- [Physics Losses](https://github.com/joshua12-5/biopinn/blob/main/src/losses.py): `src/losses.py`
- [Training Engine](https://github.com/joshua12-5/biopinn/blob/main/src/train.py): `src/train.py`

### Analysis

- [Biological Response](https://github.com/joshua12-5/biopinn/blob/main/src/biology.py): `src/biology.py`
- [Model Evaluation](https://github.com/joshua12-5/biopinn/blob/main/src/evaluate.py): `src/evaluate.py`
- [Dose Optimization](https://github.com/joshua12-5/biopinn/blob/main/src/optimize.py): `src/optimize.py`
- [Physics Ablation](https://github.com/joshua12-5/biopinn/blob/main/src/ablation.py): `src/ablation.py`
- [Scientific Plots](https://github.com/joshua12-5/biopinn/blob/main/src/visualize.py): `src/visualize.py`
- [Manuscript Assets](https://github.com/joshua12-5/biopinn/blob/main/src/results.py): `src/results.py`

### Results Interface

- [Dashboard Service](https://github.com/joshua12-5/biopinn/blob/main/app/server.py): `app/server.py`
- [Dashboard UI](https://github.com/joshua12-5/biopinn/blob/main/app/static/js/dashboard.js): `app/static/js/dashboard.js`

### Other components

- **Researcher**

## Connections

- Researcher → Dataset Pipeline: generates data (evidence: `README.md`)
- Dataset Pipeline → FDM Solver: solves simulations (evidence: `src/data_pipeline.py`)
- FDM Solver → Microenvironment: gets fields (evidence: `src/fdm_solver.py`)
- Dataset Pipeline → Training Engine: provides tensors (evidence: `README.md`)
- Training Engine → BIOPINN Model: trains (evidence: `src/train.py`)
- Training Engine → Physics Losses: computes losses (evidence: `src/train.py`)
- Physics Losses → Microenvironment: uses fields (evidence: `src/losses.py`)
- Researcher → Training Engine: trains model (evidence: `README.md`)
- Biological Response → BIOPINN Model: predicts with (evidence: `src/biology.py`)
- Model Evaluation → Biological Response: predicts fields (evidence: `src/evaluate.py`)
- Model Evaluation → FDM Solver: resolves reference (evidence: `src/evaluate.py`)
- Model Evaluation → Physics Losses: measures residuals (evidence: `src/evaluate.py`)
- Dose Optimization → Biological Response: evaluates response (evidence: `src/optimize.py`)
- Dose Optimization → FDM Solver: compares solver (evidence: `src/optimize.py`)
- Dose Optimization → Microenvironment: uses fields (evidence: `src/optimize.py`)
- Physics Ablation → Training Engine: trains baseline (evidence: `src/ablation.py`)
- Physics Ablation → Model Evaluation: compares models (evidence: `src/ablation.py`)
- Scientific Plots → Microenvironment: uses radial grid (evidence: `src/visualize.py`)
- Manuscript Assets → Dose Optimization: builds assets from (evidence: `src/results.py`)
- Manuscript Assets → Model Evaluation: builds assets from (evidence: `src/results.py`)
- Manuscript Assets → Physics Ablation: builds assets from (evidence: `src/results.py`)
- Manuscript Assets → Biological Response: builds assets from (evidence: `src/results.py`)
- Researcher → Dashboard Service: explores results (evidence: `README.md`)
- Dashboard Service → Biological Response: requests response (evidence: `app/server.py`)
- Dashboard Service → Model Evaluation: requests evaluation (evidence: `app/server.py`)
- Dashboard Service → Dose Optimization: requests optimization (evidence: `app/server.py`)
- Dashboard Service → Physics Ablation: requests ablation (evidence: `app/server.py`)
- Dashboard UI → Dashboard Service: calls service
- Configuration → FDM Solver: configures
- Configuration → Training Engine: configures (evidence: `src/train.py`)
- Configuration → Dose Optimization: configures