# yvanyin/goalflow architecture

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

- Interactive diagram: https://gitdiagram.com/yvanyin/goalflow
- Repository: https://github.com/yvanyin/goalflow

## Overview

##### Project type and purpose
- **Type**: Research‐grade, end‐to‐end autonomous driving simulation and planning framework
- **Purpose**: Generate, train, simulate, and evaluate multimodal vehicle trajectories guided by goal points (GoalFlow), built on top of NAVSIM and using diffusion‐based flow matching.

##### File structure
- **Top‐level modules**:
- `navsim/` – core simulation, planning, evaluation, training, visualization
- `vovnet/` – visual backbone library (feature extraction)
- `nuplan-devkit` – external dataset & evaluation
- `scripts/` & `download/` – data download and orchestration scripts
- `setup.py`, `requirements.txt`, `docs/`
- **Key subdirectories in `navsim/`**
- `agents/` – vehicle behavior models (constant‐velocity, MLP, GoalFlow)
- `planning/` – scenario builder, metric caching, script runners, simulation planners
- `training/` – PyTorch Lightning modules, dataset definitions, callbacks
- `evaluate/` – scoring metrics (PDM)
- `visualization/` – BEV, camera, lidar plotting

##### README for additional insights
- **Pipeline stages described**: data download → goal‐point construction → training → validation/evaluation
- **Dependencies**: NAVSIM dataset, YAML configs for different agents, PyTorch, PyTorch Lightning, Hydra‐style config files

##### Main components & interactions
a. **Components**
1. Data Layer
- NAVSIM datasets (download via `download/*.sh`)
- `navsim/common/dataloader.py`
2. Scenario Builder
- `navsim/planning/scenario_builder/navsim_scenario.py`
3. Agent Models
- ConstantVelocityAgent, EgoStatusMLPAgent, **GoalFlowAgent**
- Model definitions in `navsim/agents/goalflow/*`, uses `vovnet` backbones
4. Planner & Simulator
- PDM planner (`navsim/planning/simulation/planner/pdm_planner/*`)
5. Metric Caching & Scoring
- `navsim/planning/metric_caching/*`
- PDM score (`navsim/evaluate/pdm_score.py`)
6. Training Pipeline
- LightningModule (`navsim/planning/training/agent_lightning_module.py`)
- Configs in `navsim/planning/script/config/training/*.yaml`
7. Evaluation & Visualization
- Scripts in `navsim/planning/script/run_*.py`
- Visualization (`navsim/visualization/*.py`)
8. Orchestration Scripts
- `scripts/` folder, top‐level `run_*.sh` wrappers

b. **Relationships & Data Flow**
1. **Data Download** → 2. **Dataloader** → 3. **Scenario Builder** → 4. **Agent Inference / Training** → 5. **Planner & Simulation** → 6. **Metric Caching** → 7. **Scoring** → 8. **Visualization / Output**
9. **Training Loop**: scenario builder + dataloader feed LightningModule → weight checkpoint
10. **Inference Loop**: use trained weights in GoalFlowAgent → follow same simulation → evaluation

c. **Architectural Patterns & Principles**
- **Modularity**: clear separation between data ingestion, scenario setup, agent logic, planner, and evaluation
- **Config‐driven orchestration**: YAML files under `navsim/planning/script/config/` control behaviors without code changes
- **Plug‐and‐play agents**: abstract base class in `navsim/agents/abstract_agent.py` → multiple agent implementations
- **PyTorch Lightning** for training lifecycle management
- **Metric caching** to avoid recomputation

d. **Key Technologies & Frameworks**
- Python 3.x, PyTorch, PyTorch Lightning
- NAVSIM (dataset & baseline platform)
- VovNet (vision backbone)
- Hydra‐style YAML configs

