ARCHITECTURE.md

# Mosaic Architecture

This document describes the internal architecture and module organization of the Mosaic application.

## Overview

Mosaic is a deep learning pipeline for analyzing H&E whole slide images (WSIs) to predict:
1. **Cancer Subtypes** using the Aeon model
2. **Biomarkers** using the Paladin model

The application is organized into several focused modules with clear separation of concerns.

## Module Structure

The Mosaic application has been refactored for better readability and maintainability. The codebase is now organized into the following modules:

### Core Modules

#### `mosaic.gradio_app` (Main Entry Point)
- **Location**: `src/mosaic/gradio_app.py`
- **Purpose**: CLI entry point and command-line argument parsing
- **Responsibilities**:
  - Command-line argument parsing
  - Model downloading and initialization
  - Single slide and batch processing CLI modes
  - Launching the Gradio web UI

#### `mosaic.analysis`
- **Location**: `src/mosaic/analysis.py`
- **Purpose**: Core slide analysis logic
- **Responsibilities**:
  - Tissue segmentation
  - Feature extraction (CTransPath and Optimus)
  - Feature filtering with marker classifier
  - Aeon inference (cancer subtype prediction)
  - Paladin inference (biomarker prediction)
- **Key Function**: `analyze_slide()`

#### `mosaic.ui` Package
- **Location**: `src/mosaic/ui/`
- **Purpose**: Gradio web interface components
- **Submodules**:
  
  - **`ui.__init__.py`**: Exports the main `launch_gradio` function
  
  - **`ui.app`**: Gradio interface definition
    - UI layout and component definitions
    - Event handlers for user interactions
    - Multi-slide analysis workflow
    - Key Functions: `launch_gradio()`, `analyze_slides()`, `set_cancer_subtype_maps()`
  
  - **`ui.utils`**: UI utility functions
    - Settings validation
    - CSV file handling
    - OncoTree API integration
    - User session directory management
    - Key Functions: `validate_settings()`, `load_settings()`, `get_oncotree_code_name()`, `create_user_directory()`

### Inference Modules

#### `mosaic.inference`
- **Location**: `src/mosaic/inference/`
- **Purpose**: ML model inference implementations
- **Submodules**:
  - `aeon.py`: Cancer subtype inference
  - `paladin.py`: Biomarker inference
  - `data.py`: Data structures and utilities

## Code Organization Benefits

1. **Separation of Concerns**: UI, analysis, and CLI logic are now clearly separated
2. **Improved Maintainability**: Each module has a single, well-defined responsibility
3. **Better Testability**: Individual modules can be tested independently
4. **Enhanced Readability**: Reduced file sizes and clear module boundaries
5. **Reusability**: Analysis functions can be imported and used without UI dependencies

## Import Flow

```
gradio_app.main()
├── download_and_process_models()
│   ├── set_cancer_subtype_maps() [from ui.app]
│   └── get_oncotree_code_name() [from ui.utils]
├── analyze_slide() [from analysis]
│   ├── segment_tissue() [from mussel]
│   ├── get_features() [from mussel]
│   ├── filter_features() [from mussel]
│   ├── run_aeon() [from inference]
│   └── run_paladin() [from inference]
└── launch_gradio() [from ui]
    ├── analyze_slides() [from ui.app]
    │   └── analyze_slide() [from analysis]
    └── validate_settings() [from ui.utils]
```

## File Size Comparison

File | Original | Refactored | Change
-----|----------|------------|--------
`gradio_app.py` | 843 lines | 230 lines | -73%
UI Components | - | 474 lines | +474
Analysis Logic | - | 200 lines | +200

The refactoring distributed the original monolithic file into focused, maintainable modules while maintaining all functionality.

## Key Dependencies

### External Libraries

- **Gradio**: Web interface framework for creating the UI
- **PyTorch**: Deep learning framework for model inference
- **Pandas**: Data manipulation and CSV handling
- **Mussel**: Pathology-specific utilities for:
  - Tissue segmentation
  - Feature extraction (CTransPath, Optimus)
  - Marker classification
- **Paladin**: Biomarker prediction models
- **HuggingFace Hub**: Model downloading and management
- **Loguru**: Logging with enhanced features

### Model Components

1. **CTransPath**: Pre-trained vision transformer for histopathology feature extraction
2. **Optimus**: Foundation model for pathology image features
3. **Marker Classifier**: Filters features to tumor-relevant regions
4. **Aeon**: Multi-task model for cancer subtype classification
5. **Paladin**: Suite of models for biomarker prediction across cancer subtypes

## Data Flow

```
WSI File (*.svs, *.tif)
    ↓
Tissue Segmentation (Mussel)
    ↓
CTransPath Feature Extraction
    ↓
Marker Classification (filter to tumor regions)
    ↓
Optimus Feature Extraction (on filtered tiles)
    ↓
├── Aeon Inference → Cancer Subtype Predictions
│       ↓
└── Paladin Inference → Biomarker Predictions
        ↓
    Results (CSV, Visualizations)
```

## Design Principles

1. **Modularity**: Each component has a single, well-defined responsibility
2. **Testability**: Modules can be tested independently with mocking
3. **Reusability**: Core analysis functions can be used without UI
4. **Maintainability**: Clear interfaces and documentation
5. **Extensibility**: New models or features can be added with minimal changes

## Future Enhancements

Potential areas for extension:

- Support for additional image formats
- Real-time analysis progress tracking
- Integration with PACS systems
- Support for additional biomarkers
- Batch processing optimization
- Cloud deployment configurations