# ujjwal-qubit/run_time_terror architecture

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

- Interactive diagram: https://gitdiagram.com/ujjwal-qubit/run_time_terror
- Repository: https://github.com/ujjwal-qubit/run_time_terror

## Overview

LumiTrack is a virtual-camera tracking testbed and algorithm evaluation platform. Its main workflow configures a simulation or MP4 run, produces observed frames, runs a tracking algorithm, optionally steers the virtual PTZ camera, and records benchmark metrics and results. The README documents the tracking pipeline, ground-truth firewall, and two benchmark modes; sampled source confirms controller orchestration, disturbance processing, detection, PTZ, metrics, and API behavior. Some subsystem links are omitted where their callers were not shown.

Main entry points: [`src/app/app_controller.py`](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/app_controller.py) (Application Controller), [`src/evaluation/benchmark_manager.py`](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/evaluation/benchmark_manager.py) (Benchmark Manager), [`src/plugins/algorithms/baseline_tracker/baseline_tracker.py`](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/plugins/algorithms/baseline_tracker/baseline_tracker.py) (Baseline Tracker), [`src/api/server.py`](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/api/server.py) (REST and WebSocket API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Interfaces"]
  node_frontend["Web Frontend<br/>[App.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_api_server["REST and WebSocket API<br/>[server.py]"]
  node_desktop_ui["Desktop GUI<br/>[main_window.py]"]
  node_entrypoint["CLI Entry<br/>[main.py]"]
  node_visualization["Visualization"]
  node_results_ui["Results Views<br/>[ResultsPage.tsx]"]
end

subgraph group_runtime["Run Orchestration"]
  node_controller["Application Controller<br/>[app_controller.py]"]
  node_configuration["Configuration<br/>[config_manager.py]"]
  node_scenarios["Scenario Manager"]
end

subgraph group_sources["Frame Sources"]
  node_simulation["Simulation World<br/>[scene_manager.py]"]
  node_target_motion["Target Motion<br/>[target_manager.py]"]
  node_disturbances["Disturbance Engine"]
  node_frame_sources["Simulation and MP4 Frames"]
  node_ground_truth["Ground Truth"]
end

subgraph group_tracking["Tracking and Control"]
  node_plugin_system["Algorithm Plugins<br/>[loader.py]"]
  node_baseline["Baseline Tracker"]
  node_detection["Beacon Detection"]
  node_temporal_tracking["Temporal Tracking"]
  node_ptz["PTZ Control<br/>[ptz_controller.py]"]
end

subgraph group_evaluation["Evaluation and Results"]
  node_benchmark["Benchmark Manager"]
  node_ai_scenarios["AI Scenario Workflow<br/>[ai_scenario.py]"]
  node_metrics["Metrics Engine<br/>[metrics_engine.py]"]
  node_logging["Telemetry Logging<br/>[logging_engine.py]"]
end

node_operator(("Operator"))

node_operator -->|"operates"| node_frontend
node_frontend -->|"requests"| node_api_client
node_api_client -->|"calls"| node_api_server
node_api_server -->|"controls"| node_controller
node_operator -->|"operates"| node_desktop_ui
node_desktop_ui -->|"controls"| node_controller
node_operator -->|"invokes"| node_entrypoint
node_entrypoint -->|"initializes"| node_controller
node_controller -->|"loads"| node_configuration
node_controller -->|"manages"| node_scenarios
node_scenarios -->|"loads and saves"| node_configuration
node_controller -->|"advances"| node_target_motion
node_controller -->|"applies"| node_disturbances
node_controller -->|"renders"| node_simulation
node_controller -->|"gets frames"| node_frame_sources
node_frame_sources -->|"provides frames"| node_baseline
node_controller -->|"discovers algorithms"| node_plugin_system
node_plugin_system -->|"loads plugin"| node_baseline
node_baseline -->|"detects candidates"| node_detection
node_baseline -->|"tracks candidates"| node_temporal_tracking
node_controller -->|"computes commands"| node_ptz
node_controller -->|"runs benchmark"| node_benchmark
node_benchmark -->|"evaluates frames"| node_frame_sources
node_benchmark -->|"reads truth"| node_ground_truth
node_benchmark -->|"records metrics"| node_metrics
node_benchmark -->|"dispatches prompts"| node_ai_scenarios
node_ai_scenarios -->|"executes evaluation"| node_benchmark
node_controller -->|"records telemetry"| node_logging
node_controller -->|"renders view state"| node_visualization
node_api_server -->|"streams results"| node_results_ui

click node_frontend "https://github.com/ujjwal-qubit/run_time_terror/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/ujjwal-qubit/run_time_terror/blob/main/frontend/src/api/client.ts"
click node_api_server "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/api/server.py"
click node_desktop_ui "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/gui/main_window.py"
click node_entrypoint "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/main.py"
click node_controller "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/app_controller.py"
click node_configuration "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/config/config_manager.py"
click node_scenarios "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/config/scenario_manager.py"
click node_simulation "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/scene_manager.py"
click node_target_motion "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/target_manager.py"
click node_disturbances "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/disturbance_engine.py"
click node_frame_sources "https://github.com/ujjwal-qubit/run_time_terror/tree/main/src/frame"
click node_ground_truth "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/ground_truth_provider.py"
click node_plugin_system "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/plugins/loader.py"
click node_baseline "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/plugins/algorithms/baseline_tracker/baseline_tracker.py"
click node_detection "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/tracker/detection_engine.py"
click node_temporal_tracking "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/tracker/temporal_tracker.py"
click node_ptz "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/control/ptz_controller.py"
click node_benchmark "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/evaluation/benchmark_manager.py"
click node_ai_scenarios "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/evaluation/ai_scenario.py"
click node_metrics "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/metrics/metrics_engine.py"
click node_logging "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/metrics/logging_engine.py"
click node_visualization "https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/visualization_engine.py"
click node_results_ui "https://github.com/ujjwal-qubit/run_time_terror/blob/main/frontend/src/components/results/ResultsPage.tsx"

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_frontend,node_api_client,node_api_server,node_desktop_ui,node_entrypoint,node_visualization,node_results_ui toneBlue
class node_controller,node_configuration,node_scenarios toneAmber
class node_simulation,node_target_motion,node_disturbances,node_frame_sources,node_ground_truth toneMint
class node_plugin_system,node_baseline,node_detection,node_temporal_tracking,node_ptz toneRose
class node_benchmark,node_ai_scenarios,node_metrics,node_logging,node_operator toneIndigo
```

## Components

### User Interfaces

- [Web Frontend](https://github.com/ujjwal-qubit/run_time_terror/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/ujjwal-qubit/run_time_terror/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [REST and WebSocket API](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/api/server.py): `src/api/server.py`
- [Desktop GUI](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/gui/main_window.py): `src/app/gui/main_window.py`
- [CLI Entry](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/main.py): `src/main.py`
- [Visualization](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/visualization_engine.py): `src/app/visualization_engine.py`
- [Results Views](https://github.com/ujjwal-qubit/run_time_terror/blob/main/frontend/src/components/results/ResultsPage.tsx): `frontend/src/components/results/ResultsPage.tsx`

### Run Orchestration

- [Application Controller](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/app/app_controller.py): `src/app/app_controller.py`
- [Configuration](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/config/config_manager.py): `src/config/config_manager.py`
- [Scenario Manager](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/config/scenario_manager.py): `src/config/scenario_manager.py`

### Frame Sources

- [Simulation World](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/scene_manager.py): `src/simulation/scene_manager.py`
- [Target Motion](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/target_manager.py): `src/simulation/target_manager.py`
- [Disturbance Engine](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/disturbance_engine.py): `src/simulation/disturbance_engine.py`
- [Simulation and MP4 Frames](https://github.com/ujjwal-qubit/run_time_terror/tree/main/src/frame): `src/frame`
- [Ground Truth](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/simulation/ground_truth_provider.py): `src/simulation/ground_truth_provider.py`

### Tracking and Control

- [Algorithm Plugins](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/plugins/loader.py): `src/plugins/loader.py`
- [Baseline Tracker](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/plugins/algorithms/baseline_tracker/baseline_tracker.py): `src/plugins/algorithms/baseline_tracker/baseline_tracker.py`
- [Beacon Detection](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/tracker/detection_engine.py): `src/tracker/detection_engine.py`
- [Temporal Tracking](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/tracker/temporal_tracker.py): `src/tracker/temporal_tracker.py`
- [PTZ Control](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/control/ptz_controller.py): `src/control/ptz_controller.py`

### Evaluation and Results

- [Benchmark Manager](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/evaluation/benchmark_manager.py): `src/evaluation/benchmark_manager.py`
- [AI Scenario Workflow](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/evaluation/ai_scenario.py): `src/evaluation/ai_scenario.py`
- [Metrics Engine](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/metrics/metrics_engine.py): `src/metrics/metrics_engine.py`
- [Telemetry Logging](https://github.com/ujjwal-qubit/run_time_terror/blob/main/src/metrics/logging_engine.py): `src/metrics/logging_engine.py`

### Other components

- **Operator**

## Connections

- Operator → Web Frontend: operates
- Web Frontend → API Client: requests
- API Client → REST and WebSocket API: calls
- REST and WebSocket API → Application Controller: controls
- Operator → Desktop GUI: operates
- Desktop GUI → Application Controller: controls
- Operator → CLI Entry: invokes
- CLI Entry → Application Controller: initializes
- Application Controller → Configuration: loads
- Application Controller → Scenario Manager: manages
- Scenario Manager → Configuration: loads and saves
- Application Controller → Target Motion: advances
- Application Controller → Disturbance Engine: applies
- Application Controller → Simulation World: renders
- Application Controller → Simulation and MP4 Frames: gets frames
- Simulation and MP4 Frames → Baseline Tracker: provides frames
- Application Controller → Algorithm Plugins: discovers algorithms
- Algorithm Plugins → Baseline Tracker: loads plugin
- Baseline Tracker → Beacon Detection: detects candidates
- Baseline Tracker → Temporal Tracking: tracks candidates
- Application Controller → PTZ Control: computes commands
- Application Controller → Benchmark Manager: runs benchmark
- Benchmark Manager → Simulation and MP4 Frames: evaluates frames
- Benchmark Manager → Ground Truth: reads truth
- Benchmark Manager → Metrics Engine: records metrics
- Benchmark Manager → AI Scenario Workflow: dispatches prompts
- AI Scenario Workflow → Benchmark Manager: executes evaluation
- Application Controller → Telemetry Logging: records telemetry
- Application Controller → Visualization: renders view state
- REST and WebSocket API → Results Views: streams results