# hoangvu123456/techjam_2025 architecture

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

- Interactive diagram: https://gitdiagram.com/hoangvu123456/techjam_2025
- Repository: https://github.com/hoangvu123456/techjam_2025

## Overview

##### Project type and purpose
- This is a Python-based machine-learning pipeline for object detection using PyTorch and Faster R-CNN variants. The repository provides modules for data preparation, model construction, training, evaluation, and inference (including ensemble and video inference).

##### File structure
- Top level
- train.py, inference.py, inference_video.py, ensemble_inference.py, parallel.py — CLI entry points for train / single-image inference / video inference / ensemble inference / parallel execution.
- datasets.py — custom Dataset definitions.
- requirements.txt — dependencies (PyTorch, torchvision, etc.).
- data & data_configs
- data/split.py — scripts for splitting raw data.
- data_configs/ppe.yaml — YAML configs for different datasets or experiments.
- models
- create_fasterrcnn_model.py — factory that wires up various backbones.
- fasterrcnn_resnet*.py — per-backbone model definitions.
- torch_utils
- engine.py, utils.py, coco_utils.py, coco_eval.py — training/evaluation engine, utility functions, COCO API wrappers.
- utils
- transforms.py, annotations.py, general.py, logging.py — helper functions for data transforms, annotation parsing, logging, general utilities.

##### README(s) for additional insights
- The main README.md is empty, but torch_utils/README.md likely describes the training loop API (prepare data loader, training step, evaluation step).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        CFG["YAML Config (ppe.yaml)"]:::config
        click CFG "https://github.com/hoangvu123456/techjam_2025/blob/development/data_configs/ppe.yaml"
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RAW["Raw Data"]:::external
        SPLIT["Data Split Script"]:::data
        click SPLIT "https://github.com/hoangvu123456/techjam_2025/blob/development/data/split.py"
        DATASET["Dataset Definitions"]:::data
        click DATASET "https://github.com/hoangvu123456/techjam_2025/blob/development/datasets.py"
        TRANS["Transforms"]:::data
        click TRANS "https://github.com/hoangvu123456/techjam_2025/blob/development/utils/transforms.py"
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        FACTORY["Faster R-CNN Factory"]:::model
        click FACTORY "https://github.com/hoangvu123456/techjam_2025/blob/development/models/create_fasterrcnn_model.py"
        RES18["ResNet18 FPN"]:::model
        click RES18 "https://github.com/hoangvu123456/techjam_2025/blob/development/models/fasterrcnn_resnet18_fpn.py"
        RES34["ResNet34 FPN"]:::model
        click RES34 "https://github.com/hoangvu123456/techjam_2025/blob/development/models/fasterrcnn_resnet34_fpn.py"
        RES50["ResNet50 FPN"]:::model
        click RES50 "https://github.com/hoangvu123456/techjam_2025/blob/development/models/fasterrcnn_resnet50_fpn.py"
        RES50V2["ResNet50 FPN v2"]:::model
        click RES50V2 "https://github.com/hoangvu123456/techjam_2025/blob/development/models/fasterrcnn_resnet50_fpn_v2.py"
        RES101["ResNet101 FPN"]:::model
        click RES101 "https://github.com/hoangvu123456/techjam_2025/blob/development/models/fasterrcnn_resnet101_fpn.py"
    end

    %% Engine Layer
    subgraph "Engine Layer"
        direction TB
        ENGINE["Training & Evaluation Engine"]:::engine
        click ENGINE "https://github.com/hoangvu123456/techjam_2025/blob/development/torch_utils/engine.py"
        UTILS_T["Torch Utilities"]:::engine
        click UTILS_T "https://github.com/hoangvu123456/techjam_2025/blob/development/torch_utils/utils.py"
        COCO_U["COCO Utils"]:::engine
        click COCO_U "https://github.com/hoangvu123456/techjam_2025/blob/development/torch_utils/coco_utils.py"
        COCO_E["COCO Eval"]:::engine
        click COCO_E "https://github.com/hoangvu123456/techjam_2025/blob/development/torch_utils/coco_eval.py"
    end

    %% Utilities Layer
    subgraph "Utilities"
        direction TB
        U_G["General Utilities"]:::util
        click U_G "https://github.com/hoangvu123456/techjam_2025/blob/development/utils/general.py"
        U_A["Annotation Utilities"]:::util
        click U_A "https://github.com/hoangvu123456/techjam_2025/blob/development/utils/annotations.py"
        U_L["Logging Utilities"]:::util
        click U_L "https://github.com/hoangvu123456/techjam_2025/blob/development/utils/logging.py"
    end

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        TRAIN["Training CLI (train.py)"]:::cli
        click TRAIN "https://github.com/hoangvu123456/techjam_2025/blob/development/train.py"
        INF["Single-Image Inference (inference.py)"]:::cli
        click INF "https://github.com/hoangvu123456/techjam_2025/blob/development/inference.py"
        VINF["Video Inference (inference_video.py)"]:::cli
        click VINF "https://github.com/hoangvu123456/techjam_2025/blob/development/inference_video.py"
        ENS["Ensemble Inference (ensemble_inference.py)"]:::cli
        click ENS "https://github.com/hoangvu123456/techjam_2025/blob/development/ensemble_inference.py"
        PAR["Parallel Execution (parallel.py)"]:::cli
        click PAR "https://github.com/hoangvu123456/techjam_2025/blob/development/parallel.py"
    end

    %% Dependencies
    REQ["Project Dependencies\n(requirements.txt)"]:::external
    click REQ "https://github.com/hoangvu123456/techjam_2025/blob/development/requirements.txt"
    PYT["PyTorch & torchvision"]:::external
    COCO_API["COCO API"]:::external

    %% Flow
    CFG -->|loads config| SPLIT
    CFG -->|loads config| FACTORY
    RAW -->|images,annotations| SPLIT
    SPLIT -->|splits data| DATASET
    DATASET -->|datasets| TRANS
    TRANS -->|transformed batches| ENGINE
    FACTORY -->|model instance| ENGINE
    RES18 --> FACTORY
    RES34 --> FACTORY
    RES50 --> FACTORY
    RES50V2 --> FACTORY
    RES101 --> FACTORY
    ENGINE -->|calls| COCO_U
    ENGINE -->|calls| COCO_E
    ENGINE -->|uses| UTILS_T
    U_G -->|helpers| SPLIT
    U_A -->|parsing| DATASET
    U_L -->|logs| ENGINE
    TRAIN -->|orchestrates| ENGINE
    TRAIN -->|reads| CFG
    INF -->|uses| FACTORY
    INF -->|reads| DATASET
    VINF -->|uses| FACTORY
    VINF -->|reads| DATASET
    ENS -->|aggregates| INF
    PAR -->|parallelizes| TRAIN

    PYT -->|library| FACTORY
    PYT -->|library| ENGINE
    COCO_API -->|evaluation| COCO_U
    COCO_API -->|evaluation| COCO_E

    %% Styles
    classDef config fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef data fill:#E8F5D0,stroke:#4CAF50,color:#4CAF50
    classDef model fill:#D0F0E8,stroke:#00897B,color:#00897B
    classDef engine fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef cli fill:#F3E8FF,stroke:#9C27B0,color:#9C27B0
    classDef util fill:#F5F5F5,stroke:#616161,color:#424242
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#616161
```
