# alniyatrui/cafe-ad architecture

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

- Interactive diagram: https://gitdiagram.com/alniyatrui/cafe-ad
- Repository: https://github.com/alniyatrui/cafe-ad

## Overview

##### Project Type & Purpose
- This is a research‐grade full‐stack ML system for autonomous‐vehicle trajectory planning (CAFE-AD), built atop the PLUTO framework.
- Key goals: ingest nuPlan scenarios, preprocess & augment data, train a transformer‐based planner (PLUTO model) with cross‐scenario adaptive features, then run inference in simulation and evaluate trajectories.

##### High-Level Components
a. Data & Config
- External: nuPlan dataset (raw scenarios), HuggingFace 100K split
- Config layer: YAML files under `config/` (trainer, model, planner, augmentation, filters, training, lightning)
- Scripts: shell wrappers in `script/` + `train.sh`, `simulation.sh`
b. Preprocessing & Augmentation
- `preprocess/preprocess.py`: scenario distribution & token list generation
- `src/data_augmentation/contrastive_scenario_generator.py` + config-driven augmentation
c. Feature Extraction
- `src/feature_builders/…`: map, agent, scenario features → unified feature vectors
- `src/features/pluto_feature.py`: final feature representation
d. Training Pipeline
- DataModule & builder: `src/custom_training/custom_datamodule.py`, `custom_training_builder.py`
- Model & loss: `src/models/pluto/…` (encoder modules, transformer, embeddings, MLP layers, collision loss)
- Optimizer & scheduler: `src/optim/warmup_cos_lr.py`
- Trainer: PyTorch Lightning wrapper in `src/models/pluto/pluto_trainer.py`
- Entry point: `run_training.py` driven by `train.sh`
e. Inference & Simulation
- Planners: `src/planners/pluto_planner*.py` (learned, IDM, log‐replay variants)
- Scenario manager: `src/scenario_manager/` (route, occupancy, cost maps)
- Runner: `run_simulation.py`, `idm_simulation.py`, `log_replay.py`, orchestrated by `simulation.sh`
f. Post-processing & Evaluation
- Forward sim: `src/post_processing/forward_simulation/…`
- Metrics & evaluation: `src/post_processing/evaluation/comfort_metrics.py`, `src/metrics/*.py`
- Visualization & results: `result.py`, `src/utils/vis.py`

##### Interactions & Data Flow
1. Raw nuPlan Data → Preprocess → token_list, filtered scenarios
2. Filtered scenarios + Augmentation → Feature Builders → Batched tensors
3. DataLoader → PLUTO Model (encoders → transformer → decoder) → Loss functions → Trainer → Checkpoint
4. Checkpoint + Config → Planner component → Simulation Loop (scenario_manager drives environment)
5. Trajectory outputs → Post-processing simulators & metrics → Results & visualizations

