# natebassett/mat099-enhanced-ai-racing architecture

> Architecture diagram of the GitHub repository natebassett/mat099-enhanced-ai-racing, 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/natebassett/mat099-enhanced-ai-racing
- Repository: https://github.com/natebassett/mat099-enhanced-ai-racing

## Overview

MAT099 Enhanced AI Racing combines autonomous-agent research in TORCS with a desktop learning and review interface. The primary workflow selects an agent, runs it in a TORCS race, records telemetry and results, then presents saved runs for review and comparison. Training and evaluation scripts support the research workflow; racing-line planning and N-step TD3 learning are distinct technical subsystems. Some connections are documented only at a high level because many GUI and script implementations were not sampled.

Main entry points: [`src/runner/torcs_runner.py`](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/runner/torcs_runner.py) (TORCS runner), [`src/gui/main_window.py`](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/main_window.py) (Main window), [`src/agents/n_step_td3_agent.py`](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/n_step_td3_agent.py) (N-step TD3 agent), [`src/n_step_td3/learner.py`](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/learner.py) (N-step TD3 learner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_race["Race execution"]
  node_race_repo[("Race history store<br/>[race_repository.py]")]
  node_runner["TORCS runner<br/>[torcs_runner.py]"]
  node_sim_wrapper["TORCS environment wrapper<br/>[gym_torcs.py]"]
end

subgraph group_agents["Driving agents"]
  node_map_agent["Map-aware agent<br/>[map_aware_agent.py]"]
  node_rule_agent["Rule-based agent"]
  node_dyna_agent["Dyna-Q agent<br/>[dyna_q_agent.py]"]
  node_td3_agent["N-step TD3 agent"]
  node_sensor_agent["Sensor-only TD3 agent"]
end

subgraph group_learning["Learning and planning"]
  node_contracts["Observation and action contracts<br/>[contracts.py]"]
  node_learner["N-step TD3 learner<br/>[learner.py]"]
  node_replay[("Replay buffer<br/>[replay.py]")]
  node_race_env["Training environment<br/>[environment.py]"]
  node_line_features["Racing-line features<br/>[racing_line.py]"]
  node_line_planning["Racing-line planning<br/>[optimizer.py]"]
end

subgraph group_desktop["Desktop experience"]
  node_app["Desktop application<br/>[app.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_race_worker["Race worker<br/>[race_worker.py]"]
  node_education["Agent education"]
  node_novice["Novice guides"]
  node_telemetry_ui["Telemetry review<br/>[telemetry_model.py]"]
  node_results_ui["Results and comparison<br/>[results_view.py]"]
end

subgraph group_research["Research workflows"]
  node_train_scripts["Training workflows"]
  node_eval_scripts["Evaluation workflows"]
  node_analysis["Evaluation analysis<br/>[analyse_results.py]"]
end

node_user(("Learner / researcher"))
node_torcs(("TORCS simulator"))

node_user -->|"uses"| node_app
node_app -->|"loads"| node_window
node_window -->|"starts races"| node_race_worker
node_window -->|"presents explanations"| node_education
node_education -->|"uses guides"| node_novice
node_window -->|"shows telemetry"| node_telemetry_ui
node_window -->|"shows results"| node_results_ui
node_race_worker -->|"runs race"| node_runner
node_race_worker -->|"records results"| node_race_repo
node_runner -->|"uses environment"| node_sim_wrapper
node_sim_wrapper -->|"exchanges race data"| node_torcs
node_runner -->|"requests actions"| node_map_agent
node_runner -->|"requests actions"| node_rule_agent
node_runner -->|"requests actions"| node_dyna_agent
node_runner -->|"requests actions"| node_td3_agent
node_runner -->|"requests actions"| node_sensor_agent
node_map_agent -->|"uses track line"| node_line_planning
node_td3_agent -->|"builds observations"| node_contracts
node_td3_agent -->|"loads policy"| node_learner
node_td3_agent -->|"uses line context"| node_line_features
node_sensor_agent -->|"specializes"| node_td3_agent
node_race_env -->|"builds observations"| node_contracts
node_race_env -->|"uses race runner"| node_runner
node_learner -->|"validates contracts"| node_contracts
node_learner -->|"samples experience"| node_replay
node_train_scripts -.->|"trains policies"| node_learner
node_train_scripts -.->|"collects experience"| node_race_env
node_eval_scripts -.->|"evaluates agents"| node_runner
node_analysis -.->|"analyzes outputs"| node_eval_scripts
node_line_features -.->|"reads line data"| node_line_planning

click node_app "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/app.py"
click node_window "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/main_window.py"
click node_race_worker "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/race_worker.py"
click node_education "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/agent_education_model.py"
click node_novice "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/novice_education.py"
click node_telemetry_ui "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/telemetry_model.py"
click node_results_ui "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/results_view.py"
click node_race_repo "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/storage/race_repository.py"
click node_runner "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/runner/torcs_runner.py"
click node_sim_wrapper "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/torcs-wrapper/gym_torcs/gym_torcs.py"
click node_map_agent "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/map_aware_agent.py"
click node_rule_agent "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/rule_based_agent.py"
click node_dyna_agent "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/dyna_q_agent.py"
click node_td3_agent "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/n_step_td3_agent.py"
click node_sensor_agent "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/sensor_n_step_td3_agent.py"
click node_contracts "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/contracts.py"
click node_learner "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/learner.py"
click node_replay "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/replay.py"
click node_race_env "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/environment.py"
click node_line_features "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/racing_line.py"
click node_line_planning "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/racing_line/optimizer.py"
click node_train_scripts "https://github.com/natebassett/mat099-enhanced-ai-racing/tree/development/scripts"
click node_eval_scripts "https://github.com/natebassett/mat099-enhanced-ai-racing/tree/development/scripts"
click node_analysis "https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/controlled-evaluation/analyse_results.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_race_repo,node_runner,node_sim_wrapper toneBlue
class node_map_agent,node_rule_agent,node_dyna_agent,node_td3_agent,node_sensor_agent toneAmber
class node_contracts,node_learner,node_replay,node_race_env,node_line_features,node_line_planning toneMint
class node_app,node_window,node_race_worker,node_education,node_novice,node_telemetry_ui,node_results_ui toneRose
class node_train_scripts,node_eval_scripts,node_analysis,node_user,node_torcs toneIndigo
```

## Components

### Race execution

- [Race history store](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/storage/race_repository.py): `src/storage/race_repository.py`
- [TORCS runner](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/runner/torcs_runner.py): `src/runner/torcs_runner.py`
- [TORCS environment wrapper](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/torcs-wrapper/gym_torcs/gym_torcs.py): `torcs-wrapper/gym_torcs/gym_torcs.py`

### Driving agents

- [Map-aware agent](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/map_aware_agent.py): `src/agents/map_aware_agent.py`
- [Rule-based agent](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/rule_based_agent.py): `src/agents/rule_based_agent.py`
- [Dyna-Q agent](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/dyna_q_agent.py): `src/agents/dyna_q_agent.py`
- [N-step TD3 agent](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/n_step_td3_agent.py): `src/agents/n_step_td3_agent.py`
- [Sensor-only TD3 agent](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/agents/sensor_n_step_td3_agent.py): `src/agents/sensor_n_step_td3_agent.py`

### Learning and planning

- [Observation and action contracts](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/contracts.py): `src/n_step_td3/contracts.py`
- [N-step TD3 learner](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/learner.py): `src/n_step_td3/learner.py`
- [Replay buffer](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/replay.py): `src/n_step_td3/replay.py`
- [Training environment](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/environment.py): `src/n_step_td3/environment.py`
- [Racing-line features](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/n_step_td3/racing_line.py): `src/n_step_td3/racing_line.py`
- [Racing-line planning](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/racing_line/optimizer.py): `src/racing_line/optimizer.py`

### Desktop experience

- [Desktop application](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/app.py): `src/gui/app.py`
- [Main window](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/main_window.py): `src/gui/main_window.py`
- [Race worker](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/race_worker.py): `src/gui/race_worker.py`
- [Agent education](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/agent_education_model.py): `src/gui/agent_education_model.py`
- [Novice guides](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/novice_education.py): `src/gui/novice_education.py`
- [Telemetry review](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/telemetry_model.py): `src/gui/telemetry_model.py`
- [Results and comparison](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/src/gui/results_view.py): `src/gui/results_view.py`

### Research workflows

- [Training workflows](https://github.com/natebassett/mat099-enhanced-ai-racing/tree/development/scripts): `scripts`
- [Evaluation workflows](https://github.com/natebassett/mat099-enhanced-ai-racing/tree/development/scripts): `scripts`
- [Evaluation analysis](https://github.com/natebassett/mat099-enhanced-ai-racing/blob/development/controlled-evaluation/analyse_results.py): `controlled-evaluation/analyse_results.py`

### Other components

- **Learner / researcher**
- **TORCS simulator**

## Connections

- Learner / researcher → Desktop application: uses
- Desktop application → Main window: loads (evidence: `src/gui/app.py`)
- Main window → Race worker: starts races (evidence: `src/gui/main_window.py`)
- Main window → Agent education: presents explanations (evidence: `src/gui/main_window.py`)
- Agent education → Novice guides: uses guides (evidence: `src/gui/agent_education_model.py`)
- Main window → Telemetry review: shows telemetry (evidence: `src/gui/main_window.py`)
- Main window → Results and comparison: shows results (evidence: `src/gui/main_window.py`)
- Race worker → TORCS runner: runs race (evidence: `src/gui/race_worker.py`)
- Race worker → Race history store: records results (evidence: `src/gui/race_worker.py`)
- TORCS runner → TORCS environment wrapper: uses environment (evidence: `src/runner/torcs_runner.py`)
- TORCS environment wrapper → TORCS simulator: exchanges race data
- TORCS runner → Map-aware agent: requests actions
- TORCS runner → Rule-based agent: requests actions
- TORCS runner → Dyna-Q agent: requests actions
- TORCS runner → N-step TD3 agent: requests actions
- TORCS runner → Sensor-only TD3 agent: requests actions
- Map-aware agent → Racing-line planning: uses track line (evidence: `src/agents/map_aware_agent.py`)
- N-step TD3 agent → Observation and action contracts: builds observations (evidence: `src/agents/n_step_td3_agent.py`)
- N-step TD3 agent → N-step TD3 learner: loads policy (evidence: `src/agents/n_step_td3_agent.py`)
- N-step TD3 agent → Racing-line features: uses line context (evidence: `src/agents/n_step_td3_agent.py`)
- Sensor-only TD3 agent → N-step TD3 agent: specializes (evidence: `src/agents/sensor_n_step_td3_agent.py`)
- Training environment → Observation and action contracts: builds observations (evidence: `src/n_step_td3/environment.py`)
- Training environment → TORCS runner: uses race runner (evidence: `src/n_step_td3/environment.py`)
- N-step TD3 learner → Observation and action contracts: validates contracts (evidence: `src/n_step_td3/learner.py`)
- N-step TD3 learner → Replay buffer: samples experience (evidence: `src/n_step_td3/learner.py`)
- Training workflows → N-step TD3 learner: trains policies
- Training workflows → Training environment: collects experience
- Evaluation workflows → TORCS runner: evaluates agents
- Evaluation analysis → Evaluation workflows: analyzes outputs
- Racing-line features → Racing-line planning: reads line data
