# zzr005119/carla-extreme-scenario-generator architecture

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

- Interactive diagram: https://gitdiagram.com/zzr005119/carla-extreme-scenario-generator
- Repository: https://github.com/zzr005119/carla-extreme-scenario-generator

## Overview

This repository is a CARLA-oriented scenario generation and adversarial testing toolkit. A typical workflow creates or selects parameterized scenarios, validates them, runs or registers simulation work, then analyzes risk and feeds results into candidate selection or a scenario library. It also provides conditional-model training, library querying, and a local web interface. The README is empty; relationships below rely on shown excerpts and SOURCE INDEX references, so unsampled implementation details are not inferred.

Main entry points: [`core/scenario_features.py`](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_features.py) (Feature encoding), [`tools/evaluate_adversarial_baselines.py`](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/evaluate_adversarial_baselines.py) (Baseline evaluation), [`core/web_task_orchestrator.py`](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/web_task_orchestrator.py) (Task orchestration), [`core/scenario_validator.py`](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_validator.py) (Validation and compile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Scenario generation"]
  node_scenario_features["Feature encoding"]
  node_scenario_validator["Validation and compile"]
  node_conditional_models["Conditional generators<br/>[conditional_gmm.py]"]
  node_cvae_training["CVAE training<br/>[train_cvae.py]"]
  node_scenario_dataset["Training dataset"]
end

subgraph group_testing["Adversarial testing"]
  node_adversarial_agent["Candidate agent"]
  node_adversarial_loop["Adversarial loop"]
  node_adversarial_sampling["Candidate sampling"]
  node_gym_env["Gym environment"]
  node_proxy_executor["Proxy executor"]
end

subgraph group_simulation["Simulation and evidence"]
  node_scene_runner["CARLA scenes"]
  node_sensor_pipeline["Sensor writing<br/>[sensor_pipeline.py]"]
  node_risk_metrics["Risk metrics<br/>[risk_metrics.py]"]
end

subgraph group_library["Scenario library"]
  node_scenario_library[("Scenario library")]
  node_scenario_query["Library query<br/>[scenario_query.py]"]
  node_feedback_scoring["Candidate scoring"]
end

subgraph group_interfaces["Interfaces and analysis"]
  node_query_cli["Query command"]
  node_web_app["Web application<br/>[web_app.py]"]
  node_task_orchestrator["Task orchestration"]
  node_dashboard["Scenario dashboard"]
  node_baseline_eval["Baseline evaluation"]
  node_repeatability_analysis["Repeatability analysis"]
end

node_user(("Engineer"))
node_carla(("CARLA service"))

node_user -->|"uses"| node_web_app
node_web_app -->|"routes to"| node_dashboard
node_web_app -->|"submits tasks"| node_task_orchestrator
node_task_orchestrator -->|"validates"| node_scenario_validator
node_task_orchestrator -->|"analyzes risk"| node_risk_metrics
node_task_orchestrator -->|"registers external run"| node_carla
node_task_orchestrator -.-> node_scenario_library
node_user -->|"queries"| node_query_cli
node_query_cli -->|"matches entries"| node_scenario_query
node_dashboard -->|"queries"| node_scenario_query
node_dashboard -->|"uses"| node_query_cli
node_scenario_library -->|"uses encoding"| node_scenario_features
node_scenario_library -->|"validates records"| node_scenario_validator
node_feedback_scoring -->|"uses features"| node_scenario_features
node_feedback_scoring -->|"validates candidates"| node_scenario_validator
node_conditional_models -->|"encodes records"| node_scenario_features
node_cvae_training -->|"loads arrays"| node_scenario_dataset
node_cvae_training -->|"trains model"| node_conditional_models
node_cvae_training -->|"uses feature schema"| node_scenario_features
node_scenario_dataset -->|"converts records"| node_scenario_features
node_adversarial_agent -->|"uses features"| node_scenario_features
node_adversarial_agent -->|"validates candidates"| node_scenario_validator
node_baseline_eval -->|"evaluates"| node_adversarial_agent
node_baseline_eval -->|"runs loop"| node_adversarial_loop
node_baseline_eval -->|"samples candidates"| node_adversarial_sampling
node_baseline_eval -->|"uses features"| node_scenario_features
node_baseline_eval -->|"validates scenarios"| node_scenario_validator
node_scene_runner -->|"uses risk metrics"| node_risk_metrics
node_scene_runner -.->|"writes sensor data"| node_sensor_pipeline
node_carla -.->|"simulates"| node_scene_runner
node_repeatability_analysis -.->|"analyzes run evidence"| node_carla

click node_scenario_features "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_features.py"
click node_scenario_validator "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_validator.py"
click node_conditional_models "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/models/conditional_gmm.py"
click node_cvae_training "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/training/train_cvae.py"
click node_scenario_dataset "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/training/scenario_dataset.py"
click node_adversarial_agent "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_agent.py"
click node_adversarial_loop "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_loop.py"
click node_adversarial_sampling "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_sampling.py"
click node_gym_env "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_gym_env.py"
click node_proxy_executor "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_proxy_executor.py"
click node_scene_runner "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/scenes/scene_04_parameterized.py"
click node_sensor_pipeline "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/sensor_pipeline.py"
click node_risk_metrics "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/risk_metrics.py"
click node_scenario_library "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_library.py"
click node_scenario_query "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_query.py"
click node_feedback_scoring "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/analysis/score_feedback_candidates.py"
click node_query_cli "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/query_scenario_library.py"
click node_web_app "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/web_app.py"
click node_task_orchestrator "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/web_task_orchestrator.py"
click node_dashboard "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/scenario_dashboard.py"
click node_baseline_eval "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/evaluate_adversarial_baselines.py"
click node_repeatability_analysis "https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/analysis/analyze_carla_repeatability.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_scenario_features,node_scenario_validator,node_conditional_models,node_cvae_training,node_scenario_dataset toneBlue
class node_adversarial_agent,node_adversarial_loop,node_adversarial_sampling,node_gym_env,node_proxy_executor toneAmber
class node_scene_runner,node_sensor_pipeline,node_risk_metrics toneMint
class node_scenario_library,node_scenario_query,node_feedback_scoring toneRose
class node_query_cli,node_web_app,node_task_orchestrator,node_dashboard,node_baseline_eval,node_repeatability_analysis,node_user,node_carla toneIndigo
```

## Components

### Scenario generation

- [Feature encoding](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_features.py): `core/scenario_features.py`
- [Validation and compile](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_validator.py): `core/scenario_validator.py`
- [Conditional generators](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/models/conditional_gmm.py): `models/conditional_gmm.py`
- [CVAE training](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/training/train_cvae.py): `training/train_cvae.py`
- [Training dataset](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/training/scenario_dataset.py): `training/scenario_dataset.py`

### Adversarial testing

- [Candidate agent](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_agent.py): `core/adversarial_agent.py`
- [Adversarial loop](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_loop.py): `core/adversarial_loop.py`
- [Candidate sampling](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_sampling.py): `core/adversarial_sampling.py`
- [Gym environment](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_gym_env.py): `core/adversarial_gym_env.py`
- [Proxy executor](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/adversarial_proxy_executor.py): `core/adversarial_proxy_executor.py`

### Simulation and evidence

- [CARLA scenes](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/scenes/scene_04_parameterized.py): `scenes/scene_04_parameterized.py`
- [Sensor writing](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/sensor_pipeline.py): `core/sensor_pipeline.py`
- [Risk metrics](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/risk_metrics.py): `core/risk_metrics.py`

### Scenario library

- [Scenario library](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_library.py): `core/scenario_library.py`
- [Library query](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/scenario_query.py): `core/scenario_query.py`
- [Candidate scoring](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/analysis/score_feedback_candidates.py): `analysis/score_feedback_candidates.py`

### Interfaces and analysis

- [Query command](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/query_scenario_library.py): `tools/query_scenario_library.py`
- [Web application](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/web_app.py): `tools/web_app.py`
- [Task orchestration](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/core/web_task_orchestrator.py): `core/web_task_orchestrator.py`
- [Scenario dashboard](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/scenario_dashboard.py): `tools/scenario_dashboard.py`
- [Baseline evaluation](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/tools/evaluate_adversarial_baselines.py): `tools/evaluate_adversarial_baselines.py`
- [Repeatability analysis](https://github.com/zzr005119/carla-extreme-scenario-generator/blob/main/analysis/analyze_carla_repeatability.py): `analysis/analyze_carla_repeatability.py`

### Other components

- **Engineer**
- **CARLA service**

## Connections

- Engineer → Web application: uses (evidence: `tools/web_app.py`)
- Web application → Scenario dashboard: routes to (evidence: `tools/web_app.py`)
- Web application → Task orchestration: submits tasks (evidence: `tools/web_app.py`)
- Task orchestration → Validation and compile: validates (evidence: `core/web_task_orchestrator.py`)
- Task orchestration → Risk metrics: analyzes risk (evidence: `core/web_task_orchestrator.py`)
- Task orchestration → CARLA service: registers external run (evidence: `core/web_task_orchestrator.py`)
- Task orchestration → Scenario library
- Engineer → Query command: queries (evidence: `tools/query_scenario_library.py`)
- Query command → Library query: matches entries (evidence: `tools/query_scenario_library.py`)
- Scenario dashboard → Library query: queries (evidence: `tools/scenario_dashboard.py`)
- Scenario dashboard → Query command: uses (evidence: `tools/scenario_dashboard.py`)
- Scenario library → Feature encoding: uses encoding (evidence: `core/scenario_library.py`)
- Scenario library → Validation and compile: validates records (evidence: `core/scenario_library.py`)
- Candidate scoring → Feature encoding: uses features (evidence: `analysis/score_feedback_candidates.py`)
- Candidate scoring → Validation and compile: validates candidates (evidence: `analysis/score_feedback_candidates.py`)
- Conditional generators → Feature encoding: encodes records (evidence: `models/conditional_gmm.py`)
- CVAE training → Training dataset: loads arrays (evidence: `training/train_cvae.py`)
- CVAE training → Conditional generators: trains model (evidence: `training/train_cvae.py`)
- CVAE training → Feature encoding: uses feature schema (evidence: `training/train_cvae.py`)
- Training dataset → Feature encoding: converts records (evidence: `training/scenario_dataset.py`)
- Candidate agent → Feature encoding: uses features (evidence: `core/adversarial_agent.py`)
- Candidate agent → Validation and compile: validates candidates (evidence: `core/adversarial_agent.py`)
- Baseline evaluation → Candidate agent: evaluates (evidence: `tools/evaluate_adversarial_baselines.py`)
- Baseline evaluation → Adversarial loop: runs loop (evidence: `tools/evaluate_adversarial_baselines.py`)
- Baseline evaluation → Candidate sampling: samples candidates (evidence: `tools/evaluate_adversarial_baselines.py`)
- Baseline evaluation → Feature encoding: uses features (evidence: `tools/evaluate_adversarial_baselines.py`)
- Baseline evaluation → Validation and compile: validates scenarios (evidence: `tools/evaluate_adversarial_baselines.py`)
- CARLA scenes → Risk metrics: uses risk metrics (evidence: `scenes/scene_04_parameterized.py`)
- CARLA scenes → Sensor writing: writes sensor data (evidence: `scenes/scene_04_parameterized.py`)
- CARLA service → CARLA scenes: simulates
- Repeatability analysis → CARLA service: analyzes run evidence