##### Architectural Patterns & Principles
- Modular pipelines: separate dirs for preprocess, augment, features, model, planners, post_processing
- Config‐driven orchestration: YAML + Hydra-style parameters
- Pluggable components: multiple planner backends (learned vs. heuristic)
- Clear separation of concerns: DataModule vs. Model vs. Trainer vs. Inference vs. Evaluation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data & Config Layer
    subgraph "Data & Config" 
        direction TB
        NuPlan["nuPlan Dataset"]:::external
        HF["HuggingFace 100K Split"]:::external
        Config["YAML Configs"]:::config
        Scripts["Shell Scripts & Wrappers"]:::scripts
    end

    %% Preprocessing & Augmentation
    subgraph "Preprocessing & Augmentation"
        direction TB
        Preprocess["Preprocess Script"]:::data
        Augmentation["Contrastive Scenario Generator"]:::data
    end

    %% Feature Extraction
    subgraph "Feature Extraction"
        direction TB
        FeatureBuilders["Feature Builders"]:::data
        PlutoFeature["PLUTO Feature Representation"]:::data
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        DataModule["Custom DataModule & Builder"]:::model
        PLUTOModel["PLUTO Transformer Model"]:::model
        Trainer["PyTorch Lightning Trainer"]:::model
        Checkpoint["Model Checkpoint"]:::model
    end

    %% Inference & Simulation
    subgraph "Inference & Simulation"
        direction TB
        Planner["PLUTO Planner Variants"]:::inference
        ScenarioMgr["Scenario Manager"]:::inference
        Simulator["Simulation Runner"]:::inference
    end

    %% Post-processing & Evaluation
    subgraph "Post-processing & Evaluation"
        direction TB
        ForwardSim["Forward Simulation"]:::post
        Evaluation["Metrics & Evaluation"]:::post
        Visualization["Visualization & Results"]:::post
    end

    %% Flows
    NuPlan -->|raw data| Preprocess
    HF --> Preprocess
    Config --> Preprocess
    Scripts --> Preprocess

    Preprocess --> Augmentation
    Config --> Augmentation

    Augmentation --> FeatureBuilders
    FeatureBuilders --> PlutoFeature

    PlutoFeature --> DataModule
    Config --> DataModule

    DataModule --> PLUTOModel
    PLUTOModel --> Trainer
    Config --> Trainer
    Scripts --> Trainer
    Trainer --> Checkpoint

    Checkpoint --> Planner
    Config --> Planner
    Planner --> ScenarioMgr
    ScenarioMgr --> Simulator
    Scripts --> Simulator

    Simulator --> ForwardSim
    ForwardSim --> Evaluation
    Evaluation --> Visualization
    result.py --> Visualization

    %% Click Events
    click Config "https://github.com/alniyatrui/cafe-ad/tree/master/config/"
    click Scripts "https://github.com/alniyatrui/cafe-ad/tree/master/script/"
    click Scripts "https://github.com/alniyatrui/cafe-ad/blob/master/train.sh"
    click Scripts "https://github.com/alniyatrui/cafe-ad/blob/master/simulation.sh"
    click Preprocess "https://github.com/alniyatrui/cafe-ad/blob/master/preprocess/preprocess.py"
    click Preprocess "https://github.com/alniyatrui/cafe-ad/blob/master/preprocess/above_avg_types.json"
    click Preprocess "https://github.com/alniyatrui/cafe-ad/blob/master/preprocess/type2id.json"
    click Augmentation "https://github.com/alniyatrui/cafe-ad/blob/master/src/data_augmentation/contrastive_scenario_generator.py"
    click Augmentation "https://github.com/alniyatrui/cafe-ad/blob/master/config/data_augmentation/contrastive_scenario_generator.yaml"
    click FeatureBuilders "https://github.com/alniyatrui/cafe-ad/tree/master/src/feature_builders/"
    click PlutoFeature "https://github.com/alniyatrui/cafe-ad/blob/master/src/features/pluto_feature.py"
    click DataModule "https://github.com/alniyatrui/cafe-ad/blob/master/src/custom_training/custom_datamodule.py"
    click DataModule "https://github.com/alniyatrui/cafe-ad/blob/master/src/custom_training/custom_training_builder.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/pluto_model.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/tree/master/src/models/pluto/modules/"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/layers/transformer.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/layers/common_layers.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/layers/embedding.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/layers/fourier_embedding.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/layers/mlp_layer.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/layers/prune_block.py"
    click PLUTOModel "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/loss/esdf_collision_loss.py"
    click Trainer "https://github.com/alniyatrui/cafe-ad/blob/master/src/models/pluto/pluto_trainer.py"
    click Trainer "https://github.com/alniyatrui/cafe-ad/blob/master/src/optim/warmup_cos_lr.py"
    click Scripts "https://github.com/alniyatrui/cafe-ad/blob/master/run_training.py"
    click Config "https://github.com/alniyatrui/cafe-ad/blob/master/config/training/train_pluto.yaml"
    click Config "https://github.com/alniyatrui/cafe-ad/blob/master/config/lightning/custom_lightning.yaml"
    click Config "https://github.com/alniyatrui/cafe-ad/blob/master/config/default_training.yaml"
    click Planner "https://github.com/alniyatrui/cafe-ad/blob/master/src/planners/pluto_planner-learn.py"
    click Planner "https://github.com/alniyatrui/cafe-ad/blob/master/src/planners/pluto_planner-IDM.py"
    click Planner "https://github.com/alniyatrui/cafe-ad/blob/master/src/planners/pluto_planner-log_replay.py"
    click Planner "https://github.com/alniyatrui/cafe-ad/blob/master/src/planners/pluto_planner.py"
    click Planner "https://github.com/alniyatrui/cafe-ad/blob/master/src/planners/ml_planner_utils.py"
    click ScenarioMgr "https://github.com/alniyatrui/cafe-ad/blob/master/src/scenario_manager/route_manager.py"
    click ScenarioMgr "https://github.com/alniyatrui/cafe-ad/blob/master/src/scenario_manager/occupancy_map.py"
    click ScenarioMgr "https://github.com/alniyatrui/cafe-ad/blob/master/src/scenario_manager/cost_map_manager.py"
    click ScenarioMgr "https://github.com/alniyatrui/cafe-ad/blob/master/src/scenario_manager/scenario_manager.py"
    click ScenarioMgr "https://github.com/alniyatrui/cafe-ad/tree/master/src/scenario_manager/utils/"
    click Simulator "https://github.com/alniyatrui/cafe-ad/blob/master/run_simulation.py"
    click Simulator "https://github.com/alniyatrui/cafe-ad/blob/master/idm_simulation.py"
    click Simulator "https://github.com/alniyatrui/cafe-ad/blob/master/log_replay.py"
    click Config "https://github.com/alniyatrui/cafe-ad/blob/master/config/default_simulation.yaml"
    click Config "https://github.com/alniyatrui/cafe-ad/blob/master/config/planner/pluto_planner*.yaml"
    click ForwardSim "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/forward_simulation/forward_simulator.py"
    click ForwardSim "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/forward_simulation/batch_kinematic_bicycle.py"
    click ForwardSim "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/forward_simulation/batch_lqr.py"
    click ForwardSim "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/forward_simulation/batch_lqr_utils.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/observation/world_from_prediction.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/emergency_brake.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/trajectory_evaluator.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/post_processing/evaluation/comfort_metrics.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/metrics/min_ade.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/metrics/min_fde.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/metrics/mr.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/metrics/prediction_avg_ade.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/metrics/prediction_avg_fde.py"
    click Evaluation "https://github.com/alniyatrui/cafe-ad/blob/master/src/metrics/utils.py"
    click Visualization "https://github.com/alniyatrui/cafe-ad/blob/master/result.py"
    click Visualization "https://github.com/alniyatrui/cafe-ad/blob/master/src/utils/vis.py"

    %% Styles
    classDef external fill:#CCCCCC,stroke:#666,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef scripts fill:#EFEFEF,stroke:#555,stroke-width:1px
    classDef data fill:#D0E6F7,stroke:#333,stroke-width:1px
    classDef model fill:#C6E8B4,stroke:#333,stroke-width:1px
    classDef inference fill:#E1D5E7,stroke:#333,stroke-width:1px
    classDef post fill:#FDD0A2,stroke:#333,stroke-width:1px
```
