# sookeyy-12/neuralnitro-ai architecture

> Architecture diagram of the GitHub repository sookeyy-12/neuralnitro-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sookeyy-12/neuralnitro-ai
- Repository: https://github.com/sookeyy-12/neuralnitro-ai

## Overview

##### Project type and purpose
- This is a Unity-based full-stack simulation & training environment (“Neural Nitro”) for reinforcement learning (RL) agents in a racing‐car scenario.
- The Unity project (C# scripts + Assets + Scenes) provides the simulation, and Unity’s ML-Agents toolkit connects to an external Python trainer (via gRPC) to drive training/evaluation loops.

##### File structure
- Top-level folders:
- Assets/… → Unity assets: Scenes, Prefabs, Models, Materials, Scripts, Textures, ML-Agents config, ONNX model files under Assets/Models.
- Config/ & Curriculum/ → YAML configs and pretrained checkpoints for Python trainer.
- Packages/ → manifest.json for Unity packagemanager (incl. com.unity.ml-agents).
- ProjectSettings/ → Unity project settings.
- results/ → per‐experiment training outputs: ONNX models, .pt checkpoints, run_logs (timers, training_status).
- Key patterns:
- MVC-like separation: Unity Scenes (View), C# Scripts (Controller), ScriptableObjects/configs (Model).
- External ML service (Python) drives learning, writes models back into Assets/Models for inference in Unity.
- Build/deploy: Uses Unity Editor + ML-Agents package. Training is orchestrated by executing Unity in “training mode” connecting to Python.

##### README for additional insights
- Describes observation (RayPerceptionSensors, speed), action spaces (Throttle, Steer, Brake), reward structure.
- Instructs how to fix ML-Agents package paths in manifest.json.
- Highlights use of PPO (and other algorithms) via ML-Agents.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Unity Simulation Environment"
        USimEnv["Unity Simulation Environment"]:::runtime
        UEngine["Unity Engine (Simulation Loop)"]:::runtime
        subgraph "Assets Pipeline"
            subgraph "Scenes"
                FinalCircuit["FinalCircuit.unity"]:::asset
                MainMenu["MainMenu.unity"]:::asset
                TrainingEnv["TrainingEnv.unity"]:::asset
            end
            UScripts["C# Scripts (Controller)"]:::asset
            UMLSDK["ML-Agents C# SDK"]:::asset
            UModels["Model Assets (ONNX)"]:::asset
        end
    end

    subgraph "Python Trainer"
        PyTrainer["ML-Agents Python Trainer"]:::runtime
        PyConfig["YAML Configs"]:::datastore
        PyCurr["Curriculum Checkpoints"]:::datastore
    end

    subgraph "Results & Artifacts"
        ResArtifacts["Training Outputs & Artifacts"]:::datastore
    end

    subgraph "Configuration & Packages"
        Manifest["manifest.json"]:::datastore
        ProjSettings["ProjectSettings"]:::datastore
    end

    %% Data Flows
    UEngine -->|"streams observations via gRPC"| PyTrainer
    PyTrainer -->|"streams actions via gRPC"| UEngine
    PyTrainer -->|"writes checkpoints & ONNX"| ResArtifacts
    ResArtifacts -->|"provides ONNX for inference"| UModels

    PyConfig --> PyTrainer
    PyCurr --> PyTrainer
    Manifest --> UMLSDK
    ProjSettings --> USimEnv
    UEngine --> UScenes
    UEngine --> UScripts

    %% Click Events
    click USimEnv "https://github.com/sookeyy-12/neuralnitro-ai/tree/main/Assets/"
    click FinalCircuit "https://github.com/sookeyy-12/neuralnitro-ai/blob/main/Assets/Scenes/FinalCircuit.unity"
    click MainMenu "https://github.com/sookeyy-12/neuralnitro-ai/blob/main/Assets/Scenes/MainMenu.unity"
    click TrainingEnv "https://github.com/sookeyy-12/neuralnitro-ai/blob/main/Assets/Scenes/TrainingEnv.unity"
    click UScripts "https://github.com/sookeyy-12/neuralnitro-ai/tree/main/Assets/Scripts/"
    click UMLSDK "https://github.com/sookeyy-12/neuralnitro-ai/tree/main/Assets/ML-Agents/"
    click UModels "https://github.com/sookeyy-12/neuralnitro-ai/tree/main/Assets/Models/"
    click PyConfig "https://github.com/sookeyy-12/neuralnitro-ai/blob/main/Config/*.yaml"
    click PyCurr "https://github.com/sookeyy-12/neuralnitro-ai/blob/main/Curriculum/*.pt"
    click ResArtifacts "https://github.com/sookeyy-12/neuralnitro-ai/tree/main/results/"
    click Manifest "https://github.com/sookeyy-12/neuralnitro-ai/blob/main/Packages/manifest.json"
    click ProjSettings "https://github.com/sookeyy-12/neuralnitro-ai/tree/main/ProjectSettings/"

    %% Styles
    classDef runtime fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef datastore fill:#D5F5E3,stroke:#186A3B,color:#145A32
    classDef asset fill:#FCF3CF,stroke:#B7950B,color:#7D6608
```
