# amerblb/self-driving-rc-car architecture

> Architecture diagram of the GitHub repository amerblb/self-driving-rc-car, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amerblb/self-driving-rc-car
- Repository: https://github.com/amerblb/self-driving-rc-car

## Overview

##### Project Type and Purpose
- This is an embedded robotics / full-stack‐style system for an autonomous RC car.
- It consists of two main “modes”:
- An offline ML pipeline (data collection → training → evaluation)
- A real‐time control loop on the Raspberry Pi (perception → sensor fusion → safety → motor control)
- There is also a lightweight web component (in `src/web`) and a YAML‐based configuration service.

##### File Structure
- Top‐level directories:
- config / config.example.yaml → runtime and hardware parameters
- hardware / notebooks → hardware specs and analysis notebooks
- src/ → all Python modules and scripts
– src/core/ (motor_control, perception, safety_monitor, sensor_fusion) → real‐time control logic
– src/utils/ (data_augmentation) → offline data prep
– src/data_collection.py, src/train_model.py, src/evaluate_model.py → ML pipeline entry points
– src/autonomous_driver.py → main loop for autonomous driving
– src/web/ (static, templates) → optional monitoring/telemetry UI
– src/tests/ → unit tests
- Other files:
- requirements.txt, setup.py → packaging and dependencies

##### README Insights
- Describes NVIDIA‐inspired CNN for end‐to‐end steering
- Sensor fusion for robust state estimation
- Safety monitor for emergency stops
- Path planning and obstacle avoidance
- Quick‐start workflow: collect → train → run

1. Hardware Layer
– Sensors: Pi Camera, Ultrasonic sensor, IMU (if any)
– Actuators: L298N motor driver + DC motors
2. Configuration Service
– YAML loader, parameter server
3. Real‐Time Control Loop (on Pi)
– Perception Module (CNN inference)
– Sensor Fusion Module
– Safety Monitor
– Motor Control Module
4. Offline ML Pipeline
– Data Collection Script (manual‐drive UI)
– Data Augmentation utilities
– Model Training (TensorFlow)
– Model Evaluation
5. Web Interface (optional)
– Flask/HTML front‐end for telemetry & manual override
6. Storage
– Local disk or network share for datasets, trained models, logs

– Hardware → Perception & Sensor Fusion (raw frames, distance readings)
– Perception → Steering commands → Safety monitor → Motor Control → Hardware
– Configuration → all runtime modules (perception, control, safety)
– Data Collection → local storage → Training → trained model
– Trained model → deployed into Perception module
– Web UI ↔ Control Loop (for status, manual override)

c. Architectural Patterns & Principles
– Modular separation of concerns: Perception / Fusion / Control / Safety
– Clear offline vs online paths (ML pipeline vs real‐time loop)
– Config‐driven design (no hard‐coded parameters)
– Test harness for components (`src/tests`)

d. Key Technologies & Frameworks
– Python 3.8+
– TensorFlow 2.x (CNN inference & training)
– Flask or lightweight Python web server
– Raspberry Pi OS, RPi.GPIO (or similar)
– YAML for configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        HW["Hardware Layer"]:::hardware
    end

    %% Onboard Runtime
    subgraph "Onboard Runtime"
        Entry["autonomous_driver.py"]:::realtime
        Perception["Perception Module"]:::realtime
        Fusion["Sensor Fusion Module"]:::realtime
        Safety["Safety Monitor Module"]:::realtime
        Control["Motor Control Module"]:::realtime
    end

    %% Offline ML Pipeline
    subgraph "Offline ML Pipeline"
        DataCollection["Data Collection"]:::offline
        DataAug["Data Augmentation"]:::offline
        ModelTraining["Model Training"]:::offline
        ModelEval["Model Evaluation"]:::offline
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Config["Configuration Service"]:::infra
        StorageDataset["Dataset Storage"]:::infra
        ModelStorage["Model Storage"]:::infra
        Logs["Logs"]:::infra
        WebUI["Web Interface (Flask UI)"]:::infra
    end

    %% Data Flows and Relationships
    HW -->|"raw sensor data"| Perception
    HW -->|"raw sensor data"| Fusion
    Entry -->|starts| Perception
    Entry -->|starts| Fusion
    Entry -->|starts| Safety
    Entry -->|starts| Control

    Perception -->|"steering_cmd"| Safety
    Fusion -->|"state_estimate"| Safety
    Safety -->|"safety_cmd"| Control
    Control -->|"motor_signals"| HW

    Config --> Perception
    Config --> Fusion
    Config --> Safety
    Config --> Control

    DataCollection -->|"raw data"| StorageDataset
    StorageDataset --> DataAug
    DataAug --> ModelTraining
    ModelTraining --> ModelStorage
    ModelStorage -->|"deployed model"| Perception
    ModelTraining --> ModelEval

    WebUI <-->|"telemetry & override"| Entry

    %% Click Events
    click HW "https://github.com/amerblb/self-driving-rc-car/tree/main/hardware/"
    click Config "https://github.com/amerblb/self-driving-rc-car/blob/main/config/config.example.yaml"
    click Entry "https://github.com/amerblb/self-driving-rc-car/blob/main/src/autonomous_driver.py"
    click Perception "https://github.com/amerblb/self-driving-rc-car/blob/main/src/core/perception.py"
    click Fusion "https://github.com/amerblb/self-driving-rc-car/blob/main/src/core/sensor_fusion.py"
    click Safety "https://github.com/amerblb/self-driving-rc-car/blob/main/src/core/safety_monitor.py"
    click Control "https://github.com/amerblb/self-driving-rc-car/blob/main/src/core/motor_control.py"
    click DataCollection "https://github.com/amerblb/self-driving-rc-car/blob/main/src/data_collection.py"
    click DataAug "https://github.com/amerblb/self-driving-rc-car/blob/main/src/utils/data_augmentation.py"
    click ModelTraining "https://github.com/amerblb/self-driving-rc-car/blob/main/src/train_model.py"
    click ModelEval "https://github.com/amerblb/self-driving-rc-car/blob/main/src/evaluate_model.py"
    click WebUI "https://github.com/amerblb/self-driving-rc-car/tree/main/src/web/"
    click StorageDataset "https://github.com/amerblb/self-driving-rc-car/blob/main/src/tests/test_components.py"
    click ModelStorage "https://github.com/amerblb/self-driving-rc-car/blob/main/requirements.txt"
    click Logs "https://github.com/amerblb/self-driving-rc-car/blob/main/setup.py"
    click ModelStorage "https://github.com/amerblb/self-driving-rc-car/tree/main/notebooks/"

    %% Styles
    classDef hardware fill:#90CAF9,stroke:#1E88E5,color:#0D47A1
    classDef realtime fill:#A5D6A7,stroke:#2E7D32,color:#1B5E20
    classDef offline fill:#FFCC80,stroke:#EF6C00,color:#E65100
    classDef infra fill:#EEEEEE,stroke:#9E9E9E,color:#424242
```
