# mmsk-sbrain/aeb_demo architecture

> Architecture diagram of the GitHub repository mmsk-sbrain/aeb_demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mmsk-sbrain/aeb_demo
- Repository: https://github.com/mmsk-sbrain/aeb_demo

## Overview

##### Project Type and Purpose
- This is a standalone desktop educational simulation platform (not a web app) for teaching Autonomous Emergency Braking (AEB) systems.
- It combines a GUI (PyQt5-based), a simulation “core” (physics engine + scenario loader + plugin manager), and plugin points where students drop in their AEB logic and brake controller code.
- The purpose is to let students load scenario JSON files and their own AEB/brake modules, run a real-time simulation, see gauges/logs, and export data.

##### File Structure
- Top-level:
- src/main.py – entry point, application bootstrap
- src/core/ – core simulation components
- src/ui/ – GUI windows/widgets
- scenarios/ – JSON scenario definitions
- templates/ – starter code for student modules
- requirements.txt – external deps (PyQt5, numpy, etc.)
- In src/core:
- scenario_loader.py – loads/interpolates scenario JSON
- student_code_manager.py – dynamic import of student modules
- physics_engine.py – simulation loop, vehicle dynamics, invoking AEB logic & brake controller
- data_logger.py – logs time-series and exports CSV
- In src/ui:
- main_window.py – design of main window, menus, controls
- widgets.py – custom gauges, debug console, log panel

##### README Insights
- The README describes a “GUI → Load student code & scenario → START → run simulation → CSV export” flow.
- It references features like real-time displays, CSV export, debug console, crash indicator.
- It hints at an MVC-style separation: UI triggers actions on core components; core returns data back to UI for display.

##### Elements
– Blue for UI components
– Green for core services
– Yellow for plugin interfaces
– Gray for data stores (JSON/CSV)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point
    subgraph "Entry Point"
        OR["Application Orchestrator"]:::core
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["MainWindow"]:::ui
        W["Custom Widgets (gauges, console, log panel)"]:::ui
    end

    %% Core Simulation
    subgraph "Core Simulation"
        SL["ScenarioLoader"]:::core
        SCM["StudentCodeManager"]:::core
        PE["PhysicsEngine (simulation loop)"]:::core
        DL["DataLogger"]:::core
    end

    %% Plugin Interfaces
    subgraph "Plugin Interfaces"
        AEB["AEBLogic Interface"]:::plugin
        BC["BrakeController Interface"]:::plugin
    end

    %% Data Stores & Assets
    subgraph "Data Stores & Assets"
        subgraph "Scenarios (JSON)"
            F1["fast_approach.json"]:::datastore
            F2["gradual_slowdown.json"]:::datastore
            F3["highway_cruise.json"]:::datastore
            F4["lead_accelerating.json"]:::datastore
            F5["stop_and_go.json"]:::datastore
            F6["sudden_stop.json"]:::datastore
        end
        subgraph "Templates (Python)"
            T1["aeb_logic.py"]:::datastore
            T2["aeb_logic_simple.py"]:::datastore
            T3["aeb_logic_advanced.py"]:::datastore
            T4["brake_controller.py"]:::datastore
            T5["brake_controller_simple.py"]:::datastore
            T6["brake_controller_advanced.py"]:::datastore
        end
        CSV["CSV Output"]:::datastore
        REQ["requirements.txt"]:::datastore
    end

    %% Relationships
    OR -->|"initializes"| UI
    OR -->|"initializes"| SL
    OR -->|"initializes"| SCM
    OR -->|"initializes"| PE
    OR -->|"initializes"| DL

    UI -->|"load_scenario()"| SL
    UI -->|"load_code()"| SCM
    UI -->|"START → run()"| PE

    SL -->|"reads JSON"| F1
    SL --> F2
    SL --> F3
    SL --> F4
    SL --> F5
    SL --> F6
    SL -->|"parses into model"| PE

    SCM -->|"imports plugin"| T1
    SCM --> T2
    SCM --> T3
    SCM --> T4
    SCM --> T5
    SCM --> T6
    SCM -->|"provides"| AEB
    SCM -->|"provides"| BC

    PE -->|"calls calculate_ttc() / should_brake()"| AEB
    PE -->|"calls calculate_brake_pressure()"| BC
    PE -->|"run_step() loop"| DL

    DL -->|"signals/slots update"| W
    DL -->|"flushes to CSV"| CSV

    UI -->|"renders"| W

    %% Click Events
    click OR "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/main.py"
    click UI "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/ui/main_window.py"
    click W "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/ui/widgets.py"
    click SL "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/core/scenario_loader.py"
    click SCM "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/core/student_code_manager.py"
    click PE "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/core/physics_engine.py"
    click DL "https://github.com/mmsk-sbrain/aeb_demo/blob/main/src/core/data_logger.py"
    click F1 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/scenarios/fast_approach.json"
    click F2 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/scenarios/gradual_slowdown.json"
    click F3 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/scenarios/highway_cruise.json"
    click F4 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/scenarios/lead_accelerating.json"
    click F5 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/scenarios/stop_and_go.json"
    click F6 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/scenarios/sudden_stop.json"
    click T1 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/templates/aeb_logic.py"
    click T2 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/templates/aeb_logic_simple.py"
    click T3 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/templates/aeb_logic_advanced.py"
    click T4 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/templates/brake_controller.py"
    click T5 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/templates/brake_controller_simple.py"
    click T6 "https://github.com/mmsk-sbrain/aeb_demo/blob/main/templates/brake_controller_advanced.py"
    click REQ "https://github.com/mmsk-sbrain/aeb_demo/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef plugin fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef datastore fill:#D3D3D3,stroke:#333,stroke-width:1px
```
