# tishansathruwan/maldam architecture

> Architecture diagram of the GitHub repository tishansathruwan/maldam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tishansathruwan/maldam
- Repository: https://github.com/tishansathruwan/maldam

## Overview

MaLDAM is a YOLOv5-based malaria detector trained for HCM-to-LCM transfer. Its main workflow pairs HCM and LCM views, adapts the HCM view with microscopy augmentations, and jointly trains detection and VICReg-based global/masked-local alignment; validation evaluates cross-domain detection. The graph preserves major training, evaluation, logging, and model-support modules. Some links reflect README descriptions or SOURCE INDEX references; unsampled implementations and their internal call paths are not asserted.

Main entry points: [`src/contrastive_trainer.py`](https://github.com/tishansathruwan/maldam/blob/main/src/contrastive_trainer.py) (Training orchestrator), [`src/utils/dataloaders_contrastive.py`](https://github.com/tishansathruwan/maldam/blob/main/src/utils/dataloaders_contrastive.py) (Paired HCM/LCM loader), [`src/utils/val.py`](https://github.com/tishansathruwan/maldam/blob/main/src/utils/val.py) (Validation and benchmarking), [`src/utils/vicregl/loss.py`](https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/loss.py) (VICRegL alignment loss)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Paired Data"]
  node_paired["Paired HCM/LCM loader"]
  node_standard_data["Detection data loader<br/>[dataloaders.py]"]
  node_augment["Microscopy augmentation<br/>[augmentations.py]"]
end

subgraph group_training["Joint Training"]
  node_config["Run configuration<br/>[config.py]"]
  node_trainer["Training orchestrator"]
  node_detection_loss["Detection loss<br/>[loss.py]"]
  node_vic_head["VICRegL projection head<br/>[model.py]"]
  node_vic_loss["VICRegL alignment loss<br/>[loss.py]"]
  node_vic_match["Local feature matching<br/>[utils.py]"]
  node_feature_match["Feature matching primitives"]
  node_device["Device and training utilities<br/>[torch_utils.py]"]
  node_general["Shared training utilities<br/>[general.py]"]
end

subgraph group_model["Detection Model"]
  node_detector["YOLO detector<br/>[yolo.py]"]
  node_layers["Neural network layers<br/>[common.py]"]
  node_experimental["Model loading and ensembles<br/>[experimental.py]"]
  node_anchor["Anchor tuning<br/>[autoanchor.py]"]
end

subgraph group_evaluation["Evaluation and Reporting"]
  node_validate["Validation and benchmarking<br/>[val.py]"]
  node_metrics["Detection metrics<br/>[metrics.py]"]
  node_plots["Plots and visualizations<br/>[plots.py]"]
  node_callbacks["Training callbacks<br/>[callbacks.py]"]
  node_logging["Experiment logging<br/>[__init__.py]"]
  node_outputs["Checkpoints and results"]
end

node_operator(("Training operator"))

node_operator -->|"starts"| node_trainer
node_trainer -->|"loads config"| node_config
node_trainer -->|"loads paired views"| node_paired
node_paired -->|"uses loader"| node_standard_data
node_paired -->|"applies transforms"| node_augment
node_trainer -->|"trains model"| node_detector
node_detector -->|"builds from"| node_layers
node_trainer -->|"computes loss"| node_detection_loss
node_trainer -->|"creates head"| node_vic_head
node_trainer -->|"computes alignment"| node_vic_loss
node_vic_loss -->|"uses matching"| node_vic_match
node_trainer -.->|"uses primitives"| node_feature_match
node_trainer -->|"checks anchors"| node_anchor
node_trainer -->|"uses device utilities"| node_device
node_trainer -->|"uses shared utilities"| node_general
node_trainer -->|"runs validation"| node_validate
node_validate -->|"computes metrics"| node_metrics
node_validate -->|"produces plots"| node_plots
node_trainer -->|"dispatches hooks"| node_callbacks
node_trainer -.->|"reports run"| node_logging
node_trainer -->|"loads checkpoints"| node_experimental
node_trainer -->|"saves checkpoints"| node_outputs

click node_config "https://github.com/tishansathruwan/maldam/blob/main/src/config.py"
click node_trainer "https://github.com/tishansathruwan/maldam/blob/main/src/contrastive_trainer.py"
click node_paired "https://github.com/tishansathruwan/maldam/blob/main/src/utils/dataloaders_contrastive.py"
click node_standard_data "https://github.com/tishansathruwan/maldam/blob/main/src/utils/dataloaders.py"
click node_augment "https://github.com/tishansathruwan/maldam/blob/main/src/utils/augmentations.py"
click node_detector "https://github.com/tishansathruwan/maldam/blob/main/src/models/yolo.py"
click node_layers "https://github.com/tishansathruwan/maldam/blob/main/src/models/common.py"
click node_experimental "https://github.com/tishansathruwan/maldam/blob/main/src/models/experimental.py"
click node_detection_loss "https://github.com/tishansathruwan/maldam/blob/main/src/utils/loss.py"
click node_vic_head "https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/model.py"
click node_vic_loss "https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/loss.py"
click node_vic_match "https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/utils.py"
click node_feature_match "https://github.com/tishansathruwan/maldam/blob/main/src/utils/feature_matching.py"
click node_anchor "https://github.com/tishansathruwan/maldam/blob/main/src/utils/autoanchor.py"
click node_device "https://github.com/tishansathruwan/maldam/blob/main/src/utils/torch_utils.py"
click node_general "https://github.com/tishansathruwan/maldam/blob/main/src/utils/general.py"
click node_validate "https://github.com/tishansathruwan/maldam/blob/main/src/utils/val.py"
click node_metrics "https://github.com/tishansathruwan/maldam/blob/main/src/utils/metrics.py"
click node_plots "https://github.com/tishansathruwan/maldam/blob/main/src/utils/plots.py"
click node_callbacks "https://github.com/tishansathruwan/maldam/blob/main/src/utils/callbacks.py"
click node_logging "https://github.com/tishansathruwan/maldam/blob/main/src/utils/loggers/__init__.py"
click node_outputs "https://github.com/tishansathruwan/maldam/blob/main/src/contrastive_trainer.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_paired,node_standard_data,node_augment toneBlue
class node_config,node_trainer,node_detection_loss,node_vic_head,node_vic_loss,node_vic_match,node_feature_match,node_device,node_general toneAmber
class node_detector,node_layers,node_experimental,node_anchor toneMint
class node_validate,node_metrics,node_plots,node_callbacks,node_logging,node_outputs toneRose
class node_operator toneIndigo
```

## Components

### Paired Data

- [Paired HCM/LCM loader](https://github.com/tishansathruwan/maldam/blob/main/src/utils/dataloaders_contrastive.py): `src/utils/dataloaders_contrastive.py`
- [Detection data loader](https://github.com/tishansathruwan/maldam/blob/main/src/utils/dataloaders.py): `src/utils/dataloaders.py`
- [Microscopy augmentation](https://github.com/tishansathruwan/maldam/blob/main/src/utils/augmentations.py): `src/utils/augmentations.py`

### Joint Training

- [Run configuration](https://github.com/tishansathruwan/maldam/blob/main/src/config.py): `src/config.py`
- [Training orchestrator](https://github.com/tishansathruwan/maldam/blob/main/src/contrastive_trainer.py): `src/contrastive_trainer.py`
- [Detection loss](https://github.com/tishansathruwan/maldam/blob/main/src/utils/loss.py): `src/utils/loss.py`
- [VICRegL projection head](https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/model.py): `src/utils/vicregl/model.py`
- [VICRegL alignment loss](https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/loss.py): `src/utils/vicregl/loss.py`
- [Local feature matching](https://github.com/tishansathruwan/maldam/blob/main/src/utils/vicregl/utils.py): `src/utils/vicregl/utils.py`
- [Feature matching primitives](https://github.com/tishansathruwan/maldam/blob/main/src/utils/feature_matching.py): `src/utils/feature_matching.py`
- [Device and training utilities](https://github.com/tishansathruwan/maldam/blob/main/src/utils/torch_utils.py): `src/utils/torch_utils.py`
- [Shared training utilities](https://github.com/tishansathruwan/maldam/blob/main/src/utils/general.py): `src/utils/general.py`

### Detection Model

- [YOLO detector](https://github.com/tishansathruwan/maldam/blob/main/src/models/yolo.py): `src/models/yolo.py`
- [Neural network layers](https://github.com/tishansathruwan/maldam/blob/main/src/models/common.py): `src/models/common.py`
- [Model loading and ensembles](https://github.com/tishansathruwan/maldam/blob/main/src/models/experimental.py): `src/models/experimental.py`
- [Anchor tuning](https://github.com/tishansathruwan/maldam/blob/main/src/utils/autoanchor.py): `src/utils/autoanchor.py`

### Evaluation and Reporting

- [Validation and benchmarking](https://github.com/tishansathruwan/maldam/blob/main/src/utils/val.py): `src/utils/val.py`
- [Detection metrics](https://github.com/tishansathruwan/maldam/blob/main/src/utils/metrics.py): `src/utils/metrics.py`
- [Plots and visualizations](https://github.com/tishansathruwan/maldam/blob/main/src/utils/plots.py): `src/utils/plots.py`
- [Training callbacks](https://github.com/tishansathruwan/maldam/blob/main/src/utils/callbacks.py): `src/utils/callbacks.py`
- [Experiment logging](https://github.com/tishansathruwan/maldam/blob/main/src/utils/loggers/__init__.py): `src/utils/loggers/__init__.py`
- [Checkpoints and results](https://github.com/tishansathruwan/maldam/blob/main/src/contrastive_trainer.py): `src/contrastive_trainer.py`

### Other components

- **Training operator**

## Connections

- Training operator → Training orchestrator: starts
- Training orchestrator → Run configuration: loads config (evidence: `main.py`)
- Training orchestrator → Paired HCM/LCM loader: loads paired views (evidence: `src/contrastive_trainer.py`)
- Paired HCM/LCM loader → Detection data loader: uses loader (evidence: `src/utils/dataloaders_contrastive.py`)
- Paired HCM/LCM loader → Microscopy augmentation: applies transforms (evidence: `src/utils/dataloaders_contrastive.py`)
- Training orchestrator → YOLO detector: trains model (evidence: `src/contrastive_trainer.py`)
- YOLO detector → Neural network layers: builds from (evidence: `src/models/yolo.py`)
- Training orchestrator → Detection loss: computes loss (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → VICRegL projection head: creates head (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → VICRegL alignment loss: computes alignment (evidence: `src/contrastive_trainer.py`)
- VICRegL alignment loss → Local feature matching: uses matching (evidence: `src/utils/vicregl/loss.py`)
- Training orchestrator → Feature matching primitives: uses primitives
- Training orchestrator → Anchor tuning: checks anchors (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → Device and training utilities: uses device utilities (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → Shared training utilities: uses shared utilities (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → Validation and benchmarking: runs validation (evidence: `src/contrastive_trainer.py`)
- Validation and benchmarking → Detection metrics: computes metrics (evidence: `src/utils/val.py`)
- Validation and benchmarking → Plots and visualizations: produces plots (evidence: `src/utils/val.py`)
- Training orchestrator → Training callbacks: dispatches hooks (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → Experiment logging: reports run (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → Model loading and ensembles: loads checkpoints (evidence: `src/contrastive_trainer.py`)
- Training orchestrator → Checkpoints and results: saves checkpoints (evidence: `src/contrastive_trainer.py`)
