# iv4n-ga6l/neat-self-driving-cars architecture

> Architecture diagram of the GitHub repository iv4n-ga6l/neat-self-driving-cars, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iv4n-ga6l/neat-self-driving-cars
- Repository: https://github.com/iv4n-ga6l/neat-self-driving-cars

## Overview

##### Project Type and Purpose
- The project is an AI-driven simulation where cars learn to navigate a track using the NEAT (NeuroEvolution of Augmenting Topologies) genetic algorithm.
- It integrates real-time simulation, neural network evolution, and live visualization of the neural networks.
- The system allows users to interact by drawing a track and selecting a starting point, with the simulation then illustrating the evolving behavior of cars.

##### Major Components (as inferred from the file structure and README)
a. Main / Entry Point:
- File: main.py
- Function: Initialize the simulation, load configuration, and tie together the AI logic and rendering components.

b. AI / Car Behavior:
- Files: ai/car_ai.py, neat_config.ini
- Function: Implements the NEAT algorithm for evolving the neural network controlling the cars. The neat_config.ini provides configuration for NEAT’s operation.

c. Rendering / Visualization:
- Directory: render/
- render/car.py: Likely responsible for drawing cars.
- render/engine.py: Possibly sets up and drives the rendering loop.
- render/track.py: Manages the drawing of tracks.
- Function: Provides real-time visualization of the race simulation and the neural network data.

d. Assets and Configuration:
- Directory: assets (for graphical or data assets that may be used in rendering).
- File: requirements.txt ensures all necessary dependencies are installed.
- File: readme-data (potentially providing additional metadata for documentation or usage).

##### Relationships and Interactions
- main.py acts as the orchestrator:
- It initializes the simulation loop, instantiates the AI component from ai/car_ai.py, and launches the Render engine.
- It loads configuration (through neat_config.ini) for the NEAT algorithm.
- The AI component:
- Uses the NEAT algorithm to evolve and control car behavior based on sensor inputs and fitness evaluation.
- Updates the state of each car (accelerate, brake, turn) based on sensor data.
- The Rendering component:
- Visualizes the neural network (via render/neural_network) of the leading car.
- Provides distinct visual layers for track, car positions, and occasionally overlaid metrics or sensor data.
- Data Flow:
- The simulation loop (in main.py) continuously updates car positions and neural network parameters.
- Data flows from the AI (neural network adjustments) to the rendering engine, which in turn displays changes live.
- Sensors from the car (implied in README with five sensors) influence the AI decision-making, making it a feedback loop.

##### Architectural Patterns and Key Technologies
- Modular Design: The project splits the major concerns (simulation logic vs. visualization vs. AI evolution) into separate modules/directories.
- MVC-like Separation (though not strictly following MVC):
- Model: AI and car state (ai and parts of render).
- View: Rendering components (render/engine.py, render/car.py, render/neural_network).
- Controller: main.py that integrates and drives the simulation.
- Use of NEAT for AI evolution and explicit configuration via neat_config.ini is a core abstraction that controls the behavior of evolving neural networks.

##### Putting it All Together
- Additional annotations indicating the usage of specific libraries (like NEAT-Python if applicable, as noted in the README) and Python’s version requirements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Control Layer
    subgraph "Entry & Control"
        user("User Interaction (draw track & select start)"):::input
        main("Simulation Engine (main.py)"):::simulation
    end

    %% AI Module Layer
    subgraph "AI Module"
        ai("AI Module (ai/car_ai.py)"):::ai
        config("NEAT Config (neat_config.ini)"):::ai
        sensors("Car Sensors (implied)"):::ai
    end

    %% Rendering Module Layer
    subgraph "Rendering Module"
        engine("Render Engine (render/engine.py)"):::render
        car("Car Renderer (render/car.py)"):::render
        track("Track Manager (render/track.py)"):::render
        nn("Neural Network Visual (render/neural_network)"):::render
        colors("Colors Config (render/colors.py)"):::render
    end

    %% Assets & Documentation Layer
    subgraph "Assets & Docs"
        assets("Assets Directory (assets)"):::assets
        subgraph "Documentation & Dependencies"
            readme("README.md"):::assets
            readmeData("readme-data"):::assets
            reqs("requirements.txt"):::assets
        end
    end

    %% Relationships
    user -->|"provides_input"| main
    main -->|"init/update"| ai
    main -->|"launch_simulation"| engine
    main -->|"loads_assets"| assets

    config -->|"configures"| ai
    sensors -->|"feedback"| ai
    ai -->|"sends_control_signals"| engine

    engine -->|"renders"| car
    engine -->|"renders"| track
    engine -->|"visualizes"| nn
    engine -->|"uses"| colors

    %% Click Events
    click main "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/main.py"
    click ai "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/ai/car_ai.py"
    click config "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/neat_config.ini"
    click engine "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/render/engine.py"
    click car "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/render/car.py"
    click track "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/render/track.py"
    click nn "https://github.com/iv4n-ga6l/neat-self-driving-cars/tree/main/render/neural_network"
    click colors "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/render/colors.py"
    click assets "https://github.com/iv4n-ga6l/neat-self-driving-cars/tree/main/assets"
    click readme "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/README.md"
    click readmeData "https://github.com/iv4n-ga6l/neat-self-driving-cars/tree/main/readme-data"
    click reqs "https://github.com/iv4n-ga6l/neat-self-driving-cars/blob/main/requirements.txt"

    %% Styles
    classDef simulation fill:#FFCC00,stroke:#333,stroke-width:2px,color:#000;
    classDef ai fill:#99CCFF,stroke:#333,stroke-width:2px,color:#000;
    classDef render fill:#CCFFCC,stroke:#333,stroke-width:2px,color:#000;
    classDef assets fill:#FFCCCC,stroke:#333,stroke-width:2px,color:#000;
    classDef input fill:#FFE680,stroke:#333,stroke-width:2px,color:#000;
```
