# ghelani-kirtan/rt-detr-polyp-detection architecture

> Architecture diagram of the GitHub repository ghelani-kirtan/rt-detr-polyp-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghelani-kirtan/rt-detr-polyp-detection
- Repository: https://github.com/ghelani-kirtan/rt-detr-polyp-detection

## Overview

##### Project Type & Purpose
- This is a modular Machine-Learning system for real-time polyp detection & classification.
- It consists of three primary subsystems:
a. Data Ingestion & Preparation (data_pipelines)
b. Model Training & Zoo (src + configs + solver + zoo)
c. Inference & Deployment (scripts + tracker + tools + s3_tools)

##### High-Level File-Structure Analysis
- Top-level directories:
- configs/ YAML definitions for datasets, dataloaders, optimizers, model variants (RT-DETR v1 & v2).
- data_pipelines/ CLI-driven dataset download → clean → organize → prepare into COCO format.
- src/ Core training library:
– src/core: config & workspace management
– src/data: dataloaders, dataset wrappers, transforms
– src/nn: network architectures, backbones, loss & postprocessors
– src/optim: AMP, EMA, schedulers
– src/solver: training/evaluation engines for detection & classification
– src/zoo: ready-to-use RT-DETR(-v2) implementations
- scripts/ Inference system: CLI entrypoint (run_inference.py), core inference engine, config templates.
- tracker/ ByteTrack implementation for multi-object tracking.
- tools/ Model export (ONNX, TensorRT, CoreML), profiling, training helper.
- s3_tools/ & s3_sync.py S3 + HTTP API integration for data & model storage.
- Dockerfile & docker-compose.yml Containerized environment.

##### Key External Interactions
- HTTP API / S3 for dataset version download (data_pipelines).
- GPU resource via CUDA & PyTorch for training & inference.
- Video or camera input for real-time inference (scripts).

##### Main Components
a. Data Layer
- API/S3 Downloader → Cleaner → Organizer → Preparer → COCO JSON + Images
b. Training Layer
- Config Loader (YAML) ↔ Training Engine (clas_engine / det_engine)
- Model Zoo definitions → Backbone + RT-DETR Modules
- Optimizer / Scheduler / EMA → Checkpoint (model.pth)
c. Artifact Layer
- Checkpoints → Export Tools → ONNX, TRT, CoreML artifacts
- Model Storage (Local / S3)
d. Inference Layer
- Inference CLI (run_inference.py)
- Inference Engine / High-res variant
- Model Loader (ONNX / PyTorch)
- Tracker (ByteTrack) + EMA smoothing + Visualizer → Video stream output
e. Deployment Layer
- Docker Container & Compose Orchestration
- s3_tools / s3_sync for automated model & data upload/download

##### Relationships & Data Flows
- “Download → Clean → Organize → Prepare” (Data Pipeline stages)
- “Prepared Dataset + YAML Config → Training Engine → Model Checkpoint”
- “Checkpoint → Export → Serialized Model”
- “Serialized Model + Config → Inference Engine → Tracked Output”
- “Inference Engine → Calls Tracker Module”
- “CLI ↔ Core Libraries”
- “Docker Compose → Spins up inference & data pipeline services”