##### Detail without over‐splitting
- Of the seven major modules above
- Call out the `navsim/agents/goalflow` submodules (model, loss, features, backbone) as a grouped cluster
- Config layer as an overlay controlling the orchestration scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        DS1["NAVSIM Dataset"]:::data
        DL["Dataloader"]:::navsimModule
    end

    %% Scenario Builder
    SB["Scenario Builder"]:::navsimModule

    %% Agent Models
    subgraph "Agent Models"
        AG_ABS["abstract_agent.py"]:::navsimModule
        AG_CV["constant_velocity_agent.py"]:::navsimModule
        AG_MLP["ego_status_mlp_agent.py"]:::navsimModule
        subgraph "GoalFlowAgent" 
            GF_AGENT["goalflow_agent_traj.py"]:::novel
            GF_MODEL["goalflow_model_traj.py"]:::novel
            GF_LOSS["goalflow_loss.py"]:::novel
            GF_FEAT["goalflow_features.py"]:::novel
            GF_RN["resnet_backbone.py"]:::navsimModule
            GF_V99["v99_backbone.py"]:::navsimModule
        end
    end

    %% Planner & Simulator
    subgraph "PDM Planner"
        PP_ABS["abstract_pdm_planner.py"]:::navsimModule
        PP_CLOSED["pdm_closed_planner.py"]:::navsimModule
        PP_OBS["pdm_observation.py"]:::navsimModule
        PP_GEN["pdm_generator.py"]:::navsimModule
        PP_SIM["pdm_simulator.py"]:::navsimModule
    end

    %% Metric Caching & Scoring
    MC["Metric Caching"]:::navsimModule
    SC["PDM Scorer"]:::navsimModule

    %% Visualization
    VIS["Visualizer"]:::navsimModule

    %% Training Pipeline
    TP["Training Pipeline"]:::navsimModule

    %% Configs
    CFG["YAML Configs"]:::external

    %% Orchestration Scripts
    subgraph "Orchestration Scripts"
        OS1["run_dataset_cache_trainval.sh"]:::script
        OS2["run_generate_trajs.sh"]:::script
        OS3["run_goalflow_trajs.sh"]:::script
        UT["utils.py"]:::navsimModule
        SETUP["setup.py"]:::script
        REQ["requirements.txt"]:::script
    end

    %% Data flow
    DS1 -->|download| DL
    DL --> SB
    SB --> AG_ABS
    AG_ABS --> AG_CV
    AG_ABS --> AG_MLP
    AG_ABS --> GF_AGENT
    GF_AGENT --> GF_MODEL
    GF_MODEL --> GF_LOSS
    GF_MODEL --> GF_FEAT
    GF_FEAT --> GF_RN
    GF_FEAT --> GF_V99
    GF_AGENT --> PP_ABS
    PP_ABS --> PP_CLOSED
    PP_CLOSED --> PP_OBS
    PP_CLOSED --> PP_GEN
    PP_GEN --> PP_SIM
    PP_SIM --> MC
    MC --> SC
    SC --> VIS

    %% Training & Inference
    SB --> TP
    DL --> TP
    TP -->|weights| DS1
    TP --> SC

    %% Orchestration and Config
    OS1 --> DL
    OS2 --> SB
    OS2 --> AG_ABS
    OS3 --> SC
    CFG -.-> OS1
    CFG -.-> OS2
    CFG -.-> OS3
    UT --> OS1
    SETUP --> OS1
    REQ --> OS1

    %% Click Events
    click DS1 "https://github.com/yvanyin/goalflow/blob/main/download/download_maps.sh"
    click DS1 "https://github.com/yvanyin/goalflow/blob/main/download/download_mini.sh"
    click DS1 "https://github.com/yvanyin/goalflow/blob/main/download/download_navtrain.sh"
    click DS1 "https://github.com/yvanyin/goalflow/blob/main/download/download_private_test_e2e.sh"
    click DS1 "https://github.com/yvanyin/goalflow/blob/main/download/download_test.sh"
    click DS1 "https://github.com/yvanyin/goalflow/blob/main/download/download_trainval.sh"
    click DL "https://github.com/yvanyin/goalflow/blob/main/navsim/common/dataloader.py"
    click SB "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/scenario_builder/navsim_scenario.py"
    click SB "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/scenario_builder/navsim_scenario_utils.py"
    click AG_CV "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/constant_velocity_agent.py"
    click AG_MLP "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/ego_status_mlp_agent.py"
    click GF_AGENT "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/goalflow/goalflow_agent_traj.py"
    click GF_MODEL "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/goalflow/goalflow_model_traj.py"
    click GF_LOSS "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/goalflow/goalflow_loss.py"
    click GF_FEAT "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/goalflow/goalflow_features.py"
    click GF_RN "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/goalflow/resnet_backbone.py"
    click GF_V99 "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/goalflow/v99_backbone.py"
    click AG_ABS "https://github.com/yvanyin/goalflow/blob/main/navsim/agents/abstract_agent.py"
    click PP_ABS "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/simulation/planner/pdm_planner/abstract_pdm_planner.py"
    click PP_CLOSED "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/simulation/planner/pdm_planner/pdm_closed_planner.py"
    click PP_OBS "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py"
    click PP_GEN "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/simulation/planner/pdm_planner/proposal/pdm_generator.py"
    click PP_SIM "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py"
    click MC "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/metric_caching/caching.py"
    click MC "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/metric_caching/metric_cache.py"
    click MC "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/metric_caching/metric_cache_processor.py"
    click MC "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/metric_caching/metric_caching_utils.py"
    click SC "https://github.com/yvanyin/goalflow/blob/main/navsim/evaluate/pdm_score.py"
    click TP "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/training/agent_lightning_module.py"
    click TP "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/training/dataset.py"
    click TP "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/training/callbacks/time_logging_callback.py"
    click CFG "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/script/config/training/default_training.yaml"
    click CFG "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/script/config/training/goalflow_training.yaml"
    click OS1 "https://github.com/yvanyin/goalflow/blob/main/scripts/cahce/run_dataset_cache_trainval.sh"
    click OS2 "https://github.com/yvanyin/goalflow/blob/main/scripts/generate/run_generate_trajs.sh"
    click OS3 "https://github.com/yvanyin/goalflow/blob/main/scripts/evaluation/run_goalflow_trajs.sh"
    click UT "https://github.com/yvanyin/goalflow/blob/main/navsim/planning/script/utils.py"
    click SETUP "https://github.com/yvanyin/goalflow/blob/main/setup.py"
    click REQ "https://github.com/yvanyin/goalflow/blob/main/requirements.txt"

    %% Styles
    classDef navsimModule fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef novel fill:#ffdd99,stroke:#333,stroke-width:1px
    classDef data fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef script fill:#f0f0f0,stroke:#333,stroke-width:1px
```
