# alena-xinran/mri2rep architecture

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

- Interactive diagram: https://gitdiagram.com/alena-xinran/mri2rep
- Repository: https://github.com/alena-xinran/mri2rep

## Overview

MRI2Rep turns free-text liver MRI reports into structured lesion labels, then trains a 3D CNN–Transformer to generate those structured reports from three-channel MRI volumes. Its user-facing web app accepts MRI inputs and presents generated reports, with validation-set comparison and visualization features. The extraction flow is visible in source; model training, evaluation, pretraining, and web capabilities are also included where documented in the README. Some subsystem links rely on README descriptions or source-index references rather than complete excerpts.

Main entry points: [`webapp/app.py`](https://github.com/alena-xinran/mri2rep/blob/main/webapp/app.py) (Inference and web routes), [`main.py`](https://github.com/alena-xinran/mri2rep/blob/main/main.py) (Training orchestrator), [`src/dataset.py`](https://github.com/alena-xinran/mri2rep/blob/main/src/dataset.py) (MRI sequence dataset), [`src/model.py`](https://github.com/alena-xinran/mri2rep/blob/main/src/model.py) (MRI report generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_labels["Report labeling"]
  node_batch["Batch runner<br/>[main.py]"]
  node_reportio["Report and prompt I/O<br/>[io.py]"]
  node_stages["Label extraction<br/>[pipeline.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_case_logs["Case logs<br/>[logger.py]"]
  node_normalize["Label normalization<br/>[post.py]"]
  node_consensus["Consensus recovery<br/>[recover_2of3.py]"]
  node_retry["Failed-case reruns<br/>[rerun_failed.py]"]
  node_dataset_build["Dataset aggregation"]
  node_summary_merge["Batch summary merge"]
end

subgraph group_modeling["Model and training"]
  node_training["Training orchestrator<br/>[main.py]"]
  node_config["Model configuration<br/>[config.py]"]
  node_dataset["MRI sequence dataset<br/>[dataset.py]"]
  node_model["MRI report generator<br/>[model.py]"]
  node_engine["Training and metrics<br/>[engine.py]"]
  node_pretraining["PV pretraining<br/>[pretrain_pv.py]"]
  node_run_artifacts["Checkpoints and logs"]
end

subgraph group_assessment["Evaluation and analysis"]
  node_nlg_eval["NLG evaluation<br/>[evaluate_nlg.py]"]
  node_pred_analysis["Prediction analysis<br/>[analyze_preds.py]"]
  node_gradcam["GradCAM visualization<br/>[gradcam_vis.py]"]
end

subgraph group_app["Web application"]
  node_webapp["Inference and web routes<br/>[app.py]"]
end

node_radiologist(("Report inputs"))
node_web_user(("MRI web user"))
node_mri_upload["MRI volumes"]
node_report_output["Structured report"]

node_radiologist -->|"provides reports"| node_batch
node_batch -->|"finds and reads"| node_reportio
node_batch -->|"logs cases"| node_case_logs
node_batch -->|"runs stages"| node_stages
node_stages -->|"loads prompts"| node_reportio
node_stages -->|"requests completions"| node_llm
node_llm -.->|"records responses"| node_case_logs
node_batch -->|"formats outputs"| node_normalize
node_consensus -->|"selects reruns"| node_retry
node_retry -->|"reprocesses cases"| node_stages
node_normalize -->|"prepares labels"| node_dataset_build
node_dataset_build -->|"produces summaries"| node_summary_merge
node_summary_merge -->|"supplies training labels"| node_dataset
node_training -->|"loads splits"| node_dataset
node_training -->|"optimizes model"| node_model
node_training -->|"trains and evaluates"| node_engine
node_training -->|"uses settings"| node_config
node_training -->|"saves checkpoints"| node_run_artifacts
node_pretraining -->|"pretrains backbone"| node_model
node_pretraining -->|"uses settings"| node_config
node_nlg_eval -->|"loads evaluation data"| node_dataset
node_nlg_eval -->|"generates reports"| node_model
node_nlg_eval -->|"uses evaluation metrics"| node_engine
node_nlg_eval -->|"loads checkpoint"| node_run_artifacts
node_pred_analysis -->|"loads cases"| node_dataset
node_pred_analysis -->|"compares predictions"| node_model
node_pred_analysis -->|"loads run"| node_run_artifacts
node_gradcam -->|"loads MRI cases"| node_dataset
node_gradcam -->|"computes attribution"| node_model
node_gradcam -->|"loads checkpoint"| node_run_artifacts
node_web_user -->|"submits MRI"| node_webapp
node_mri_upload -->|"uploads volumes"| node_webapp
node_webapp -->|"loads validation cases"| node_dataset
node_webapp -->|"runs inference"| node_model
node_webapp -->|"loads checkpoint"| node_run_artifacts
node_webapp -->|"formats findings"| node_report_output

click node_batch "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/main.py"
click node_reportio "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/utils/io.py"
click node_stages "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/pipeline.py"
click node_llm "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/utils/llm.py"
click node_case_logs "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/utils/logger.py"
click node_normalize "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/post.py"
click node_consensus "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/recover_2of3.py"
click node_retry "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/rerun_failed.py"
click node_dataset_build "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/build_accurate_dataset.py"
click node_summary_merge "https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/merge_summary_yes.py"
click node_training "https://github.com/alena-xinran/mri2rep/blob/main/main.py"
click node_config "https://github.com/alena-xinran/mri2rep/blob/main/src/config.py"
click node_dataset "https://github.com/alena-xinran/mri2rep/blob/main/src/dataset.py"
click node_model "https://github.com/alena-xinran/mri2rep/blob/main/src/model.py"
click node_engine "https://github.com/alena-xinran/mri2rep/blob/main/src/engine.py"
click node_pretraining "https://github.com/alena-xinran/mri2rep/blob/main/pretrain_pv.py"
click node_nlg_eval "https://github.com/alena-xinran/mri2rep/blob/main/evaluate_nlg.py"
click node_pred_analysis "https://github.com/alena-xinran/mri2rep/blob/main/analyze_preds.py"
click node_gradcam "https://github.com/alena-xinran/mri2rep/blob/main/gradcam_vis.py"
click node_webapp "https://github.com/alena-xinran/mri2rep/blob/main/webapp/app.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_batch,node_reportio,node_stages,node_llm,node_case_logs,node_normalize,node_consensus,node_retry,node_dataset_build,node_summary_merge,node_web_user toneBlue
class node_training,node_config,node_dataset,node_model,node_engine,node_pretraining,node_run_artifacts toneAmber
class node_nlg_eval,node_pred_analysis,node_gradcam toneMint
class node_webapp toneRose
class node_radiologist,node_mri_upload,node_report_output toneIndigo
```

## Components

### Report labeling

- [Batch runner](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/main.py): `Report_Process/main.py`
- [Report and prompt I/O](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/utils/io.py): `Report_Process/utils/io.py`
- [Label extraction](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/pipeline.py): `Report_Process/pipeline.py`
- [LLM client](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/utils/llm.py): `Report_Process/utils/llm.py`
- [Case logs](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/utils/logger.py): `Report_Process/utils/logger.py`
- [Label normalization](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/post.py): `Report_Process/post.py`
- [Consensus recovery](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/recover_2of3.py): `Report_Process/recover_2of3.py`
- [Failed-case reruns](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/rerun_failed.py): `Report_Process/rerun_failed.py`
- [Dataset aggregation](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/build_accurate_dataset.py): `Report_Process/build_accurate_dataset.py`
- [Batch summary merge](https://github.com/alena-xinran/mri2rep/blob/main/Report_Process/merge_summary_yes.py): `Report_Process/merge_summary_yes.py`

### Model and training

- [Training orchestrator](https://github.com/alena-xinran/mri2rep/blob/main/main.py): `main.py`
- [Model configuration](https://github.com/alena-xinran/mri2rep/blob/main/src/config.py): `src/config.py`
- [MRI sequence dataset](https://github.com/alena-xinran/mri2rep/blob/main/src/dataset.py): `src/dataset.py`
- [MRI report generator](https://github.com/alena-xinran/mri2rep/blob/main/src/model.py): `src/model.py`
- [Training and metrics](https://github.com/alena-xinran/mri2rep/blob/main/src/engine.py): `src/engine.py`
- [PV pretraining](https://github.com/alena-xinran/mri2rep/blob/main/pretrain_pv.py): `pretrain_pv.py`
- **Checkpoints and logs**

### Evaluation and analysis

- [NLG evaluation](https://github.com/alena-xinran/mri2rep/blob/main/evaluate_nlg.py): `evaluate_nlg.py`
- [Prediction analysis](https://github.com/alena-xinran/mri2rep/blob/main/analyze_preds.py): `analyze_preds.py`
- [GradCAM visualization](https://github.com/alena-xinran/mri2rep/blob/main/gradcam_vis.py): `gradcam_vis.py`

### Web application

- [Inference and web routes](https://github.com/alena-xinran/mri2rep/blob/main/webapp/app.py): `webapp/app.py`

### Other components

- **Report inputs**
- **MRI web user**
- **MRI volumes**
- **Structured report**

## Connections

- Report inputs → Batch runner: provides reports
- Batch runner → Report and prompt I/O: finds and reads (evidence: `Report_Process/main.py`)
- Batch runner → Case logs: logs cases (evidence: `Report_Process/main.py`)
- Batch runner → Label extraction: runs stages (evidence: `Report_Process/main.py`)
- Label extraction → Report and prompt I/O: loads prompts (evidence: `Report_Process/pipeline.py`)
- Label extraction → LLM client: requests completions (evidence: `Report_Process/pipeline.py`)
- LLM client → Case logs: records responses
- Batch runner → Label normalization: formats outputs
- Consensus recovery → Failed-case reruns: selects reruns
- Failed-case reruns → Label extraction: reprocesses cases (evidence: `Report_Process/rerun_failed.py`)
- Label normalization → Dataset aggregation: prepares labels
- Dataset aggregation → Batch summary merge: produces summaries
- Batch summary merge → MRI sequence dataset: supplies training labels
- Training orchestrator → MRI sequence dataset: loads splits (evidence: `main.py`)
- Training orchestrator → MRI report generator: optimizes model (evidence: `main.py`)
- Training orchestrator → Training and metrics: trains and evaluates (evidence: `main.py`)
- Training orchestrator → Model configuration: uses settings (evidence: `main.py`)
- Training orchestrator → Checkpoints and logs: saves checkpoints
- PV pretraining → MRI report generator: pretrains backbone (evidence: `pretrain_pv.py`)
- PV pretraining → Model configuration: uses settings (evidence: `pretrain_pv.py`)
- NLG evaluation → MRI sequence dataset: loads evaluation data (evidence: `evaluate_nlg.py`)
- NLG evaluation → MRI report generator: generates reports (evidence: `evaluate_nlg.py`)
- NLG evaluation → Training and metrics: uses evaluation metrics (evidence: `evaluate_nlg.py`)
- NLG evaluation → Checkpoints and logs: loads checkpoint
- Prediction analysis → MRI sequence dataset: loads cases (evidence: `analyze_preds.py`)
- Prediction analysis → MRI report generator: compares predictions (evidence: `analyze_preds.py`)
- Prediction analysis → Checkpoints and logs: loads run
- GradCAM visualization → MRI sequence dataset: loads MRI cases (evidence: `gradcam_vis.py`)
- GradCAM visualization → MRI report generator: computes attribution (evidence: `gradcam_vis.py`)
- GradCAM visualization → Checkpoints and logs: loads checkpoint
- MRI web user → Inference and web routes: submits MRI (evidence: `webapp/app.py`)
- MRI volumes → Inference and web routes: uploads volumes (evidence: `webapp/app.py`)
- Inference and web routes → MRI sequence dataset: loads validation cases (evidence: `webapp/app.py`)
- Inference and web routes → MRI report generator: runs inference (evidence: `webapp/app.py`)
- Inference and web routes → Checkpoints and logs: loads checkpoint (evidence: `webapp/app.py`)
- Inference and web routes → Structured report: formats findings (evidence: `webapp/app.py`)
