# sense-x/co-detr architecture

> Architecture diagram of the GitHub repository sense-x/co-detr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sense-x/co-detr
- Repository: https://github.com/sense-x/co-detr

## Overview

##### Main Components
- Configurations & Experiment Management – The repository contains several layers of configuration files (found in the “configs” and “projects/configs” folders) that define datasets, model architectures, training schedules, and runtime parameters.
- Core Modules & Framework Library – The “mmdet” folder (which mimics the MMDetection structure) includes submodules for dataset handling, model definitions (backbones, necks, detectors, heads), loss functions, evaluation routines, and postprocessing.
- Model Definitions & Custom Research Implementations – In addition to the core components, there is a “projects” folder with custom models and configurations (e.g., collaborative hybrid assignments, Co‑DINO, Co‑Deformable‑DETR) that extend the base detector architectures.
- Utilities & API Layers – The “mmdet/apis” folder contains training, testing, and inference routines while “mmcv_custom” houses modifications or extra utilities to extend MMCV functionalities.
- Data & Pipeline – The “mmdet/datasets” and “mmdet/datasets/pipelines” directories define how data is loaded, augmented, transformed, and fed into the model during training and testing.
- Tools & Deployment – The “tools”, “docker”, and “demo” folders provide scripts for model training, evaluation, converting models (e.g., to ONNX or TensorRT), data conversion, and demo notebooks which facilitate both model deployment and visualization.
- Tests & Documentation – The “tests” and “docs” folders verify functionality and provide detailed instructions and usage guidelines (including performance and reproducibility information).

##### Relationships and Interactions
- At the top level, the configuration files (from “configs” and “projects/configs”) are loaded by training/inference APIs (in “mmdet/apis” and “tools/train.py”) to set up the training experiments.
- The API layer instantiates models from the “mmdet/models” (and “projects/models” for customized research variants) and ties them to the dataset pipelines from “mmdet/datasets”.
- The core functionality (in “mmdet/core”) implements shared abstractions like loss calculation, postprocessing (NMS, matrix NMS), anchor generation, and optimization hooks. This module coordinates with lower-level utilities (in “mmdet/utils”) and MMCV modules.
- Tools and deployment scripts use the models (exported via ONNX or integrated within Docker containers) to provide further analysis, benchmarking, and online inference demonstrations.
- All of these components are integrated so that changes in configuration or new model architectures can be easily swapped or extended—embodying the modular design principle.

##### Architectural Patterns and Design Principles
- Modular & Config‑Driven Design: By separating configuration specifications (in hierarchical config files) from the code implementation, it supports experiment reproducibility and easy model variants creation.
- Layered Architecture: The system is layered from low-level utilities (data pipelines, core operations) up through model definitions and training APIs to high-level deployment tools.
- Extensibility & Flexibility: Through multiple folders (such as “projects” for custom research models and “tools” for deployment), the architecture highlights plug‑in design where new components (e.g., new heads or loss functions) can be added with minimal impact on the existing framework.

- Top Level:
- “Data Pipeline” (datasets, pipelines) feeding into “Model & Training API” layer.
- Below that:
- “Core Operations” (mmdet/core – anchors, bbox coder, optimization hooks).
- Peripheral/Supporting Modules:
- “Utilities & Scripts” (tools, docker, demo) that interface with the training/inference APIs.
- “Testing & Documentation” (tests, docs) which ensure integrity and provide developer guidance.
- External Dependencies:
- “External Libraries” such as PyTorch and MMCV connected to the core and API layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Experiment Management
    subgraph "Configuration & Experiment Management"
        CFG["configs"] 
        PCFG["projects/configs"]
    end

    %% API & Data Pipeline
    subgraph "API & Data Pipeline"
        APIS["mmdet/apis"]
        TRAIN["tools/train.py"]
        DS["mmdet/datasets"]
        PIPE["mmdet/datasets/pipelines"]
    end

    %% Core Operations & Utilities
    subgraph "Core Operations & Utilities"
        CORE["mmdet/core"]
        UTILS["mmdet/utils"]
        MMCV["mmcv_custom"]
    end

    %% Model Definitions & Custom Research
    subgraph "Model Definitions & Custom Research"
        PMODELS["projects/models"]
    end

    %% Tools & Deployment
    subgraph "Tools & Deployment"
        TOOLS["tools"]
        DOCKER["docker"]
        DEMO["demo"]
    end

    %% Tests & Documentation
    subgraph "Tests & Documentation"
        TEST["tests"]
        DOCS["docs"]
    end

    %% External Dependencies
    PT["PyTorch"]
    MMCVEx["MMCV"]

    %% Connections between layers
    CFG --> APIS
    PCFG --> APIS
    TRAIN --> APIS
    DS --> PIPE
    PIPE --> APIS
    APIS -->|"instantiates"| PMODELS
    APIS -->|"calls core functions"| CORE
    CORE --> UTILS
    CORE --> MMCV
    APIS -->|"provides output to"| TOOLS
    TOOLS --> DOCKER
    TOOLS --> DEMO

    %% External dependencies connections
    PT --> APIS
    PT --> CORE
    MMCVEx --> MMCV

    %% Connections from Tests & Documentation feedback (optional)
    TEST --- CORE
    DOCS --- CFG

    %% Styles
    classDef config fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef tools fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#000,stroke-width:2px;

    class CFG,PCFG config;
    class APIS,TRAIN,DS,PIPE api;
    class CORE,UTILS,MMCV,PMODELS core;
    class TOOLS,DOCKER,DEMO,TEST,DOCS tools;
    class PT,MMCVEx external;

%% Click Events
click CFG "https://github.com/sense-x/co-detr/tree/main/configs"
click PCFG "https://github.com/sense-x/co-detr/tree/main/projects/configs"
click APIS "https://github.com/sense-x/co-detr/tree/main/mmdet/apis"
click TRAIN "https://github.com/sense-x/co-detr/blob/main/tools/train.py"
click DS "https://github.com/sense-x/co-detr/tree/main/mmdet/datasets"
click PIPE "https://github.com/sense-x/co-detr/tree/main/mmdet/datasets/pipelines"
click MMCV "https://github.com/sense-x/co-detr/tree/main/mmcv_custom"
click PMODELS "https://github.com/sense-x/co-detr/tree/main/projects/models"
click TOOLS "https://github.com/sense-x/co-detr/tree/main/tools"
click DOCKER "https://github.com/sense-x/co-detr/tree/main/docker"
click DEMO "https://github.com/sense-x/co-detr/tree/main/demo"
click TEST "https://github.com/sense-x/co-detr/tree/main/tests"
click DOCS "https://github.com/sense-x/co-detr/tree/main/docs"
```
