# piyushnile1509/sickle-detection architecture

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

- Interactive diagram: https://gitdiagram.com/piyushnile1509/sickle-detection
- Repository: https://github.com/piyushnile1509/sickle-detection

## Overview

This is an experimental sickle-cell image-classification and cell-counting research project, explicitly not a diagnostic device. The documented workflow prepares a primary dataset, prevents duplicate leakage in splits, trains and evaluates field classifiers, then exposes image predictions and Grad-CAM through CLI and Streamlit. Cell counting is a separate capability with a trained cell detector and a Cellpose shape-heuristic alternative. Some workflow links are documented rather than visible in sampled source; those are marked dashed.

Main entry points: [`src/inference.py`](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/inference.py) (Field inference), [`app.py`](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/app.py) (Streamlit demo), [`src/training/loop.py`](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/training/loop.py) (Training loop), [`src/detector_counting.py`](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/detector_counting.py) (YOLO cell counting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset preparation"]
  node_primary_data["Primary images"]
  node_manifest["Label manifest<br/>[manifest.py]"]
  node_duplicate_groups["Duplicate grouping<br/>[duplicates.py]"]
  node_splits["Leakage-safe splits<br/>[splitting.py]"]
  node_dataset_loader["Dataset transforms<br/>[dataset.py]"]
  node_class_weights["Class weighting<br/>[imbalance.py]"]
end

subgraph group_training["Classifier training"]
  node_training_models["Model factory<br/>[models.py]"]
  node_training_loop["Training loop<br/>[loop.py]"]
  node_checkpoint["Model checkpoint"]
end

subgraph group_inference["Inference and evaluation"]
  node_classifier_eval["Classifier evaluation"]
  node_inference_core["Field inference<br/>[inference.py]"]
  node_predict_cli["Prediction CLI<br/>[predict.py]"]
  node_streamlit_demo["Streamlit demo<br/>[app.py]"]
end

subgraph group_counting["Cell counting"]
  node_detector_cli["Detector CLI<br/>[count_cells.py]"]
  node_detector_counting["YOLO cell counting"]
  node_cellpose_counting["Cellpose heuristic<br/>[counting.py]"]
  node_detector_weights["Detector weights"]
end

node_researcher(("Researcher / user"))

node_researcher -.->|"provides images"| node_primary_data
node_primary_data -.->|"builds labels"| node_manifest
node_manifest -.->|"groups duplicates"| node_duplicate_groups
node_duplicate_groups -.->|"informs groups"| node_splits
node_splits -.->|"selects samples"| node_dataset_loader
node_dataset_loader -.->|"provides batches"| node_training_loop
node_class_weights -.->|"weights loss"| node_training_loop
node_training_loop -->|"sets training stage"| node_training_models
node_training_loop -.->|"saves model"| node_checkpoint
node_training_models -->|"builds model"| node_inference_core
node_checkpoint -->|"loads weights"| node_inference_core
node_researcher -.->|"requests prediction"| node_predict_cli
node_predict_cli -->|"runs inference"| node_inference_core
node_researcher -.->|"uploads image"| node_streamlit_demo
node_streamlit_demo -.->|"predicts field"| node_inference_core
node_inference_core -->|"supplies predictions"| node_classifier_eval
node_researcher -.->|"requests counts"| node_detector_cli
node_detector_cli -->|"runs detector"| node_detector_counting
node_detector_counting -.->|"loads weights"| node_detector_weights
node_streamlit_demo -.->|"offers detector mode"| node_detector_counting
node_streamlit_demo -.->|"offers fallback mode"| node_cellpose_counting

click node_primary_data "https://github.com/piyushnile1509/sickle-detection/tree/claude/sickle-cell-cnn-research-g6fipc/data/train_source"
click node_manifest "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/manifest.py"
click node_duplicate_groups "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/duplicates.py"
click node_splits "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/splitting.py"
click node_dataset_loader "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/dataset.py"
click node_class_weights "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/imbalance.py"
click node_training_models "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/training/models.py"
click node_training_loop "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/training/loop.py"
click node_checkpoint "https://github.com/piyushnile1509/sickle-detection/tree/claude/sickle-cell-cnn-research-g6fipc/models"
click node_classifier_eval "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/scripts/evaluate_classifier.py"
click node_inference_core "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/inference.py"
click node_predict_cli "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/scripts/predict.py"
click node_streamlit_demo "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/app.py"
click node_detector_cli "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/scripts/count_cells.py"
click node_detector_counting "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/detector_counting.py"
click node_cellpose_counting "https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/counting.py"
click node_detector_weights "https://github.com/piyushnile1509/sickle-detection/tree/claude/sickle-cell-cnn-research-g6fipc/models/sickle5k_detector/weights"

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_primary_data,node_manifest,node_duplicate_groups,node_splits,node_dataset_loader,node_class_weights,node_researcher toneBlue
class node_training_models,node_training_loop,node_checkpoint toneAmber
class node_classifier_eval,node_inference_core,node_predict_cli,node_streamlit_demo toneMint
class node_detector_cli,node_detector_counting,node_cellpose_counting,node_detector_weights toneRose
```

## Components

### Dataset preparation

- [Primary images](https://github.com/piyushnile1509/sickle-detection/tree/claude/sickle-cell-cnn-research-g6fipc/data/train_source): `data/train_source`
- [Label manifest](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/manifest.py): `src/data/manifest.py`
- [Duplicate grouping](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/duplicates.py): `src/data/duplicates.py`
- [Leakage-safe splits](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/splitting.py): `src/data/splitting.py`
- [Dataset transforms](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/dataset.py): `src/data/dataset.py`
- [Class weighting](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/data/imbalance.py): `src/data/imbalance.py`

### Classifier training

- [Model factory](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/training/models.py): `src/training/models.py`
- [Training loop](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/training/loop.py): `src/training/loop.py`
- [Model checkpoint](https://github.com/piyushnile1509/sickle-detection/tree/claude/sickle-cell-cnn-research-g6fipc/models): `models`

### Inference and evaluation

- [Classifier evaluation](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/scripts/evaluate_classifier.py): `scripts/evaluate_classifier.py`
- [Field inference](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/inference.py): `src/inference.py`
- [Prediction CLI](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/scripts/predict.py): `scripts/predict.py`
- [Streamlit demo](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/app.py): `app.py`

### Cell counting

- [Detector CLI](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/scripts/count_cells.py): `scripts/count_cells.py`
- [YOLO cell counting](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/detector_counting.py): `src/detector_counting.py`
- [Cellpose heuristic](https://github.com/piyushnile1509/sickle-detection/blob/claude/sickle-cell-cnn-research-g6fipc/src/counting.py): `src/counting.py`
- [Detector weights](https://github.com/piyushnile1509/sickle-detection/tree/claude/sickle-cell-cnn-research-g6fipc/models/sickle5k_detector/weights): `models/sickle5k_detector/weights`

### Other components

- **Researcher / user**

## Connections

- Researcher / user → Primary images: provides images
- Primary images → Label manifest: builds labels
- Label manifest → Duplicate grouping: groups duplicates
- Duplicate grouping → Leakage-safe splits: informs groups
- Leakage-safe splits → Dataset transforms: selects samples
- Dataset transforms → Training loop: provides batches
- Class weighting → Training loop: weights loss
- Training loop → Model factory: sets training stage (evidence: `src/training/loop.py`)
- Training loop → Model checkpoint: saves model
- Model factory → Field inference: builds model (evidence: `src/inference.py`)
- Model checkpoint → Field inference: loads weights (evidence: `src/inference.py`)
- Researcher / user → Prediction CLI: requests prediction
- Prediction CLI → Field inference: runs inference (evidence: `scripts/predict.py`)
- Researcher / user → Streamlit demo: uploads image (evidence: `README.md`)
- Streamlit demo → Field inference: predicts field (evidence: `README.md`)
- Field inference → Classifier evaluation: supplies predictions (evidence: `scripts/evaluate_classifier.py`)
- Researcher / user → Detector CLI: requests counts (evidence: `README.md`)
- Detector CLI → YOLO cell counting: runs detector (evidence: `scripts/count_cells.py`)
- YOLO cell counting → Detector weights: loads weights
- Streamlit demo → YOLO cell counting: offers detector mode (evidence: `README.md`)
- Streamlit demo → Cellpose heuristic: offers fallback mode (evidence: `README.md`)