##### Architectural Patterns & Principles
- Layered, modular design with clear separation of concerns.
- Config-first approach: all behavior controlled via YAML.
- CLI wrappers for each subsystem (data, train, infer).
- Pluggable model zoo and config includes for easy experiment swapping.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Data Layer
  subgraph "Data Layer"
    API_DL["API Downloader"]:::data
    click API_DL "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/data_pipelines/downloaders/api_downloader.py"
    S3_DL["S3 Downloader"]:::data
    click S3_DL "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/data_pipelines/downloaders/s3_downloader.py"
    Cleaner["Dataset Cleaner"]:::data
    click Cleaner "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/data_pipelines/cleaners/dataset_cleaner.py"
    Organizer["Detection Organizer"]:::data
    click Organizer "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/data_pipelines/organizers/detection_organizer.py"
    Preparer["Detection Preparer"]:::data
    click Preparer "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/data_pipelines/preparers/detection_preparer.py"
    Dataset_Storage["Dataset Storage"]:::data
  end

  API_DL -->|"raw data"| Cleaner
  S3_DL -->|"raw data"| Cleaner
  Cleaner -->|"clean data"| Organizer
  Organizer -->|"organized data"| Preparer
  Preparer -->|"COCO JSON"| Dataset_Storage

  %% Training Layer
  subgraph "Training Layer"
    Config_Core["Config Loader"]:::train
    click Config_Core "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/core/_config.py"
    click Config_Core "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/core/yaml_config.py"
    Workspace["Workspace Manager"]:::train
    click Workspace "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/core/workspace.py"
    Data_Handler["Data Handler"]:::train
    click Data_Handler "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/data/dataloader.py"
    click Data_Handler "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/data/dataset/coco_dataset.py"
    Model_Zoo["Model Zoo"]:::train
    click Model_Zoo "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/zoo/rtdetr/rtdetr.py"
    click Model_Zoo "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/zoo/rtdetr/rtdetr_decoder.py"
    click Model_Zoo "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/zoo/rtdetr/rtdetr_criterion.py"
    click Model_Zoo "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/zoo/rtdetr/rtdetr_postprocessor.py"
    Optimizer["Optimizers & Scheduler"]:::train
    click Optimizer "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/optim/amp.py"
    click Optimizer "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/optim/ema.py"
    Training_Engine["Training Engine"]:::train
    click Training_Engine "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/solver/det_engine.py"
    click Training_Engine "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/src/solver/clas_engine.py"
    Checkpoint_Storage["Checkpoint Storage"]:::train
  end

  Dataset_Storage -->|"COCO JSON + Config"| Config_Core
  Config_Core --> Workspace
  Workspace --> Data_Handler
  Data_Handler --> Training_Engine
  Model_Zoo --> Training_Engine
  Optimizer --> Training_Engine
  Training_Engine -->|"model.pth"| Checkpoint_Storage

  %% Artifact Layer
  subgraph "Artifact Layer"
    Export_Tools["Export Tools"]:::artifact
    click Export_Tools "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/tools/export_onnx.py"
    click Export_Tools "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/tools/export_trt.py"
    click Export_Tools "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/tools/export_coreml.py"
    Serialized_Model["Serialized Models"]:::artifact
    Model_Store["Model Storage"]:::artifact
    click Model_Store "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/s3_tools/model_detector.py"
  end

  Checkpoint_Storage -->|"checkpoint"| Export_Tools
  Export_Tools -->|"ONNX, TRT, CoreML"| Serialized_Model
  Serialized_Model --> Model_Store

  %% Inference Layer
  subgraph "Inference Layer"
    Inference_CLI["Inference CLI"]:::inference
    click Inference_CLI "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/scripts/run_inference.py"
    Inference_Engine["Inference Engine"]:::inference
    click Inference_Engine "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/scripts/core/inference_engine.py"
    Tracker["ByteTrack Tracker"]:::inference
    click Tracker "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/tracker/byte_tracker.py"
    Visualizer["Visualizer"]:::inference
    click Visualizer "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/scripts/core/visualizer.py"
    Video_Output["Video Output"]:::inference
  end

  Model_Store -->|"model + config"| Inference_CLI
  Inference_CLI --> Inference_Engine
  Inference_Engine -->|"load model"| Model_Store
  Inference_Engine -->|"calls Tracker"| Tracker
  Tracker --> Visualizer
  Visualizer --> Video_Output

  %% Deployment Layer
  subgraph "Deployment Layer"
    Docker["Docker Compose"]:::deploy
    click Docker "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/docker-compose.yml"
    S3_Tools["S3 Tools"]:::deploy
    click S3_Tools "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/s3_tools/cli.py"
    click S3_Tools "https://github.com/ghelani-kirtan/rt-detr-polyp-detection/blob/main/s3_sync.py"
  end

  Docker --> Data_Layer
  Docker --> Training_Layer
  Docker --> Inference_Layer
  Docker --> Artifact_Layer
  S3_Tools --> Dataset_Storage
  S3_Tools --> Model_Store

  %% Styles
  classDef data fill:#D0E8FF,stroke:#333,stroke-width:1px;
  classDef train fill:#D0FFD8,stroke:#333,stroke-width:1px;
  classDef inference fill:#FFE0B2,stroke:#333,stroke-width:1px;
  classDef artifact fill:#FFF2CC,stroke:#333,stroke-width:1px;
  classDef deploy fill:#E0D4FF,stroke:#333,stroke-width:1px;
```
