# aaronmcleancs/particlebox architecture

> Architecture diagram of the GitHub repository aaronmcleancs/particlebox, 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/aaronmcleancs/particlebox
- Repository: https://github.com/aaronmcleancs/particlebox

## Overview

##### Project Components
- Engine:
- Contains all the core simulation functionality. This includes particle physics (physics.cpp/h), particle representation (particle.cpp/h), simulation setup/control (simulation.cpp/h and simulation_flags.h), and even a subset of test code (test.cpp/h) to validate behavior.
- Implements performance-critical algorithms such as spatial partitioning (to optimize collision detection) and uses multithreading to handle chunks of particles.
- UI:
- Provides a graphical user interface (gui.cpp/h) that uses SDL2 for visualization.
- Likely handles user inputs, rendering the simulated particles, and possibly interacting with the simulation states.
- Main Program:
- The main.cpp file serves as the entry point of the application, initiating both the Engine and the UI components.
- Build and Configuration:
- The Makefile specifies the build process, linking the simulation and UI parts together along with required libraries.

##### Relationships and Interactions
- Main.cpp acts as the orchestrator that initializes the simulation engine (Engine) and the UI system.
- The Engine module performs core computations and updates the state of particles. It feeds simulation data to the UI for real-time visualization.
- The UI module, built using SDL2, both displays the simulation and can send interaction events (if applicable) back to the Engine.
- Multithreading is a cross-cutting concern in the Engine that allows different partitions of the particle system to be processed in parallel.

##### Architectural Patterns and Principles
- Separation of Concerns: The project neatly segregates the simulation (Engine) from the display logic (UI).
- Performance Optimization: Use of spatial partitioning to reduce the computational complexity from O(N²) to a more manageable level.

##### Technologies and Frameworks
- C++ (with C++11 or later) forms the foundation of the project.
- SDL2 and SDL2_ttf libraries power the graphical interface.
- Additionally, modern C++ practices for memory management and random number generation (thread-local RNGs) are used in the simulation engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Application
    main_app["Main Application"]:::main

    %% Engine Subgraph
    subgraph "Engine"
        engine["Simulation Engine"]:::engine
        physics["Physics Module"]:::engine
        particle["Particle Module"]:::engine
        simulation["Simulation Setup Module"]:::engine
        test["Test Module"]:::engine
        threadPool["Thread Pool (Multithreading)"]:::engine
    end

    %% UI Subgraph
    subgraph "UI"
        gui["GUI Module"]:::ui
    end

    %% External Dependencies
    sdl["SDL2 & SDL2_ttf (Libraries)"]:::external
    make["Build Process (Makefile)"]:::external

    %% Connections
    main_app -->|"initializes"| engine
    main_app -->|"initializes"| gui

    engine -->|"processes_data"| gui
    gui -->|"sends_input"| engine

    engine -->|"uses_multithreading"| threadPool

    gui -->|"utilizes"| sdl

    make -->|"builds"| main_app

    %% Click Events
    click engine "https://github.com/aaronmcleancs/particlebox/tree/main/Engine/"
    click physics "https://github.com/aaronmcleancs/particlebox/blob/main/Engine/physics.cpp"
    click particle "https://github.com/aaronmcleancs/particlebox/blob/main/Engine/particle.cpp"
    click simulation "https://github.com/aaronmcleancs/particlebox/blob/main/Engine/simulation.cpp"
    click test "https://github.com/aaronmcleancs/particlebox/blob/main/Engine/test.cpp"
    click gui "https://github.com/aaronmcleancs/particlebox/tree/main/UI/"
    click main_app "https://github.com/aaronmcleancs/particlebox/blob/main/main.cpp"
    click make "https://github.com/aaronmcleancs/particlebox/tree/main/Makefile"

    %% Styles
    classDef main fill:#ffce91,stroke:#d58512,stroke-width:2px;
    classDef engine fill:#cce5ff,stroke:#2a9df4,stroke-width:2px;
    classDef ui fill:#d9f9d9,stroke:#28a745,stroke-width:2px;
    classDef external fill:#f9dcdc,stroke:#d9534f,stroke-width:2px;
```
