# minimert989/immunova architecture

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

- Interactive diagram: https://gitdiagram.com/minimert989/immunova
- Repository: https://github.com/minimert989/immunova

## Overview

##### Project Type and Purpose
- This is a full-stack machine-learning platform that bundles multiple ML pipelines (TIL image classification, GNN for drug optimization, survival analysis, multimodal treatment-response fusion) plus data preprocessing and validation, and exposes inference endpoints via a FastAPI backend with a simple static frontend.

##### File Structure
- Top‐level:
- api.py       → FastAPI application
- model.py     → shared model utilities
- requirements.txt
- deployment/  → Azure deployment configuration
- frontend/    → Static HTML/CSS/JS user interface
- ML modules (each folder is effectively its own service/component):
- preprocessing/          → WSIProcessor for whole-slide image preprocessing
- til_classification/     → TIL classifier (train.py, model.py, grad_cam.py)
- drug_optimization/      → GNN model and RL optimizer
- survival_analysis/      → Kaplan-Meier and survival transformer
- treatment_response/     → Fusion of imaging + genomics + other modalities
- validation/             → Clinical and external‐dataset validation scripts
- Data landing: /datasets/ (TIL images, graphs, CSVs, multimodal assets)

##### Extract Insights from the README
- Describes dataset layout per pipeline
- Commands to train each model in its own directory
- Inference example and FastAPI deployment instructions
- Technology stack: Python, PyTorch, Torch-Geometric, Lifelines, FastAPI, Uvicorn, Azure

a. Main Components:
- Data Store (datasets/ on disk or blob storage)
- Preprocessing Service (WSIProcessor)
- Training Services (six distinct pipelines)
- Validation Services (clinical & external loaders + validators)
- Model Registry / Artifact Storage (torch .pth files)
- FastAPI Inference Layer (api.py)
- Frontend UI (index.html + script.js + styles.css)
- Deployment & Infrastructure (Azure config)
- External Clients (browsers, other services)
b. Interactions & Data Flow:
1. Raw data lands in Data Store
2. Preprocessing Service reads images → outputs processed data
3. Each Training Service consumes processed data → writes model artifacts
4. Validation Services read both data & artifacts → produce reports/metrics
5. FastAPI loads latest artifacts at startup or on-demand
6. Frontend or API clients send HTTP requests → FastAPI serves inference
7. Deployment layer packages all components into Azure containers
c. Architectural Patterns & Principles:
- Modular/“micro-pipeline” decomposition: each ML task is self-contained
- Clear separation of concerns: Data → Preprocessing → Training → Validation → Inference → UI
- Thin API layer for inference, with static frontend decoupled from backend
- Infrastructure as code for reproducible deployments (azure_deploy_config.yaml)
d. Key Technologies & Libraries:
- Python + PyTorch (core ML)
- Torch-Geometric (GNN)
- Lifelines (survival analysis)
- FastAPI + Uvicorn (API server)
- Azure (cloud deployment)
- Standard web stack for frontend (HTML/CSS/JS)

