# raidionics/aeropath architecture

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

- Interactive diagram: https://gitdiagram.com/raidionics/aeropath
- Repository: https://github.com/raidionics/aeropath

## Overview

##### Project type and purpose
- This is a Python-based ML web demo (“AeroPath”) for automatic airway segmentation.
- It bundles a Gradio frontend (demo/app.py) with a Raidionics deep-learning backend, containerized via Docker, and can fetch the AeroPath dataset from the Hugging Face Hub or Zenodo.

##### File structure
- Top-level:
- Dockerfile, .dockerignore → container build
- README.md, LICENSE.md → project description, license
- setup.cfg → code formatting/linters
- .github/workflows → CI/CD pipelines (deploy, filesize check, linting)
- demo/:
- app.py → Gradio app entry point
- requirements.txt → Python dependencies (Gradio, Raidionics, nibabel, etc.)
- src/
– gui.py → UI layout and event handlers
– inference.py → calls segmentation model, orchestrates input/output
– convert.py → data format conversions (e.g., NIfTI to arrays)
– css_style.py → custom CSS for UI
– utils.py → shared helper functions
– logger.py → logging abstraction
- notebooks/: example notebooks for dataset loading and exploration
- shell/: lint/format scripts

##### README for additional insights
- Confirms use of Gradio for frontend, Raidionics for segmentation, Hugging Face Datasets for data access.
- Provides Docker and local-Python launch commands.
- Mentions CI/CD status badges linking to GitHub Actions.

a. Main components
- User (Web Browser)
- Gradio Web UI (demo/app.py + gui.py + css_style.py)
- Application Logic Layer (demo/src/inference.py, utils.py, convert.py)
- Raidionics Backend (external Python library implementing segmentation)
- Data Source (Hugging Face Hub / Zenodo)
- Logging Module (demo/src/logger.py)
- Containerization & Env (Docker container or local venv)
- CI/CD (GitHub Actions workflows)

b. Relationships & data flow
1. User submits a CT scan via the Gradio interface
2. UI layer passes the input to inference.py
3. inference.py invokes:
– convert.py to transform file formats if needed
– Raidionics library to run the segmentation model
– utils.py for post-processing (e.g., thresholding)
4. Segmentation results return to UI for display
5. logger.py captures events/errors throughout steps
6. If a new dataset is requested, the app fetches it from the Hugging Face Hub
7. Entire app runs inside a Docker container (or Python venv)
8. CI/CD pipelines build, test, lint, and deploy the container to Hugging Face Spaces

c. Architectural patterns & design principles
- Modular monolith: clear separation of UI, business logic, and utilities
- MVC-like: gui.py = View, inference.py = Controller, convert/utils = Model
- Containerization for environment consistency
- CI/CD for automated testing, linting, size checks, and deployment

d. Key technologies/frameworks
- Python 3.x
- Gradio (frontend)
- Raidionics (segmentation backend)
- nibabel or similar (NIfTI handling)
- Hugging Face Datasets (data loading)
- Docker
- GitHub Actions (CI/CD)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User (Web Browser)"]:::external

    subgraph "Docker Container / Python venv" 
        direction TB
        subgraph "Frontend Layer (Gradio UI)"
            direction TB
            App["app.py"]:::ui
            GUI["gui.py"]:::ui
            CSS["css_style.py"]:::ui
        end
        subgraph "Core Logic Layer"
            direction TB
            Inference["inference.py"]:::core
            Convert["convert.py"]:::core
            Utils["utils.py"]:::core
        end
        Logger["logger.py"]:::core
        Dockerfile["Dockerfile"]:::infra
        DOIGNORE[".dockerignore"]:::infra
        Req["requirements.txt"]:::infra
    end

    HF["Hugging Face Hub"]:::external
    Zenodo["Zenodo"]:::external
    Raidionics["Raidionics Library"]:::external
    CI["CI/CD Pipelines"]:::infra
    README["README.md"]:::infra
    LICENSE["LICENSE.md"]:::infra
    Setup["setup.cfg"]:::infra
    Notebooks["aeropath-load-dataset-example.ipynb"]:::infra
    ShellLint["lint.sh"]:::infra
    ShellFmt["format.sh"]:::infra

    User -->|"Upload CT Scan"| App
    App -->|"render UI"| GUI
    App -->|"apply CSS"| CSS
    App -->|"submit data"| Inference
    GUI -->|"UI events"| Inference
    Inference -->|"format conversion"| Convert
    Inference -->|"post-process"| Utils
    Inference -->|"segmentation call"| Raidionics
    Inference -->|"log events"| Logger
    Inference -->|"fetch dataset"| HF
    HF ==>|"alternatively"| Zenodo
    Inference -->|"return results"| App

    CI -.->|"watches"| README
    CI -.->|"watches"| LICENSE
    CI -.->|"watches"| Setup
    CI -.->|"runs"| ShellLint
    CI -.->|"runs"| ShellFmt
    CI -.->|"checks"| Req
    CI -.->|"builds image"| Dockerfile
    CI -.->|"builds image"| DOIGNORE

    Notebooks -.->|"example load"| HF

    click App "https://github.com/raidionics/aeropath/blob/main/demo/app.py"
    click GUI "https://github.com/raidionics/aeropath/blob/main/demo/src/gui.py"
    click CSS "https://github.com/raidionics/aeropath/blob/main/demo/src/css_style.py"
    click Inference "https://github.com/raidionics/aeropath/blob/main/demo/src/inference.py"
    click Convert "https://github.com/raidionics/aeropath/blob/main/demo/src/convert.py"
    click Utils "https://github.com/raidionics/aeropath/blob/main/demo/src/utils.py"
    click Logger "https://github.com/raidionics/aeropath/blob/main/demo/src/logger.py"
    click Dockerfile "https://github.com/raidionics/aeropath/tree/main/Dockerfile"
    click DOIGNORE "https://github.com/raidionics/aeropath/blob/main/.dockerignore"
    click Req "https://github.com/raidionics/aeropath/blob/main/demo/requirements.txt"
    click README "https://github.com/raidionics/aeropath/blob/main/README.md"
    click LICENSE "https://github.com/raidionics/aeropath/blob/main/LICENSE.md"
    click Setup "https://github.com/raidionics/aeropath/blob/main/setup.cfg"
    click Notebooks "https://github.com/raidionics/aeropath/blob/main/notebooks/aeropath-load-dataset-example.ipynb"
    click ShellLint "https://github.com/raidionics/aeropath/blob/main/shell/lint.sh"
    click ShellFmt "https://github.com/raidionics/aeropath/blob/main/shell/format.sh"

    classDef ui fill:#D0E6FF,stroke:#1E70BF,stroke-width:2px
    classDef core fill:#DFFFD0,stroke:#5A9A00,stroke-width:2px
    classDef external fill:#FFE4B3,stroke:#D27E00,stroke-width:2px
    classDef infra fill:#E0E0E0,stroke:#808080,stroke-width:2px
```
