# navi-challenge/navi-2025 architecture

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

- Interactive diagram: https://gitdiagram.com/navi-challenge/navi-2025
- Repository: https://github.com/navi-challenge/navi-2025

## Overview

##### Project Type and Purpose
- This is a deep‐learning research codebase for Video‐Text Retrieval (VTR) on the NAVI dataset (text‐based vehicle retrieval).
- It implements data preprocessing, PyTorch dataloaders, model definitions (XCLIP, CLIP, cross‐modal transformers), training and evaluation scripts, and submission‐generation utilities.

##### File Structure Analysis
Top‐level components:
- data_navi/ – raw NAVI dataset with subfolders for data, input, output, logs, models, similarity matrices, submissions
- dataloaders/ – PyTorch dataloader implementations for various benchmarks including NAVI
- modules/ – core model code: tokenizers, CLIP/XCLIP modules, cross‐modal modules, optimization, file utilities, configs
- main_clip4clip.py & main_xclip.py – entrypoints for training/testing corresponding model variants
- preprocess_data.py – transforms raw JSON/video data into the required format
- make_submission_from_sim_matrix.py – post‐processing script for submission files
- metrics.py & util.py – evaluation metrics and helper functions
- scripts/ – shell scripts to launch training/testing
- requirements.txt – Python dependencies

##### Key Insights from README
- Preprocess → train/test with shell scripts
- External pretrained weights for XCLIP, ViT‐B/16
- PyTorch 1.7.1 core framework

