# victorbutoi/flexray architecture

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

## Overview

FleXray is a Python package and CLI for X-ray anatomy segmentation, with additional tools for training, preparing and harmonizing datasets, rendering CT-derived DRRs, and MCP-based access. The main user workflow preprocesses an image, runs a pretrained model, and saves masks, probabilities, and logits. README capabilities guide the broader map; only some internal behavior was sampled, so uncertain implementation links are omitted.

Main entry points: [`src/fxr/inference/runner.py`](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/runner.py) (Inference runner), [`src/fxr/experiment/train.py`](https://github.com/victorbutoi/flexray/blob/main/src/fxr/experiment/train.py) (Training lifecycle), [`src/fxr/launch/cli.py`](https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/cli.py) (Training launcher), [`src/fxr/datasets/cli.py`](https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/cli.py) (Dataset CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Inference"]
  node_inference_cli["Inference CLI<br/>[cli.py]"]
  node_runner["Inference runner<br/>[runner.py]"]
  node_preprocess["Image preprocessing<br/>[preprocessing.py]"]
  node_segmenter["Model segmenter<br/>[segmenter.py]"]
  node_tta["Test-time augmentation<br/>[tta.py]"]
  node_postprocess["Prediction processing<br/>[postprocessing.py]"]
  node_artifacts["Prediction artifacts<br/>[artifacts.py]"]
end

subgraph group_training["Training"]
  node_train_cli["Training launcher<br/>[cli.py]"]
  node_readiness["Run validation<br/>[readiness.py]"]
  node_experiment["Training lifecycle<br/>[train.py]"]
  node_model["Segmentation model<br/>[unet.py]"]
  node_augmentation["Training augmentation<br/>[pipeline.py]"]
  node_loss["Segmentation losses<br/>[segmentation.py]"]
end

subgraph group_data["Data and protocols"]
  node_dataset_cli["Dataset CLI<br/>[cli.py]"]
  node_dataset_build["Dataset preparation<br/>[builders.py]"]
  node_dataset_package["Dataset packaging<br/>[packaging.py]"]
  node_dataset_runtime["Dataset runtime<br/>[runtime.py]"]
  node_thunderdb[("ThunderDB packages")]
  node_protocol_cli["Protocol CLI<br/>[cli.py]"]
  node_protocol_io["Protocol definitions<br/>[io.py]"]
end

subgraph group_drr["DRR rendering"]
  node_render_cli["DRR CLI<br/>[render_cli.py]"]
  node_drr_render["DRR rendering<br/>[rendering.py]"]
  node_ct_subjects["CT subjects<br/>[subjects.py]"]
end

subgraph group_integration["External access"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_inference["Inference tools<br/>[inference_tools.py]"]
  node_mcp_protocol["Protocol tools<br/>[protocol_tools.py]"]
end

node_user(("User"))
node_huggingface["Hugging Face"]
node_mcp_client(("AI client"))
node_output["NumPy outputs"]

node_user -->|"runs prediction"| node_inference_cli
node_inference_cli -->|"starts inference"| node_runner
node_runner -->|"prepares image"| node_preprocess
node_runner -->|"runs model"| node_segmenter
node_runner -->|"applies TTA"| node_tta
node_runner -->|"processes prediction"| node_postprocess
node_runner -->|"writes results"| node_artifacts
node_segmenter -->|"loads model bundle"| node_huggingface
node_artifacts -->|"saves arrays"| node_output
node_user -->|"starts training"| node_train_cli
node_train_cli -->|"validates config"| node_readiness
node_train_cli -->|"runs experiment"| node_experiment
node_experiment -->|"trains model"| node_model
node_experiment -->|"augments batches"| node_augmentation
node_experiment -->|"computes loss"| node_loss
node_user -->|"prepares datasets"| node_dataset_cli
node_dataset_cli -->|"builds dataset"| node_dataset_build
node_dataset_cli -->|"packages data"| node_dataset_package
node_dataset_package -->|"writes package"| node_thunderdb
node_dataset_runtime -->|"reads package"| node_thunderdb
node_user -->|"manages protocols"| node_protocol_cli
node_protocol_cli -->|"loads definitions"| node_protocol_io
node_user -->|"renders CT data"| node_render_cli
node_render_cli -->|"starts rendering"| node_drr_render
node_drr_render -->|"uses subjects"| node_ct_subjects
node_mcp_client -->|"sends tool requests"| node_mcp_server
node_mcp_server -->|"registers tools"| node_mcp_inference
node_mcp_server -->|"registers tools"| node_mcp_protocol
node_mcp_inference -->|"runs segmentation"| node_segmenter
node_mcp_protocol -->|"inspects definitions"| node_protocol_io

click node_inference_cli "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/cli.py"
click node_runner "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/runner.py"
click node_preprocess "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/preprocessing.py"
click node_segmenter "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/segmenter.py"
click node_tta "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/tta.py"
click node_postprocess "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/postprocessing.py"
click node_artifacts "https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/artifacts.py"
click node_train_cli "https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/cli.py"
click node_readiness "https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/readiness.py"
click node_experiment "https://github.com/victorbutoi/flexray/blob/main/src/fxr/experiment/train.py"
click node_model "https://github.com/victorbutoi/flexray/blob/main/src/fxr/models/unet.py"
click node_augmentation "https://github.com/victorbutoi/flexray/blob/main/src/fxr/augmentation/pipeline.py"
click node_loss "https://github.com/victorbutoi/flexray/blob/main/src/fxr/losses/segmentation.py"
click node_dataset_cli "https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/cli.py"
click node_dataset_build "https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/builders.py"
click node_dataset_package "https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/packaging.py"
click node_dataset_runtime "https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/runtime.py"
click node_protocol_cli "https://github.com/victorbutoi/flexray/blob/main/src/fxr/protocols/cli.py"
click node_protocol_io "https://github.com/victorbutoi/flexray/blob/main/src/fxr/protocols/io.py"
click node_render_cli "https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/render_cli.py"
click node_drr_render "https://github.com/victorbutoi/flexray/blob/main/src/fxr/drr/rendering.py"
click node_ct_subjects "https://github.com/victorbutoi/flexray/blob/main/src/fxr/drr/subjects.py"
click node_mcp_server "https://github.com/victorbutoi/flexray/blob/main/src/fxr/mcp/server.py"
click node_mcp_inference "https://github.com/victorbutoi/flexray/blob/main/src/fxr/mcp/inference_tools.py"
click node_mcp_protocol "https://github.com/victorbutoi/flexray/blob/main/src/fxr/mcp/protocol_tools.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_inference_cli,node_runner,node_preprocess,node_segmenter,node_tta,node_postprocess,node_artifacts,node_user,node_mcp_client toneBlue
class node_train_cli,node_readiness,node_experiment,node_model,node_augmentation,node_loss toneAmber
class node_dataset_cli,node_dataset_build,node_dataset_package,node_dataset_runtime,node_thunderdb,node_protocol_cli,node_protocol_io toneMint
class node_render_cli,node_drr_render,node_ct_subjects toneRose
class node_mcp_server,node_mcp_inference,node_mcp_protocol,node_huggingface,node_output toneIndigo
```

## Components

### Inference

- [Inference CLI](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/cli.py): `src/fxr/inference/cli.py`
- [Inference runner](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/runner.py): `src/fxr/inference/runner.py`
- [Image preprocessing](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/preprocessing.py): `src/fxr/inference/preprocessing.py`
- [Model segmenter](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/segmenter.py): `src/fxr/inference/segmenter.py`
- [Test-time augmentation](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/tta.py): `src/fxr/inference/tta.py`
- [Prediction processing](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/postprocessing.py): `src/fxr/inference/postprocessing.py`
- [Prediction artifacts](https://github.com/victorbutoi/flexray/blob/main/src/fxr/inference/artifacts.py): `src/fxr/inference/artifacts.py`

### Training

- [Training launcher](https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/cli.py): `src/fxr/launch/cli.py`
- [Run validation](https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/readiness.py): `src/fxr/launch/readiness.py`
- [Training lifecycle](https://github.com/victorbutoi/flexray/blob/main/src/fxr/experiment/train.py): `src/fxr/experiment/train.py`
- [Segmentation model](https://github.com/victorbutoi/flexray/blob/main/src/fxr/models/unet.py): `src/fxr/models/unet.py`
- [Training augmentation](https://github.com/victorbutoi/flexray/blob/main/src/fxr/augmentation/pipeline.py): `src/fxr/augmentation/pipeline.py`
- [Segmentation losses](https://github.com/victorbutoi/flexray/blob/main/src/fxr/losses/segmentation.py): `src/fxr/losses/segmentation.py`

### Data and protocols

- [Dataset CLI](https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/cli.py): `src/fxr/datasets/cli.py`
- [Dataset preparation](https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/builders.py): `src/fxr/datasets/builders.py`
- [Dataset packaging](https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/packaging.py): `src/fxr/datasets/packaging.py`
- [Dataset runtime](https://github.com/victorbutoi/flexray/blob/main/src/fxr/datasets/runtime.py): `src/fxr/datasets/runtime.py`
- **ThunderDB packages**
- [Protocol CLI](https://github.com/victorbutoi/flexray/blob/main/src/fxr/protocols/cli.py): `src/fxr/protocols/cli.py`
- [Protocol definitions](https://github.com/victorbutoi/flexray/blob/main/src/fxr/protocols/io.py): `src/fxr/protocols/io.py`

### DRR rendering

- [DRR CLI](https://github.com/victorbutoi/flexray/blob/main/src/fxr/launch/render_cli.py): `src/fxr/launch/render_cli.py`
- [DRR rendering](https://github.com/victorbutoi/flexray/blob/main/src/fxr/drr/rendering.py): `src/fxr/drr/rendering.py`
- [CT subjects](https://github.com/victorbutoi/flexray/blob/main/src/fxr/drr/subjects.py): `src/fxr/drr/subjects.py`

### External access

- [MCP server](https://github.com/victorbutoi/flexray/blob/main/src/fxr/mcp/server.py): `src/fxr/mcp/server.py`
- [Inference tools](https://github.com/victorbutoi/flexray/blob/main/src/fxr/mcp/inference_tools.py): `src/fxr/mcp/inference_tools.py`
- [Protocol tools](https://github.com/victorbutoi/flexray/blob/main/src/fxr/mcp/protocol_tools.py): `src/fxr/mcp/protocol_tools.py`

### Other components

- **User**
- **Hugging Face**
- **AI client**
- **NumPy outputs**

## Connections

- User → Inference CLI: runs prediction
- Inference CLI → Inference runner: starts inference
- Inference runner → Image preprocessing: prepares image
- Inference runner → Model segmenter: runs model
- Inference runner → Test-time augmentation: applies TTA
- Inference runner → Prediction processing: processes prediction
- Inference runner → Prediction artifacts: writes results
- Model segmenter → Hugging Face: loads model bundle
- Prediction artifacts → NumPy outputs: saves arrays
- User → Training launcher: starts training
- Training launcher → Run validation: validates config
- Training launcher → Training lifecycle: runs experiment
- Training lifecycle → Segmentation model: trains model
- Training lifecycle → Training augmentation: augments batches
- Training lifecycle → Segmentation losses: computes loss
- User → Dataset CLI: prepares datasets
- Dataset CLI → Dataset preparation: builds dataset
- Dataset CLI → Dataset packaging: packages data
- Dataset packaging → ThunderDB packages: writes package
- Dataset runtime → ThunderDB packages: reads package
- User → Protocol CLI: manages protocols
- Protocol CLI → Protocol definitions: loads definitions
- User → DRR CLI: renders CT data
- DRR CLI → DRR rendering: starts rendering
- DRR rendering → CT subjects: uses subjects
- AI client → MCP server: sends tool requests
- MCP server → Inference tools: registers tools
- MCP server → Protocol tools: registers tools
- Inference tools → Model segmenter: runs segmentation
- Protocol tools → Protocol definitions: inspects definitions