# aiclub-uit/aicity2024_track5 architecture

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

- Interactive diagram: https://gitdiagram.com/aiclub-uit/aicity2024_track5
- Repository: https://github.com/aiclub-uit/aicity2024_track5

## Overview

##### Data Management and Preprocessing
- The “data” folder holds raw input (i.e. videos and ground truth text files) that must adhere to a specific structure.
- The “scripts” folder contains scripts such as convert.sh for converting raw video data into a format that the training pipeline expects.
- The data processing component reads raw videos (from, for example, “data/aicity2024_track5_train”) and processes them into a usable dataset (frames/annotations) using the provided conversion scripts.

##### Training Pipeline and Model Development
- The bulk of the code is housed under “sources/Co-DETR”. This directory replicates a full object detection framework and contains configuration files (under “configs”), model definitions (in “mmdet”, “models”, “mmcv_custom”), training hooks, and evaluation metrics.
- The training instructions in the README indicate that pre-trained models are placed in “sources/Co-DETR/models” and that Docker Compose is used to orchestrate training (“docker compose up …”).
- This section leverages proven deep learning libraries (likely PyTorch with the mmcv and mmdet toolkits) extended by the Co-DETR code base to carry out model training.

##### Inference and Deployment
- The “sources/inference” directory contains a separate Dockerfile, configuration files, and inference scripts. The instructions show that inference is run by building a dedicated docker image and then executing the “inference.sh” script.
- Pre-trained weights for inference are stored in “sources/inference/weights”.
- The inference pipeline is modular and mirrors much of the training code (as evidenced by similar folder structure for custom mmcv and mmdet modules in the “inference” directory) while focusing on deployment and testing.

##### Docker-based Orchestration and Environment Management
- Several Dockerfiles exist across both the training (within “sources/Co-DETR/docker” and the docker-compose.yaml file) and inference directories. This shows the importance of containerization in ensuring reproducibility on GPU-enabled systems (note the use of “--gpus all” during docker run).
- The environment is specified using an environment.yml file and Docker Compose, which helps integrate all components seamlessly.

##### Supporting Utilities, Testing, and Documentation
- Beyond the core pipelines, there are directories for tests (extensive unit and integration tests under “sources/Co-DETR/tests”), utility scripts (in “sources/utils”), and documentation (in “sources/Co-DETR/docs” and “static”).

- Data Preprocessing Module: A block that runs the convert.sh script to transform raw data into the desired dataset.
- Training Pipeline: A large block labeled “Model Training (Co-DETR)” that includes subcomponents:
▪ Configuration/Parameter Management (from “configs”)
▪ Model Definition & Training Engine (from “mmdet”, “models”, “mmcv_custom”)
▪ Docker Compose orchestration (container symbol)
▪ Checkpoint Storage (models saved in “sources/Co-DETR/models”)
- Inference Pipeline: A separate block labeled “Inference & Deployment” that contains:
▪ Inference Engine (in “sources/inference”, with similar submodules as training)
▪ Weights/Checkpoint Loader (from “sources/inference/weights”)
▪ Docker container used to run inference.
- From Raw Data → Preprocessing → Training (data conversion output feeds training).
- Checkpoints are produced by training and used by inference.

- Since this is a full deep learning application with dedicated training and inference pipelines, ensure that both pipelines are given equal emphasis.
- A dedicated note on the integration of Docker for both pipelines.
- Feature the externally provided pre-trained models and mention that external model download links exist for both training and inference.
- Since the challenge is for helmet violation detection, you might annotate the training block with “Helmet Violation Detection (AICITY2024 Track5)” so that reviewers immediately know the application domain.

This detailed approach, using the internal structure of the repository (such as separating “Co-DETR” for training and “inference” for deployment), will help capture the comprehensive architecture of the system and offer a clear visual representation to guide further development or integration work.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Management and Preprocessing
    rawData(("Raw Data: Videos & GT")):::data
    dataPrep("Data Preprocessing (convert.sh)"):::processing
    processedDS("Processed Dataset"):::processing

    rawData -->|"raw_videos"| dataPrep
    dataPrep -->|"processed_dataset"| processedDS

    %% Training Pipeline and Model Development
    subgraph "Model Training (Co-DETR) - Helmet Violation Detection (AICITY2024 Track5)"
        T1("Configurations (configs)"):::training
        T2("Model & Training Engine (models, mmdet, mmcv_custom)"):::training
        T3("Training Orchestration (train.sh & Docker Compose)"):::training
        T3_5("Docker Config"):::training
        T4("Trained Model Checkpoints"):::training
        T1 --> T2
        T2 --> T3
        T3 --> T3_5
        T3_5 --> T4
    end

    processedDS -->|"dataset_input"| T3

    %% Inference and Deployment
    subgraph "Inference & Deployment"
        I0("Inference Pipeline Code"):::inference
        I1("Inference Engine (inference.py)"):::inference
        I2("Inference Configs"):::inference
        I3("Pre-trained Weights"):::inference
        I4("Inference Docker Container (Dockerfile)"):::inference
        I5("Inference Results"):::inference
        I0 --> I1
        I0 --> I2
        I0 --> I3
        I0 --> I4
        I1 --> I5
        I3 -->|"load_checkpoint"| I1
    end

    T4 -->|"trained_model_checkpoint"| I3
    I5 -->|"feedback"| T2

    %% Supporting Utilities, Testing, and Documentation
    subgraph "Supporting Utilities & Docs"
        U1("Utility Scripts"):::utilities
        U2("Tests (unit/integration)"):::utilities
        U3("Documentation & Static Assets"):::utilities
    end

    %% Connections from Supporting Utilities to Pipelines (indicative)
    U1 ---|"provides_funcs"| T1
    U2 ---|"validates"| T3
    U3 ---|"guides"| I1

    %% Click Events
    click rawData "https://github.com/aiclub-uit/aicity2024_track5/tree/main/data/"
    click dataPrep "https://github.com/aiclub-uit/aicity2024_track5/blob/main/scripts/convert.sh"
    click T1 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/Co-DETR/configs"
    click T2 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/Co-DETR/models"
    click T3 "https://github.com/aiclub-uit/aicity2024_track5/blob/main/sources/Co-DETR/train.sh"
    click T3_5 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/Co-DETR/docker/"
    click I0 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/inference/"
    click I1 "https://github.com/aiclub-uit/aicity2024_track5/blob/main/sources/inference/inference.py"
    click I2 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/inference/configs"
    click I3 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/inference/weights"
    click I4 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/inference/Dockerfile"
    click U1 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/utils/"
    click U2 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/Co-DETR/tests/"
    click U3 "https://github.com/aiclub-uit/aicity2024_track5/tree/main/sources/Co-DETR/docs/"

    %% Class definitions for styling
    classDef data fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef processing fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef training fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef inference fill:#FFB6C1,stroke:#8B0000,stroke-width:2px;
    classDef utilities fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