##### Main Components
A. Data Layer
1. Raw Dataset (data_navi/data & data_navi/navi/input/json)
2. Preprocessing Module (preprocess_data.py) → produces structured data for training/testing
B. Data Access Layer
1. dataloaders package
2. Video utilities (rawvideo_util.py)
3. JSON parsers for tracks & queries
C. Model Layer
1. Tokenization (modules/tokenization_clip.py)
2. Vision encoder (pretrained ViT‐B/16) – modules/module_clip.py
3. Text encoder (CLIP extended to max length 256) – modules/module_clip.py
4. Cross‐modal fusion (modules/module_cross.py & cross-base)
5. Configuration (modules/cross_config.json, until_config.py)
D. Training & Optimization
1. Training scripts (main_clip4clip.py, main_xclip.py)
2. Optimization module (modules/optimization.py)
3. Hyperparameter configs via shell scripts (scripts/*.sh)
4. External weights loader (modules/file_utils.py)
E. Evaluation & Submission
1. Similarity matrix generator → data_navi/navi/output/sim_matrix
2. make_submission_from_sim_matrix.py → data_navi/navi/output/submissions
3. metrics.py calculates retrieval metrics → data_navi/navi/output/log
F. Utilities & Support
1. util.py – general-purpose helpers
2. requirements.txt – environment specification

##### Relationships & Data Flow
- Raw Dataset → Preprocessing → Structured JSON/video frames
- Structured data → Dataloaders → Batched inputs
- Batched inputs → Model encoders (vision & text) → Feature embeddings
- Embeddings → Cross‐modal module → Similarity scores
- Scores → Loss & optimizer → Model weights checkpointing (data_navi/navi/output/models)
- At test time: Scores → sim_matrix → make_submission → final submission file
- metrics.py invoked within training/test loops to log performance

##### Architectural Patterns & Principles
- Modular separation: data ingestion, processing, modeling, training, evaluation
- Pipeline pattern: clear stages (preprocess → load → train → evaluate → submit)
- Config-driven: JSON configs and shell scripts parameterize experiments
- Reusable utilities: central modules for tokenization, file I/O, optimization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        rd1["Raw Data\n(data_navi/data)"]:::data
        rd2["Input Files\n(data_navi/navi/input)"]:::data
        rd3["JSON Files\n(data_navi/navi/json)"]:::data
    end
    click rd1 "https://github.com/navi-challenge/navi-2025/tree/main/data_navi/data"
    click rd2 "https://github.com/navi-challenge/navi-2025/tree/main/data_navi/navi/input"
    click rd3 "https://github.com/navi-challenge/navi-2025/tree/main/data_navi/navi/json"

    %% Preprocessing
    preprocess["Preprocessing Module\n(preprocess_data.py)"]:::pre
    click preprocess "https://github.com/navi-challenge/navi-2025/blob/main/preprocess_data.py"

    rd1 --> preprocess
    rd2 --> preprocess
    rd3 --> preprocess

    %% Data Access Layer
    subgraph "Data Access Layer"
        dl_pkg["Dataloaders Package\n(dataloaders/)"]:::pre
        rv_util["Video Utils\n(rawvideo_util.py)"]:::pre
        dl_navi["NAVI Dataloader\n(dataloader_navi_retrieval.py)"]:::pre
    end
    click dl_pkg "https://github.com/navi-challenge/navi-2025/tree/main/dataloaders/"
    click rv_util "https://github.com/navi-challenge/navi-2025/blob/main/dataloaders/rawvideo_util.py"
    click dl_navi "https://github.com/navi-challenge/navi-2025/blob/main/dataloaders/dataloader_navi_retrieval.py"

    preprocess --> dl_pkg
    dl_pkg --> rv_util
    dl_pkg --> dl_navi

    %% Model Layer
    subgraph "Model Layer"
        tok["Tokenizer\n(tokenization_clip.py)"]:::model
        enc["Vision & Text Encoders\n(module_clip.py,\nmodeling.py,\nmodeling_xclip.py)"]:::model
        cross["Cross-modal Fusion\n(module_cross.py)"]:::model
        cfg1["Cross Config\n(cross_config.json)"]:::model
        cfg2["General Config\n(until_config.py)"]:::model
    end
    click tok "https://github.com/navi-challenge/navi-2025/blob/main/modules/tokenization_clip.py"
    click enc "https://github.com/navi-challenge/navi-2025/blob/main/modules/module_clip.py"
    click enc "https://github.com/navi-challenge/navi-2025/blob/main/modules/modeling.py"
    click enc "https://github.com/navi-challenge/navi-2025/blob/main/modules/modeling_xclip.py"
    click cross "https://github.com/navi-challenge/navi-2025/blob/main/modules/module_cross.py"
    click cfg1 "https://github.com/navi-challenge/navi-2025/blob/main/modules/cross-base/cross_config.json"
    click cfg2 "https://github.com/navi-challenge/navi-2025/blob/main/modules/until_config.py"

    dl_pkg --> tok
    dl_pkg --> enc
    tok --> cross
    enc --> cross
    cfg1 --> cross
    cfg2 --> tok
    cfg2 --> enc

    %% Training & Optimization
    subgraph "Training & Optimization"
        train1["Train XCLIP\n(main_xclip.py)"]:::train
        train2["Train CLIP4Clip\n(main_clip4clip.py)"]:::train
        opt["Optimization Module\n(optimization.py)"]:::train
        fileu["Weights Loader\n(file_utils.py)"]:::train
        script1["Train Script\n(run_xclip_navi_vit16_train.sh)"]:::train
        testscript["Test Script\n(run_xclip_navi_vit16_test.sh)"]:::train
    end
    click train1 "https://github.com/navi-challenge/navi-2025/blob/main/main_xclip.py"
    click train2 "https://github.com/navi-challenge/navi-2025/blob/main/main_clip4clip.py"
    click opt "https://github.com/navi-challenge/navi-2025/blob/main/modules/optimization.py"
    click fileu "https://github.com/navi-challenge/navi-2025/blob/main/modules/file_utils.py"
    click script1 "https://github.com/navi-challenge/navi-2025/blob/main/scripts/run_xclip_navi_vit16_train.sh"
    click testscript "https://github.com/navi-challenge/navi-2025/blob/main/scripts/run_xclip_navi_vit16_test.sh"

    cross --> train1
    cross --> train2
    train1 --> opt
    train1 --> fileu
    train2 --> opt
    train2 --> fileu
    script1 --> train1
    testscript --> train1

    %% Evaluation & Submission
    subgraph "Evaluation & Submission"
        sim["Similarity Matrix\n(data_navi/navi/output/sim_matrix)"]:::eval
        subm_script["Submission Generator\n(make_submission_from_sim_matrix.py)"]:::eval
        sub_out["Submissions\n(data_navi/navi/output/submissions)"]:::eval
        logs["Logs\n(data_navi/navi/output/log)"]:::eval
        mets["Metrics\n(metrics.py)"]:::eval
    end
    click sim "https://github.com/navi-challenge/navi-2025/tree/main/data_navi/navi/output/sim_matrix"
    click subm_script "https://github.com/navi-challenge/navi-2025/blob/main/make_submission_from_sim_matrix.py"
    click sub_out "https://github.com/navi-challenge/navi-2025/tree/main/data_navi/navi/output/submissions"
    click logs "https://github.com/navi-challenge/navi-2025/tree/main/data_navi/navi/output/log"
    click mets "https://github.com/navi-challenge/navi-2025/blob/main/metrics.py"

    train1 --> sim
    testscript --> sim
    sim --> subm_script
    subm_script --> sub_out
    train1 --> mets
    testscript --> mets
    mets --> logs

    %% Utilities & Support
    subgraph "Utilities & Support"
        util["General Utilities\n(util.py)"]:::support
        req["Requirements\n(requirements.txt)"]:::support
    end
    click util "https://github.com/navi-challenge/navi-2025/blob/main/util.py"
    click req "https://github.com/navi-challenge/navi-2025/blob/main/requirements.txt"

    train1 --> util
    train2 --> util
    train1 --> req

    %% External Dependencies
    subgraph "External Dependencies"
        torch["PyTorch 1.7.1"]:::external
        weights["Pretrained Weights\n(Google Drive)"]:::external
    end
    torch --> enc
    torch --> tok
    weights --> fileu

    %% Styles
    classDef data fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef pre fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef model fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef train fill:#CE93D8,stroke:#6A1B9A,color:#6A1B9A
    classDef eval fill:#FFF59D,stroke:#F9A825,color:#F9A825
    classDef support fill:#EEEEEE,stroke:#424242,color:#424242
    classDef external fill:#CFD8DC,stroke:#455A64,color:#455A64
```
