# rithwik-dudala/trajnex-26037 architecture

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

- Interactive diagram: https://gitdiagram.com/rithwik-dudala/trajnex-26037
- Repository: https://github.com/rithwik-dudala/trajnex-26037

## Overview

Trajnex is an autonomous-driving planning and collision-avoidance stack for unstructured Indian roads. Its principal workflow ingests a scenario or sensor frame, detects road users and drivable space, tracks and predicts motion, estimates uncertainty and dynamic risk, plans a route and local maneuver, then makes a driving decision and control command within simulation. It also supports video inference and an interactive dashboard. The README documents the major stage relationships; source excerpts and the index clarify component responsibilities, but do not expose every runtime call.

Main entry points: [`simulation/closed_loop_simulator.py`](https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/closed_loop_simulator.py) (Closed-Loop Simulator), [`tracking/byte_track.py`](https://github.com/rithwik-dudala/trajnex-26037/blob/main/tracking/byte_track.py) (Multi-Object Tracking), [`visualization/app.py`](https://github.com/rithwik-dudala/trajnex-26037/blob/main/visualization/app.py) (Interactive Dashboard), [`simulation/scenario_runner.py`](https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/scenario_runner.py) (Scenario Evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data and Scenarios"]
  node_idd["IDD Classes<br/>[idd_classes.py]"]
  node_scenario["Road Scenarios<br/>[scenarios.py]"]
  node_idd_loader["IDD Loader<br/>[idd_loader.py]"]
end

subgraph group_sensing["Perception and Prediction"]
  node_detector["Object Detector<br/>[detector.py]"]
  node_drivable["Drivable Area"]
  node_tracker["Multi-Object Tracking<br/>[byte_track.py]"]
  node_kalman_pred["Kalman Prediction"]
  node_lstm_pred["LSTM Prediction<br/>[lstm_predictor.py]"]
  node_uncertainty["Uncertainty Estimation"]
  node_video["Video Pipeline<br/>[video_pipeline.py]"]
end

subgraph group_navigation["Risk and Planning"]
  node_risk["Dynamic Risk Field"]
  node_hybrid["Hybrid A*<br/>[hybrid_astar.py]"]
  node_dwa["DWA Planner"]
  node_mpc["MPC Planner"]
end

subgraph group_actuation["Decision and Control"]
  node_fsm["Decision FSM<br/>[decision_fsm.py]"]
  node_controller["Vehicle Controllers"]
end

subgraph group_runtime["Simulation and Viewing"]
  node_simulator["Closed-Loop Simulator"]
  node_realtime["Realtime Simulator"]
  node_runner["Scenario Evaluation<br/>[scenario_runner.py]"]
  node_renderer["2D Renderer<br/>[render_2d.py]"]
  node_dashboard["Interactive Dashboard<br/>[app.py]"]
end

node_driver(("Engineer"))

node_scenario -->|"supplies scenarios"| node_simulator
node_simulator -->|"detects objects"| node_detector
node_simulator -->|"builds drivable mask"| node_drivable
node_detector -->|"provides detections"| node_tracker
node_tracker -->|"provides tracks"| node_kalman_pred
node_tracker -->|"provides tracks"| node_lstm_pred
node_simulator -->|"predicts motion"| node_kalman_pred
node_simulator -->|"predicts motion"| node_lstm_pred
node_simulator -->|"estimates uncertainty"| node_uncertainty
node_simulator -->|"computes risk"| node_risk
node_drivable -->|"sets boundaries"| node_risk
node_simulator -->|"plans global path"| node_hybrid
node_simulator -->|"plans local path"| node_dwa
node_risk -->|"scores trajectories"| node_dwa
node_simulator -->|"selects action"| node_fsm
node_simulator -->|"computes controls"| node_controller
node_simulator -->|"reads scenario"| node_scenario
node_runner -->|"runs scenarios"| node_simulator
node_runner -->|"selects benchmarks"| node_scenario
node_driver -->|"uses dashboard"| node_dashboard
node_dashboard -->|"runs simulation"| node_simulator
node_dashboard -->|"opens video workflow"| node_video
node_driver -->|"submits video"| node_video
node_idd_loader -.->|"supplies IDD frames"| node_video
node_simulator -->|"renders results"| node_renderer
node_driver -->|"starts benchmarks"| node_runner
node_idd -->|"defines road-user classes"| node_detector

click node_idd "https://github.com/rithwik-dudala/trajnex-26037/blob/main/data/idd_classes.py"
click node_scenario "https://github.com/rithwik-dudala/trajnex-26037/blob/main/data/scenarios.py"
click node_idd_loader "https://github.com/rithwik-dudala/trajnex-26037/blob/main/data/idd_loader.py"
click node_detector "https://github.com/rithwik-dudala/trajnex-26037/blob/main/perception/detector.py"
click node_drivable "https://github.com/rithwik-dudala/trajnex-26037/blob/main/perception/drivable_area_seg.py"
click node_tracker "https://github.com/rithwik-dudala/trajnex-26037/blob/main/tracking/byte_track.py"
click node_kalman_pred "https://github.com/rithwik-dudala/trajnex-26037/blob/main/prediction/kalman_predictor.py"
click node_lstm_pred "https://github.com/rithwik-dudala/trajnex-26037/blob/main/prediction/lstm_predictor.py"
click node_uncertainty "https://github.com/rithwik-dudala/trajnex-26037/blob/main/uncertainty/uncertainty_estimator.py"
click node_video "https://github.com/rithwik-dudala/trajnex-26037/blob/main/perception/video_pipeline.py"
click node_risk "https://github.com/rithwik-dudala/trajnex-26037/blob/main/risk_field/dynamic_risk_field.py"
click node_hybrid "https://github.com/rithwik-dudala/trajnex-26037/blob/main/planning/hybrid_astar.py"
click node_dwa "https://github.com/rithwik-dudala/trajnex-26037/blob/main/planning/dwa_local_planner.py"
click node_mpc "https://github.com/rithwik-dudala/trajnex-26037/blob/main/planning/mpc_local_planner.py"
click node_fsm "https://github.com/rithwik-dudala/trajnex-26037/blob/main/control/decision_fsm.py"
click node_controller "https://github.com/rithwik-dudala/trajnex-26037/blob/main/control/vehicle_controller.py"
click node_simulator "https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/closed_loop_simulator.py"
click node_realtime "https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/realtime_simulator.py"
click node_runner "https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/scenario_runner.py"
click node_renderer "https://github.com/rithwik-dudala/trajnex-26037/blob/main/visualization/render_2d.py"
click node_dashboard "https://github.com/rithwik-dudala/trajnex-26037/blob/main/visualization/app.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_idd,node_scenario,node_idd_loader toneBlue
class node_detector,node_drivable,node_tracker,node_kalman_pred,node_lstm_pred,node_uncertainty,node_video toneAmber
class node_risk,node_hybrid,node_dwa,node_mpc toneMint
class node_fsm,node_controller toneRose
class node_simulator,node_realtime,node_runner,node_renderer,node_dashboard,node_driver toneIndigo
```

## Components

### Data and Scenarios

- [IDD Classes](https://github.com/rithwik-dudala/trajnex-26037/blob/main/data/idd_classes.py): `data/idd_classes.py`
- [Road Scenarios](https://github.com/rithwik-dudala/trajnex-26037/blob/main/data/scenarios.py): `data/scenarios.py`
- [IDD Loader](https://github.com/rithwik-dudala/trajnex-26037/blob/main/data/idd_loader.py): `data/idd_loader.py`

### Perception and Prediction

- [Object Detector](https://github.com/rithwik-dudala/trajnex-26037/blob/main/perception/detector.py): `perception/detector.py`
- [Drivable Area](https://github.com/rithwik-dudala/trajnex-26037/blob/main/perception/drivable_area_seg.py): `perception/drivable_area_seg.py`
- [Multi-Object Tracking](https://github.com/rithwik-dudala/trajnex-26037/blob/main/tracking/byte_track.py): `tracking/byte_track.py`
- [Kalman Prediction](https://github.com/rithwik-dudala/trajnex-26037/blob/main/prediction/kalman_predictor.py): `prediction/kalman_predictor.py`
- [LSTM Prediction](https://github.com/rithwik-dudala/trajnex-26037/blob/main/prediction/lstm_predictor.py): `prediction/lstm_predictor.py`
- [Uncertainty Estimation](https://github.com/rithwik-dudala/trajnex-26037/blob/main/uncertainty/uncertainty_estimator.py): `uncertainty/uncertainty_estimator.py`
- [Video Pipeline](https://github.com/rithwik-dudala/trajnex-26037/blob/main/perception/video_pipeline.py): `perception/video_pipeline.py`

### Risk and Planning

- [Dynamic Risk Field](https://github.com/rithwik-dudala/trajnex-26037/blob/main/risk_field/dynamic_risk_field.py): `risk_field/dynamic_risk_field.py`
- [Hybrid A*](https://github.com/rithwik-dudala/trajnex-26037/blob/main/planning/hybrid_astar.py): `planning/hybrid_astar.py`
- [DWA Planner](https://github.com/rithwik-dudala/trajnex-26037/blob/main/planning/dwa_local_planner.py): `planning/dwa_local_planner.py`
- [MPC Planner](https://github.com/rithwik-dudala/trajnex-26037/blob/main/planning/mpc_local_planner.py): `planning/mpc_local_planner.py`

### Decision and Control

- [Decision FSM](https://github.com/rithwik-dudala/trajnex-26037/blob/main/control/decision_fsm.py): `control/decision_fsm.py`
- [Vehicle Controllers](https://github.com/rithwik-dudala/trajnex-26037/blob/main/control/vehicle_controller.py): `control/vehicle_controller.py`

### Simulation and Viewing

- [Closed-Loop Simulator](https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/closed_loop_simulator.py): `simulation/closed_loop_simulator.py`
- [Realtime Simulator](https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/realtime_simulator.py): `simulation/realtime_simulator.py`
- [Scenario Evaluation](https://github.com/rithwik-dudala/trajnex-26037/blob/main/simulation/scenario_runner.py): `simulation/scenario_runner.py`
- [2D Renderer](https://github.com/rithwik-dudala/trajnex-26037/blob/main/visualization/render_2d.py): `visualization/render_2d.py`
- [Interactive Dashboard](https://github.com/rithwik-dudala/trajnex-26037/blob/main/visualization/app.py): `visualization/app.py`

### Other components

- **Engineer**

## Connections

- Road Scenarios → Closed-Loop Simulator: supplies scenarios (evidence: `README.md`)
- Closed-Loop Simulator → Object Detector: detects objects (evidence: `README.md`)
- Closed-Loop Simulator → Drivable Area: builds drivable mask (evidence: `README.md`)
- Object Detector → Multi-Object Tracking: provides detections (evidence: `README.md`)
- Multi-Object Tracking → Kalman Prediction: provides tracks (evidence: `README.md`)
- Multi-Object Tracking → LSTM Prediction: provides tracks (evidence: `README.md`)
- Closed-Loop Simulator → Kalman Prediction: predicts motion (evidence: `README.md`)
- Closed-Loop Simulator → LSTM Prediction: predicts motion (evidence: `README.md`)
- Closed-Loop Simulator → Uncertainty Estimation: estimates uncertainty (evidence: `README.md`)
- Closed-Loop Simulator → Dynamic Risk Field: computes risk (evidence: `README.md`)
- Drivable Area → Dynamic Risk Field: sets boundaries (evidence: `risk_field/dynamic_risk_field.py`)
- Closed-Loop Simulator → Hybrid A*: plans global path (evidence: `README.md`)
- Closed-Loop Simulator → DWA Planner: plans local path (evidence: `README.md`)
- Dynamic Risk Field → DWA Planner: scores trajectories (evidence: `planning/dwa_local_planner.py`)
- Closed-Loop Simulator → Decision FSM: selects action (evidence: `README.md`)
- Closed-Loop Simulator → Vehicle Controllers: computes controls (evidence: `README.md`)
- Closed-Loop Simulator → Road Scenarios: reads scenario (evidence: `simulation/closed_loop_simulator.py`)
- Scenario Evaluation → Closed-Loop Simulator: runs scenarios (evidence: `simulation/scenario_runner.py`)
- Scenario Evaluation → Road Scenarios: selects benchmarks (evidence: `simulation/scenario_runner.py`)
- Engineer → Interactive Dashboard: uses dashboard (evidence: `README.md`)
- Interactive Dashboard → Closed-Loop Simulator: runs simulation (evidence: `visualization/app.py`)
- Interactive Dashboard → Video Pipeline: opens video workflow (evidence: `visualization/app.py`)
- Engineer → Video Pipeline: submits video (evidence: `README.md`)
- IDD Loader → Video Pipeline: supplies IDD frames
- Closed-Loop Simulator → 2D Renderer: renders results (evidence: `run_simulation.py`)
- Engineer → Scenario Evaluation: starts benchmarks (evidence: `README.md`)
- IDD Classes → Object Detector: defines road-user classes (evidence: `perception/detector.py`)