##### Final Recommendations
- Artifact paths: show where .pth or .pt files are stored and loaded
- Don’t overcomplicate: aim for clarity—one flow from data ingestion to end-user inference
- Keep deployment separate: show Azure config and containerization as an outer boundary around backend and frontend
- Review with stakeholders: ensure data compliance/regulatory flows (e.g., clinical validation) are clearly called out

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Tier
    subgraph "Data Tier"
        DS["Data Store\n(datasets/)"]:::data
    end

    %% ML Tier
    subgraph "ML Tier"
        PRE["Preprocessing Service\n(WSIProcessor)"]:::ml
        TILTrain["TIL Train Service\n(train.py)"]:::ml
        TILModel["TIL Model\n(model.py)"]:::ml
        TILGradCam["TIL Grad-CAM\n(grad_cam.py)"]:::ml
        DrugGNN["Drug Optimization\n(gnn_model.py)"]:::ml
        DrugRL["RL Optimizer\n(rl_optimizer.py)"]:::ml
        SurvivalKM["Kaplan-Meier\n(km_validation.py)"]:::ml
        SurvivalTrans["Survival Transformer\n(survival_transformer.py)"]:::ml
        Fusion["Treatment Fusion\n(fusion_model.py)"]:::ml
        Genomics["Genomics Model\n(genomics_model.py)"]:::ml
        Imaging["Imaging Model\n(imaging_model.py)"]:::ml
        ClinVal["Clinical Validation\n(clinical_validation.py)"]:::ml
        ExtVal["External Dataset Loader\n(external_datasets_loader.py)"]:::ml
        MR["Model Registry\n(.pth artifacts)"]:::ml
    end

    %% Service Tier
    subgraph "Service Tier"
        FastAPI_API["FastAPI Service\n(api.py)"]:::api
        FastAPI_Model["Shared Model Utils\n(model.py)"]:::api
    end

    %% Presentation Tier
    subgraph "Presentation Tier"
        UI["Frontend UI"]:::frontend
        IDX["index.html"]:::frontend
        SCR["script.js"]:::frontend
        STY["styles.css"]:::frontend
    end

    %% Deployment Tier
    subgraph "Deployment Tier"
        AZ["Azure Deployment Config\ndeployment/azure_deploy_config.yaml"]:::infra
    end

    %% External Clients
    Client["External Clients\n(browsers, services)"]:::external

    %% Connections
    DS -->|"raw data"| PRE
    PRE -->|"processed data"| TILTrain
    PRE -->|"processed data"| DrugGNN
    PRE -->|"processed data"| SurvivalKM
    PRE -->|"processed data"| Fusion
    TILTrain --> TILModel
    TILModel --> TILGradCam
    TILModel --> MR
    DrugGNN --> DrugRL
    DrugRL --> MR
    SurvivalKM --> SurvivalTrans
    SurvivalTrans --> MR
    Fusion --> Genomics
    Fusion --> Imaging
    Genomics --> MR
    Imaging --> MR
    ClinVal -->|"reads data & artifacts"| DS
    ClinVal --> MR
    ExtVal -->|"reads data & artifacts"| DS
    ExtVal --> MR
    MR --> FastAPI_API
    FastAPI_API --> FastAPI_Model
    Client -->|"HTTP request/response"| FastAPI_API
    UI -->|"API calls"| FastAPI_API
    UI --> IDX
    UI --> SCR
    UI --> STY
    AZ --> FastAPI_API
    AZ --> UI

    %% Click Events
    click PRE "https://github.com/minimert989/immunova/blob/main/preprocessing/TILs/WSIProcessor.py"
    click TILTrain "https://github.com/minimert989/immunova/blob/main/til_classification/train.py"
    click TILModel "https://github.com/minimert989/immunova/blob/main/til_classification/model.py"
    click TILGradCam "https://github.com/minimert989/immunova/blob/main/til_classification/grad_cam.py"
    click DrugGNN "https://github.com/minimert989/immunova/blob/main/drug_optimization/gnn_model.py"
    click DrugRL "https://github.com/minimert989/immunova/blob/main/drug_optimization/rl_optimizer.py"
    click SurvivalKM "https://github.com/minimert989/immunova/blob/main/survival_analysis/km_validation.py"
    click SurvivalTrans "https://github.com/minimert989/immunova/blob/main/survival_analysis/survival_transformer.py"
    click Fusion "https://github.com/minimert989/immunova/blob/main/treatment_response/fusion_model.py"
    click Genomics "https://github.com/minimert989/immunova/blob/main/treatment_response/genomics_model.py"
    click Imaging "https://github.com/minimert989/immunova/blob/main/treatment_response/imaging_model.py"
    click ClinVal "https://github.com/minimert989/immunova/blob/main/validation/clinical_validation.py"
    click ExtVal "https://github.com/minimert989/immunova/blob/main/validation/external_datasets_loader.py"
    click FastAPI_API "https://github.com/minimert989/immunova/blob/main/api.py"
    click FastAPI_Model "https://github.com/minimert989/immunova/blob/main/model.py"
    click IDX "https://github.com/minimert989/immunova/blob/main/frontend/index.html"
    click SCR "https://github.com/minimert989/immunova/blob/main/frontend/script.js"
    click STY "https://github.com/minimert989/immunova/blob/main/frontend/styles.css"
    click AZ "https://github.com/minimert989/immunova/blob/main/deployment/azure_deploy_config.yaml"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#333,stroke-width:1px;
    classDef ml fill:#D0F2D8,stroke:#333,stroke-width:1px;
    classDef api fill:#E5D3FF,stroke:#333,stroke-width:1px;
    classDef frontend fill:#FFE2B3,stroke:#333,stroke-width:1px;
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px;
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5;
```
