# timdgn/mri_brain_tumor_detection architecture

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

- Interactive diagram: https://gitdiagram.com/timdgn/mri_brain_tumor_detection
- Repository: https://github.com/timdgn/mri_brain_tumor_detection

## Overview

##### Project type and purpose
- This is a full-stack machine-learning web application for brain MRI tumor classification.
- It ingests raw MRI images, cleans and preprocesses them, trains a convolutional neural network (EfficientNetV2B0), exposes an inference API via FastAPI, and provides a user interface via Streamlit.

##### File structure
Top-level directories and files:
- data/
– raw/ (original MRI images, split into Training/Testing, then by tumor category)
– processed/ (duplicates removed, borders cropped, same splits)
- src/
– data_cleaning.py (deduplication, border cropping)
– preprocessing.py (resizing, normalization, augmentation)
– training.py (model setup, callbacks, training loop)
– inference.py (wraps the trained model for prediction)
– fastapi_app.py (REST API endpoints for inference)
– streamlit_app.py (frontend UI)
– constants.py (shared config: paths, model params)
- models/ (saved model artifacts: .h5 weights and .json architecture)
- plots/ (visualizations: history, confusion, Grad-CAM, etc.)
- docs/ (static images for README)
- requirements.txt (dependencies)

##### README for additional insights
- Confirms use of transfer learning with EfficientNetV2B0.
- Details three user-facing steps in the UI: upload MRI, get prediction, display Grad-CAM.
- Specifies local launch commands: Uvicorn for backend, Streamlit for frontend.

##### Main components and their relationships
a. Data Layer
– Raw Data Store (data/raw/)
– Processed Data Store (data/processed/)
b. Preprocessing Service (src/data_cleaning.py + src/preprocessing.py)
– Reads raw images → cleans → outputs processed images
c. Training Pipeline (src/training.py)
– Consumes processed images → trains EfficientNetV2B0 → saves model to models/
d. Model Registry (models/)
– Versioned model artifacts (.h5, .json)
e. Inference Service (src/inference.py + src/fastapi_app.py)
– Loads model from registry → exposes /predict endpoint via FastAPI
f. Frontend UI (src/streamlit_app.py)
– Provides upload form → calls FastAPI → displays prediction and Grad-CAM overlay
g. Visualization / Reporting (plots/)
– Historical training metrics, confusion matrices, Grad-CAM outputs for end users or maintainers

##### Architectural patterns and design principles
- Layered separation: Data → Preprocessing → Training → Inference → Presentation
- Modular codebase: each major function in its own module
- Stateless REST API: inference is idempotent, no session state
- Reproducible model training: use of checkpoint callbacks, versioned artifacts
- Transfer Learning: reuse pretrained EfficientNetV2B0, fine-tuned on the domain dataset

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Source
    ExternalData["Kaggle Dataset"]:::external

    %% Offline Workflow
    subgraph "Offline Workflow"
        direction TB
        RawData["Raw Data Store\n(data/raw/)"]:::dataStore
        Cleaning["Cleaning Module\n(src/data_cleaning.py)"]:::compute
        Transform["Transformation Module\n(src/preprocessing.py)"]:::compute
        ProcData["Processed Data Store\n(data/processed/)"]:::dataStore
        Training["Training Pipeline\n(src/training.py)"]:::compute
        ModelReg["Model Registry\n(models/effnet_*.h5/.json)"]:::dataStore
    end

    %% Online Workflow
    subgraph "Online Workflow"
        direction TB
        User["End User (Browser)"]:::external
        UI["Streamlit UI\n(src/streamlit_app.py)"]:::ui
        API["FastAPI Service\n(src/fastapi_app.py)"]:::compute
        Wrapper["Model Wrapper\n(src/inference.py)"]:::compute
        Viz["Visualization Store\n(plots/)"]:::dataStore
    end

    %% Offline connections
    ExternalData -->|download| RawData
    RawData -->|clean| Cleaning
    Cleaning -->|output| ProcData
    ProcData -->|transform| Transform
    Transform -->|output| ProcData
    ProcData -->|train| Training
    Training -->|save model| ModelReg

    %% Online connections
    User -->|access| UI
    UI -->|POST /predict| API
    API -->|invoke| Wrapper
    Wrapper -->|load weights| ModelReg
    Wrapper -->|generate Grad-CAM| Viz
    Wrapper -->|return prediction & map| API
    API -->|response| UI
    UI -->|display| Viz

    %% Click Events
    click RawData "https://github.com/timdgn/mri_brain_tumor_detection/tree/main/data/raw/"
    click ProcData "https://github.com/timdgn/mri_brain_tumor_detection/tree/main/data/processed/"
    click Cleaning "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/src/data_cleaning.py"
    click Transform "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/src/preprocessing.py"
    click Training "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/src/training.py"
    click ModelReg "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/models/effnet_2024-06-08_01-19-59.h5"
    click Wrapper "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/src/inference.py"
    click API "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/src/fastapi_app.py"
    click UI "https://github.com/timdgn/mri_brain_tumor_detection/blob/main/src/streamlit_app.py"
    click Viz "https://github.com/timdgn/mri_brain_tumor_detection/tree/main/plots/"

    %% Styles
    classDef dataStore fill:#b3d9ff,stroke:#036,stroke-width:1px,shape:cylinder
    classDef compute fill:#ffd9b3,stroke:#c63,stroke-width:1px
    classDef ui fill:#d9ffb3,stroke:#393,stroke-width:1px,shape:roundrect
    classDef external fill:#eeeeee,stroke:#666,stroke-dasharray: 2 2,stroke-width:1px
```
