# rjtdeo/warp-av architecture

> Architecture diagram of the GitHub repository rjtdeo/warp-av, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rjtdeo/warp-av
- Repository: https://github.com/rjtdeo/warp-av
- Video tour (about a minute): https://gitdiagram.com/rjtdeo/warp-av/video

## Overview

Warp AV is a CARLA-based autonomous cargo-vehicle stack, with a single Python process running an approximately 10 Hz autonomy loop and serving an operator API/console. The main workflow is operator mission request → sensor acquisition and pose estimation → perception and world state → route/behavior decisions → safety supervision → vehicle control. Major documented branches include scenario execution and a separate reinforcement-learning parking environment. Relationships are limited to the README’s documented workflow and relationships visible in the supplied SOURCE INDEX; several subsystem internals were not sampled.

Main entry points: [`src/warp_av/main.py`](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/main.py) (Autonomy loop and API), [`src/warp_av/perception/camera_lidar_perception.py`](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/camera_lidar_perception.py) (Perception stack), [`src/warp_av/scenario_engine/runner.py`](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/runner.py) (Scenario runner), [`src/warp_av/adapters/carla_sensor_adapter.py`](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/adapters/carla_sensor_adapter.py) (Sensor adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Autonomy runtime"]
  node_main["Autonomy loop and API<br/>[main.py]"]
  node_mission["Mission management<br/>[mission_manager.py]"]
  node_console["Operator console"]
end

subgraph group_sensing["Sensing and state"]
  node_sensors["Sensor adapter"]
  node_pose["Pose source<br/>[pose_source.py]"]
  node_localization["Localization<br/>[localization.py]"]
  node_perception["Perception stack"]
  node_detection["Detection scheduler"]
  node_tracking["Object tracking<br/>[tracking.py]"]
  node_occupancy["Occupancy grid<br/>[occupancy.py]"]
  node_world["World model<br/>[world_model.py]"]
end

subgraph group_decision["Planning and control"]
  node_planner["Route and parking planner<br/>[planner.py]"]
  node_behavior["Behavior decisions<br/>[behavior.py]"]
  node_safety["Safety supervisor"]
  node_controller["Vehicle controller<br/>[controller.py]"]
  node_vehicle["Vehicle interface"]
end

subgraph group_validation["Scenarios and validation"]
  node_scenario["Scenario runner<br/>[runner.py]"]
  node_catalog["Scenario catalog<br/>[catalog.py]"]
  node_eval["Scenario evaluation<br/>[evaluator.py]"]
end

subgraph group_learning["Parking learning"]
  node_parking_env["Parking practice environment<br/>[parking_env.py]"]
  node_parking_math["Parking math and scoring<br/>[parking_math.py]"]
  node_parking_train["Parking training<br/>[train_parking.py]"]
end

node_operator(("Operator"))
node_carla["CARLA simulator"]

node_operator -->|"requests mission"| node_main
node_main -->|"serves console"| node_console
node_main -->|"manages mission"| node_mission
node_carla -->|"provides sensor data"| node_sensors
node_main -->|"reads sensors"| node_sensors
node_main -->|"estimates pose"| node_localization
node_sensors -->|"provides capture pose"| node_pose
node_localization -->|"uses pose source"| node_pose
node_main -->|"runs perception"| node_perception
node_perception -->|"schedules detections"| node_detection
node_perception -->|"tracks objects"| node_tracking
node_perception -->|"updates occupancy"| node_occupancy
node_main -->|"plans route"| node_planner
node_main -->|"decides behavior"| node_behavior
node_main -->|"checks safety"| node_safety
node_main -->|"computes commands"| node_controller
node_controller -->|"sends commands"| node_vehicle
node_vehicle -->|"actuates vehicle"| node_carla
node_operator -->|"runs scenarios"| node_scenario
node_scenario -->|"loads scenarios"| node_catalog
node_scenario -.->|"evaluates run"| node_eval
node_parking_env -->|"uses parking math"| node_parking_math
node_parking_train -.->|"trains in"| node_parking_env

click node_main "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/main.py"
click node_mission "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/mission/mission_manager.py"
click node_console "https://github.com/rjtdeo/warp-av/tree/master/src/warp_av/console"
click node_sensors "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/adapters/carla_sensor_adapter.py"
click node_pose "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/localization/pose_source.py"
click node_localization "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/localization/localization.py"
click node_perception "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/camera_lidar_perception.py"
click node_detection "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/detection_worker.py"
click node_tracking "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/tracking.py"
click node_occupancy "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/occupancy.py"
click node_world "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/world_model.py"
click node_planner "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/planning/planner.py"
click node_behavior "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/behavior/behavior.py"
click node_safety "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/safety/safety_supervisor.py"
click node_controller "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/control/controller.py"
click node_vehicle "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/vehicle_interface.py"
click node_scenario "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/runner.py"
click node_catalog "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/catalog.py"
click node_eval "https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/evaluator.py"
click node_parking_env "https://github.com/rjtdeo/warp-av/blob/master/rl/parking_env.py"
click node_parking_math "https://github.com/rjtdeo/warp-av/blob/master/rl/parking_math.py"
click node_parking_train "https://github.com/rjtdeo/warp-av/blob/master/rl/train_parking.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_main,node_mission,node_console toneBlue
class node_sensors,node_pose,node_localization,node_perception,node_detection,node_tracking,node_occupancy,node_world toneAmber
class node_planner,node_behavior,node_safety,node_controller,node_vehicle toneMint
class node_scenario,node_catalog,node_eval toneRose
class node_parking_env,node_parking_math,node_parking_train,node_operator,node_carla toneIndigo
```

## Components

### Autonomy runtime

- [Autonomy loop and API](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/main.py): `src/warp_av/main.py`
- [Mission management](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/mission/mission_manager.py): `src/warp_av/mission/mission_manager.py`
- [Operator console](https://github.com/rjtdeo/warp-av/tree/master/src/warp_av/console): `src/warp_av/console`

### Sensing and state

- [Sensor adapter](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/adapters/carla_sensor_adapter.py): `src/warp_av/adapters/carla_sensor_adapter.py`
- [Pose source](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/localization/pose_source.py): `src/warp_av/localization/pose_source.py`
- [Localization](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/localization/localization.py): `src/warp_av/localization/localization.py`
- [Perception stack](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/camera_lidar_perception.py): `src/warp_av/perception/camera_lidar_perception.py`
- [Detection scheduler](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/detection_worker.py): `src/warp_av/perception/detection_worker.py`
- [Object tracking](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/tracking.py): `src/warp_av/perception/tracking.py`
- [Occupancy grid](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/perception/occupancy.py): `src/warp_av/perception/occupancy.py`
- [World model](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/world_model.py): `src/warp_av/world_model.py`

### Planning and control

- [Route and parking planner](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/planning/planner.py): `src/warp_av/planning/planner.py`
- [Behavior decisions](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/behavior/behavior.py): `src/warp_av/behavior/behavior.py`
- [Safety supervisor](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/safety/safety_supervisor.py): `src/warp_av/safety/safety_supervisor.py`
- [Vehicle controller](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/control/controller.py): `src/warp_av/control/controller.py`
- [Vehicle interface](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/vehicle_interface.py): `src/warp_av/vehicle_interface.py`

### Scenarios and validation

- [Scenario runner](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/runner.py): `src/warp_av/scenario_engine/runner.py`
- [Scenario catalog](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/catalog.py): `src/warp_av/scenario_engine/catalog.py`
- [Scenario evaluation](https://github.com/rjtdeo/warp-av/blob/master/src/warp_av/scenario_engine/evaluator.py): `src/warp_av/scenario_engine/evaluator.py`

### Parking learning

- [Parking practice environment](https://github.com/rjtdeo/warp-av/blob/master/rl/parking_env.py): `rl/parking_env.py`
- [Parking math and scoring](https://github.com/rjtdeo/warp-av/blob/master/rl/parking_math.py): `rl/parking_math.py`
- [Parking training](https://github.com/rjtdeo/warp-av/blob/master/rl/train_parking.py): `rl/train_parking.py`

### Other components

- **Operator**
- **CARLA simulator**

## Connections

- Operator → Autonomy loop and API: requests mission (evidence: `README.md`)
- Autonomy loop and API → Operator console: serves console (evidence: `README.md`)
- Autonomy loop and API → Mission management: manages mission (evidence: `README.md`)
- CARLA simulator → Sensor adapter: provides sensor data (evidence: `README.md`)
- Autonomy loop and API → Sensor adapter: reads sensors (evidence: `README.md`)
- Autonomy loop and API → Localization: estimates pose (evidence: `src/warp_av/main.py`)
- Sensor adapter → Pose source: provides capture pose (evidence: `src/warp_av/adapters/carla_sensor_adapter.py`)
- Localization → Pose source: uses pose source (evidence: `src/warp_av/localization/localization.py`)
- Autonomy loop and API → Perception stack: runs perception (evidence: `src/warp_av/main.py`)
- Perception stack → Detection scheduler: schedules detections (evidence: `src/warp_av/perception/camera_lidar_perception.py`)
- Perception stack → Object tracking: tracks objects (evidence: `src/warp_av/perception/camera_lidar_perception.py`)
- Perception stack → Occupancy grid: updates occupancy (evidence: `src/warp_av/perception/camera_lidar_perception.py`)
- Autonomy loop and API → Route and parking planner: plans route (evidence: `src/warp_av/main.py`)
- Autonomy loop and API → Behavior decisions: decides behavior (evidence: `src/warp_av/main.py`)
- Autonomy loop and API → Safety supervisor: checks safety (evidence: `README.md`)
- Autonomy loop and API → Vehicle controller: computes commands (evidence: `README.md`)
- Vehicle controller → Vehicle interface: sends commands (evidence: `src/warp_av/control/controller.py`)
- Vehicle interface → CARLA simulator: actuates vehicle (evidence: `README.md`)
- Operator → Scenario runner: runs scenarios (evidence: `README.md`)
- Scenario runner → Scenario catalog: loads scenarios (evidence: `scenarios/run_scenario.py`)
- Scenario runner → Scenario evaluation: evaluates run
- Parking practice environment → Parking math and scoring: uses parking math (evidence: `rl/parking_env.py`)
- Parking training → Parking practice environment: trains in