# starss9/cruise-controller-system architecture

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

- Interactive diagram: https://gitdiagram.com/starss9/cruise-controller-system
- Repository: https://github.com/starss9/cruise-controller-system

## Overview

##### Project Type and Purpose
- This is a lightweight, single-page web application built with Streamlit.

##### File Structure
- Top-level files:
- README.md – Project description and run instructions
- cruise_Sim.py – Main Streamlit app and simulation logic
- Untitled1.ipynb – Development/playground notebook (not part of production pipeline)
- No separate frontend/backend folders: the Streamlit script both renders the UI and drives the backend simulation.

##### Extract Key Architectural Insights from README
- Core features: real-time plots, slider-based parameter tuning, system stability/performance visualization.
- Technical stack: Python + Streamlit, underlying plotting library (Streamlit’s built-in charts or Matplotlib/Plotly).

##### Main Components
a. User Interface (UI)
- Browser / local client rendering the Streamlit app
- Slider widgets for Kp, Ki, Kd
b. Streamlit Application Server
- `cruise_Sim.py` as entrypoint
- Handles HTTP/WebSocket requests from the browser
c. Simulation Engine
- PID controller logic (compute error, integral, derivative, output)
- Vehicle dynamics model (first-order/second-order system)
d. Visualization Module
- Real-time plotting libraries (Streamlit charts, Matplotlib, or Plotly)
- Data buffers/time-series generator
e. Development Notebook (Optional/Evaluation)
- Jupyter notebook used for prototyping
- Not active in production but useful to mention as “Dev/Analysis”

##### Relationships & Data Flow
- 1) User moves sliders → 2) UI widget events sent to Streamlit server → 3) Server invokes Simulation Engine with new Kp, Ki, Kd → 4) Engine returns time-series of speed vs. setpoint → 5) Visualization Module renders updated plots → 6) Browser updates display.
- All components run in the same Python process (no external services or databases).

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- UI layer (Streamlit widgets & layout)
- Business logic layer (PID computation + vehicle model)
- Presentation layer (plot rendering)
- Event-driven update cycle: UI events trigger recomputation and re-rendering.
- Single‐process, reactive web app (no microservices or external dependencies).

##### Essential Elements
- Clear, concise labels for:
- Browser (User)
- Streamlit App / Server
- PID Simulation Engine
- Visualization Component
- (Optional) Jupyter Notebook

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser
    Browser["User (Browser)"]:::frontend

    %% Python Environment Boundary
    subgraph "Python Environment"
        direction TB
        UIWidgets["UI Widgets (Sliders)"]:::frontend
        StreamlitServer["Streamlit App / Server"]:::backend
        PIDEngine["PID Simulation Engine"]:::compute
        Visualization["Visualization Module"]:::viz
    end

    %% Development & Documentation
    subgraph "Development & Docs"
        direction TB
        Notebook["Jupyter Notebook (Prototype)"]:::dev
        Doc["README.md"]:::doc
    end

    %% Data Flows
    Browser -->|"slider events (Kp/Ki/Kd)"| UIWidgets
    UIWidgets -->|"UI events"| StreamlitServer
    StreamlitServer -->|"invoke with parameters"| PIDEngine
    PIDEngine -->|"time-series data"| Visualization
    Visualization -->|"plot data"| StreamlitServer
    StreamlitServer -->|"render UI"| Browser

    %% Click Events
    click UIWidgets "https://github.com/starss9/cruise-controller-system/blob/main/cruise_Sim.py"
    click StreamlitServer "https://github.com/starss9/cruise-controller-system/blob/main/cruise_Sim.py"
    click PIDEngine "https://github.com/starss9/cruise-controller-system/blob/main/cruise_Sim.py"
    click Visualization "https://github.com/starss9/cruise-controller-system/blob/main/cruise_Sim.py"
    click Notebook "https://github.com/starss9/cruise-controller-system/blob/main/Untitled1.ipynb"
    click Doc "https://github.com/starss9/cruise-controller-system/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef backend fill:#AED6F1,stroke:#1A5276,color:#154360;
    classDef compute fill:#85C1E9,stroke:#1F618D,color:#1B4F72;
    classDef viz fill:#5DADE2,stroke:#21618C,color:#1B2631;
    classDef dev fill:#F9E79F,stroke:#B7950B,stroke-dasharray:5 5,color:#7D6608;
    classDef doc fill:#ABEBC6,stroke:#196F3D,color:#145A32;
```
