# spa-junghokim/safedrive architecture

> Architecture diagram of the GitHub repository spa-junghokim/safedrive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spa-junghokim/safedrive
- Repository: https://github.com/spa-junghokim/safedrive

## Overview

SafeDrive is a NAVSIM end-to-end driving agent with perception, planning, and fine-grained safety reasoning. Its main workflow builds scenario features, runs the SafeDrive model to predict a plan, and evaluates predictions with PDM scoring. Training includes dataset/feature-target processing and, as documented, PDM-simulator rollouts for safety supervision; metric caching and visualization are supporting product capabilities. Several runtime modules are unsampled, so links to them are shown only where the README or source index supports them.

Main entry points: [`navsim/agents/safedrive/safedrive_model.py`](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_model.py) (SafeDrive model), [`navsim/agents/safedrive/safedrive_features.py`](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_features.py) (Feature builders), [`navsim/planning/training/agent_lightning_module.py`](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/training/agent_lightning_module.py) (Training module), [`navsim/agents/safedrive/safedrive_agent.py`](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_agent.py) (SafeDrive agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["SafeDrive Agent"]
  node_features["Feature builders"]
  node_agent_runtime["SafeDrive agent<br/>[safedrive_agent.py]"]
  node_model["SafeDrive model<br/>[safedrive_model.py]"]
  node_backbone["BEV backbone"]
  node_transformers["Detection and motion modules"]
  node_loss["Safety and planning loss<br/>[safedrive_loss.py]"]
end

subgraph group_data["NAVSIM Data"]
  node_scenario["Scenario builder<br/>[navsim_scenario.py]"]
  node_scenario_utils["Scenario utilities"]
  node_data_types["Sensor and trajectory data<br/>[dataclasses.py]"]
end

subgraph group_planning["PDM Planning"]
  node_observation["PDM observations<br/>[pdm_observation.py]"]
  node_proposals["Trajectory proposals<br/>[pdm_generator.py]"]
  node_simulator["PDM simulator<br/>[pdm_simulator.py]"]
  node_scorer["PDM scorer<br/>[pdm_scorer.py]"]
end

subgraph group_workflows["Training and Evaluation"]
  node_dataset["Training dataset<br/>[dataset.py]"]
  node_training_module["Training module"]
  node_cache[("Metric caching")]
  node_evaluation["PDM evaluation<br/>[pdm_score.py]"]
  node_visualization["Scene visualization<br/>[bev.py]"]
end

node_user(("Agent user"))

node_user -.->|"requests trajectory"| node_agent_runtime
node_agent_runtime -.->|"builds features"| node_features
node_features -->|"uses scenario data"| node_scenario_utils
node_scenario -->|"uses utilities"| node_scenario_utils
node_features -->|"produces inputs"| node_data_types
node_agent_runtime -.->|"runs inference"| node_model
node_model -->|"builds BEV features"| node_backbone
node_model -->|"uses transformers"| node_transformers
node_model -->|"consumes features"| node_features
node_model -.->|"trains with loss"| node_loss
node_dataset -->|"loads samples"| node_data_types
node_dataset -.->|"builds targets"| node_scenario
node_training_module -.->|"trains agent"| node_model
node_training_module -.->|"computes loss"| node_loss
node_training_module -.->|"rolls out plans"| node_simulator
node_observation -->|"indexes occupancy maps"| node_observation
node_proposals -->|"reads observations"| node_observation
node_evaluation -->|"simulates trajectory"| node_simulator
node_evaluation -->|"scores trajectory"| node_scorer
node_cache -->|"computes cached metrics"| node_scorer
node_visualization -->|"uses scene geometry"| node_scenario_utils

click node_scenario "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/scenario_builder/navsim_scenario.py"
click node_scenario_utils "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/scenario_builder/navsim_scenario_utils.py"
click node_data_types "https://github.com/spa-junghokim/safedrive/blob/main/navsim/common/dataclasses.py"
click node_features "https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_features.py"
click node_agent_runtime "https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_agent.py"
click node_model "https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_model.py"
click node_backbone "https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_backbone.py"
click node_transformers "https://github.com/spa-junghokim/safedrive/tree/main/navsim/agents/safedrive/modules"
click node_loss "https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_loss.py"
click node_dataset "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/training/dataset.py"
click node_training_module "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/training/agent_lightning_module.py"
click node_cache "https://github.com/spa-junghokim/safedrive/tree/main/navsim/planning/metric_caching"
click node_observation "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py"
click node_proposals "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/proposal/pdm_generator.py"
click node_simulator "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py"
click node_scorer "https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py"
click node_evaluation "https://github.com/spa-junghokim/safedrive/blob/main/navsim/evaluate/pdm_score.py"
click node_visualization "https://github.com/spa-junghokim/safedrive/blob/main/navsim/visualization/bev.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_features,node_agent_runtime,node_model,node_backbone,node_transformers,node_loss,node_user toneBlue
class node_scenario,node_scenario_utils,node_data_types toneAmber
class node_observation,node_proposals,node_simulator,node_scorer toneMint
class node_dataset,node_training_module,node_cache,node_evaluation,node_visualization toneRose
```

## Components

### SafeDrive Agent

- [Feature builders](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_features.py): `navsim/agents/safedrive/safedrive_features.py`
- [SafeDrive agent](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_agent.py): `navsim/agents/safedrive/safedrive_agent.py`
- [SafeDrive model](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_model.py): `navsim/agents/safedrive/safedrive_model.py`
- [BEV backbone](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_backbone.py): `navsim/agents/safedrive/safedrive_backbone.py`
- [Detection and motion modules](https://github.com/spa-junghokim/safedrive/tree/main/navsim/agents/safedrive/modules): `navsim/agents/safedrive/modules`
- [Safety and planning loss](https://github.com/spa-junghokim/safedrive/blob/main/navsim/agents/safedrive/safedrive_loss.py): `navsim/agents/safedrive/safedrive_loss.py`

### NAVSIM Data

- [Scenario builder](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/scenario_builder/navsim_scenario.py): `navsim/planning/scenario_builder/navsim_scenario.py`
- [Scenario utilities](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/scenario_builder/navsim_scenario_utils.py): `navsim/planning/scenario_builder/navsim_scenario_utils.py`
- [Sensor and trajectory data](https://github.com/spa-junghokim/safedrive/blob/main/navsim/common/dataclasses.py): `navsim/common/dataclasses.py`

### PDM Planning

- [PDM observations](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py): `navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py`
- [Trajectory proposals](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/proposal/pdm_generator.py): `navsim/planning/simulation/planner/pdm_planner/proposal/pdm_generator.py`
- [PDM simulator](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py): `navsim/planning/simulation/planner/pdm_planner/simulation/pdm_simulator.py`
- [PDM scorer](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py): `navsim/planning/simulation/planner/pdm_planner/scoring/pdm_scorer.py`

### Training and Evaluation

- [Training dataset](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/training/dataset.py): `navsim/planning/training/dataset.py`
- [Training module](https://github.com/spa-junghokim/safedrive/blob/main/navsim/planning/training/agent_lightning_module.py): `navsim/planning/training/agent_lightning_module.py`
- [Metric caching](https://github.com/spa-junghokim/safedrive/tree/main/navsim/planning/metric_caching): `navsim/planning/metric_caching`
- [PDM evaluation](https://github.com/spa-junghokim/safedrive/blob/main/navsim/evaluate/pdm_score.py): `navsim/evaluate/pdm_score.py`
- [Scene visualization](https://github.com/spa-junghokim/safedrive/blob/main/navsim/visualization/bev.py): `navsim/visualization/bev.py`

### Other components

- **Agent user**

## Connections

- Agent user → SafeDrive agent: requests trajectory
- SafeDrive agent → Feature builders: builds features
- Feature builders → Scenario utilities: uses scenario data (evidence: `navsim/agents/safedrive/safedrive_features.py`)
- Scenario builder → Scenario utilities: uses utilities (evidence: `navsim/planning/scenario_builder/navsim_scenario.py`)
- Feature builders → Sensor and trajectory data: produces inputs (evidence: `navsim/agents/safedrive/safedrive_features.py`)
- SafeDrive agent → SafeDrive model: runs inference
- SafeDrive model → BEV backbone: builds BEV features (evidence: `navsim/agents/safedrive/safedrive_model.py`)
- SafeDrive model → Detection and motion modules: uses transformers (evidence: `navsim/agents/safedrive/safedrive_model.py`)
- SafeDrive model → Feature builders: consumes features (evidence: `navsim/agents/safedrive/safedrive_model.py`)
- SafeDrive model → Safety and planning loss: trains with loss
- Training dataset → Sensor and trajectory data: loads samples
- Training dataset → Scenario builder: builds targets
- Training module → SafeDrive model: trains agent
- Training module → Safety and planning loss: computes loss
- Training module → PDM simulator: rolls out plans (evidence: `README.md`)
- PDM observations → PDM observations: indexes occupancy maps (evidence: `navsim/planning/simulation/planner/pdm_planner/observation/pdm_observation.py`)
- Trajectory proposals → PDM observations: reads observations (evidence: `navsim/planning/simulation/planner/pdm_planner/proposal/pdm_generator.py`)
- PDM evaluation → PDM simulator: simulates trajectory (evidence: `navsim/evaluate/pdm_score.py`)
- PDM evaluation → PDM scorer: scores trajectory (evidence: `navsim/evaluate/pdm_score.py`)
- Metric caching → PDM scorer: computes cached metrics (evidence: `navsim/planning/metric_caching/train_cache_processor.py`)
- Scene visualization → Scenario utilities: uses scene geometry (evidence: `navsim/visualization/bev.py`)
