# wesleycramblitt/scientificsimulator architecture

> Architecture diagram of the GitHub repository wesleycramblitt/scientificsimulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wesleycramblitt/scientificsimulator
- Repository: https://github.com/wesleycramblitt/scientificsimulator

## Overview

#### Purpose and executable entry
This is a C++ game-engine-style simulation prototype centered on an ECS-like entity/component model, real-time graphics, and FluidX3D fluid simulation integration. The executable begins at `app/main.cpp`, which delegates application lifecycle orchestration to `app/include/core/app.hpp` and `app/src/core/app.cpp`. CMake is the build boundary in `CMakeLists.txt`.

#### Application lifecycle, window, and events
The core layer owns the interactive runtime: window creation, graphics-context-facing state, and per-frame event handling. `app/include/core/window.hpp` / `app/src/core/window.cpp` isolate platform/window behavior; `app/include/core/event_state.hpp` / `app/src/core/event_state.cpp` represent input/event state. Systems consume this state rather than owning window control directly.

#### Entity registry and component state
Simulation and renderable scene state are modeled as entities with composable components through `app/include/entities/registry.hpp` and `app/src/entities/registry.cpp`. Architecturally important component groups are transforms and selection (`app/include/components/transform.hpp`, `app/include/components/selected.hpp`), renderability/material technique selection (`app/include/components/renderable.hpp`, `app/include/components/render_technique_lit.hpp`), and fluid-domain/simulation state (`app/include/components/fluid_domain.hpp`, `app/include/components/fluid_physics.hpp`, `app/include/components/fluidx3d_config.hpp`).

#### Scene construction and asset ingestion
`app/include/scene/scene_manager.hpp` / `app/src/scene/scene_manager.cpp` form the scene-level boundary that likely creates and manages entity collections. Assets enter through `app/include/assets/file_importer.hpp` and `app/src/assets/file_importer.cpp`; mesh entities are populated/maintained by `app/include/systems/mesh_asset_system.hpp` and `app/src/systems/mesh_asset_system.cpp`. Built-in geometry follows a separate primitive path in `app/include/systems/primitive_mesh_system.hpp` and `app/src/systems/primitive_mesh_system.cpp`. Source models and cubemap images are local filesystem assets under `assets/models` and `assets/cubemaps`.

#### Simulation pipeline
FluidX3D is the concrete solver integration, isolated in `app/include/systems/fluidx3d_system.hpp` and `app/src/systems/fluidx3d_system.cpp`. It consumes fluid configuration/domain/physics components and writes simulation-associated entity state, including status/reference components (`app/include/components/simulation_status.hpp`, `app/include/components/simulation_reference.hpp`). Domain visualization/boundary handling is associated with `app/src/systems/domain_box.cpp`. Other solver categories described in the README are planned rather than represented as corresponding runtime systems.

#### Graphics resources and rendering
The graphics layer manages CPU-to-GPU resource boundaries: meshes via `app/include/graphics/mesh_manager.hpp` / `app/src/graphics/mesh_manager.cpp`, textures via `app/include/graphics/texture_manager.hpp` / `app/src/graphics/texture_manager.cpp`, and shaders via `app/include/graphics/shader_manager.hpp` / `app/src/graphics/shader_manager.cpp`. `app/include/systems/render_system.hpp` / `app/src/systems/render_system.cpp` is the frame rendering coordinator: it reads camera, transform, and render components and dispatches rendering techniques. Technique implementations cover Lambertian, reflections, cubemaps, particles, and volume ray marching, e.g. `app/src/graphics/render_techniques/volume_render_technique.cpp`, backed by GLSL in `shaders/volume/ray_march.frag`.

#### Interaction, editor controls, and frame-oriented systems
Camera/input control is separated into `app/include/systems/camera_controller_system.hpp` / `app/src/systems/camera_controller_system.cpp`. Scene editing and diagnostics are represented by ImGui and ImGuizmo systems (`app/src/systems/imgui_system.cpp`, `app/src/systems/imguizmo_system.cpp`) plus gizmo and grid systems (`app/src/systems/gizmo_system.cpp`, `app/src/systems/grid_system.cpp`). Cubemap and polygon-mode systems adjust rendering state independently (`app/src/systems/cubemap_system.cpp`, `app/src/systems/polygon_mode_system.cpp`).

#### Runtime dependencies and boundaries
The repository is a native CMake application with GPU rendering and shader assets; no remote backend, database, or network service is present in the tree. External numerical/GPU capabilities are implied by the FluidX3D integration and graphics context abstractions (`app/include/graphics/graphics_context.hpp`), but dependency acquisition details are not visible here. Tests focus on FluidX3D behavior (`tests/test_fluidx3d.cpp`, `tests/test_lbm_direct.cpp`).

Main entry points: [`app/src/core/app.cpp`](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/app.cpp) (Application Lifecycle), [`app/src/entities/registry.cpp`](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/entities/registry.cpp) (Entity Registry), [`app/src/systems/render_system.cpp`](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/render_system.cpp) (Render System), [`app/src/systems/fluidx3d_system.cpp`](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/fluidx3d_system.cpp) (FluidX3D System)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application Runtime"]
  node_main["Executable Entry<br/>C++ entry point<br/>[main.cpp]"]
  node_app["Application Lifecycle<br/>runtime orchestrator<br/>[app.cpp]"]
  node_window["Window &amp; Context<br/>platform runtime<br/>[window.cpp]"]
  node_events["Event State<br/>input state<br/>[event_state.cpp]"]
  node_camera_controls["Camera Controller<br/>input system"]
  node_editor_systems["Editor &amp; Diagnostics<br/>frame systems<br/>[imgui_system.cpp]"]
end

subgraph group_scene["Scene &amp; ECS"]
  node_registry[("Entity Registry<br/>ECS registry<br/>[registry.cpp]")]
  node_scene_manager["Scene Manager<br/>scene composition<br/>[scene_manager.cpp]"]
  node_asset_importer["File Importer<br/>asset ingestion<br/>[file_importer.cpp]"]
  node_mesh_assets["Mesh Asset System<br/>scene system"]
  node_primitives["Primitive Mesh System<br/>scene system"]
end

subgraph group_simulation["Fluid Simulation"]
  node_fluid_components["Fluid Components<br/>ECS component group<br/>[fluid_domain.hpp]"]
  node_fluidx3d{{"FluidX3D System<br/>solver integration"}}
  node_domain_box["Domain Box<br/>domain visualization<br/>[domain_box.cpp]"]
end

subgraph group_graphics["Graphics &amp; Rendering"]
  node_graphics_context["Graphics Context<br/>GPU context abstraction"]
  node_gpu_resources["GPU Resource Managers<br/>[mesh_manager.cpp]"]
  node_render_system["Render System<br/>frame renderer<br/>[render_system.cpp]"]
  node_volume_technique["Volume Ray Marching<br/>render technique"]
  node_volume_shader["Volume Shader<br/>GLSL shader<br/>[ray_march.frag]"]
end

node_cmake["CMake Build<br/>[CMakeLists.txt]"]

node_cmake -->|"builds"| node_main
node_main -->|"starts"| node_app
node_app -->|"creates"| node_window
node_window -->|"provides context"| node_graphics_context
node_app -->|"updates per frame"| node_events
node_app -->|"orchestrates"| node_scene_manager
node_scene_manager -->|"creates entities"| node_registry
node_asset_importer -->|"imports models"| node_mesh_assets
node_mesh_assets -->|"populates mesh entities"| node_registry
node_primitives -->|"adds built-in geometry"| node_registry
node_app -->|"runs per frame"| node_fluidx3d
node_fluidx3d -->|"reads and writes state"| node_registry
node_fluid_components -->|"configures solver"| node_fluidx3d
node_fluidx3d -->|"updates domain view"| node_domain_box
node_camera_controls -->|"consumes input"| node_events
node_camera_controls -->|"updates camera"| node_registry
node_editor_systems -->|"edits and inspects"| node_registry
node_app -->|"renders each frame"| node_render_system
node_render_system -->|"reads scene state"| node_registry
node_render_system -->|"uses GPU assets"| node_gpu_resources
node_gpu_resources -->|"uploads through"| node_graphics_context
node_render_system -->|"dispatches"| node_volume_technique
node_volume_technique -->|"uses"| node_volume_shader
node_render_system -->|"draws through"| node_graphics_context

click node_cmake "https://github.com/wesleycramblitt/scientificsimulator/blob/main/CMakeLists.txt"
click node_main "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/main.cpp"
click node_app "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/app.cpp"
click node_window "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/window.cpp"
click node_events "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/event_state.cpp"
click node_registry "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/entities/registry.cpp"
click node_scene_manager "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/scene/scene_manager.cpp"
click node_asset_importer "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/assets/file_importer.cpp"
click node_mesh_assets "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/mesh_asset_system.cpp"
click node_primitives "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/primitive_mesh_system.cpp"
click node_fluid_components "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/include/components/fluid_domain.hpp"
click node_fluidx3d "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/fluidx3d_system.cpp"
click node_domain_box "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/domain_box.cpp"
click node_graphics_context "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/include/graphics/graphics_context.hpp"
click node_gpu_resources "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/graphics/mesh_manager.cpp"
click node_render_system "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/render_system.cpp"
click node_volume_technique "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/graphics/render_techniques/volume_render_technique.cpp"
click node_volume_shader "https://github.com/wesleycramblitt/scientificsimulator/blob/main/shaders/volume/ray_march.frag"
click node_camera_controls "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/camera_controller_system.cpp"
click node_editor_systems "https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/imgui_system.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_window,node_events,node_camera_controls,node_editor_systems toneBlue
class node_registry,node_scene_manager,node_asset_importer,node_mesh_assets,node_primitives toneAmber
class node_fluid_components,node_fluidx3d,node_domain_box toneMint
class node_graphics_context,node_gpu_resources,node_render_system,node_volume_technique,node_volume_shader toneRose
class node_cmake toneNeutral
```

## Components

### Application Runtime

- [Executable Entry](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/main.cpp): C++ entry point · `app/main.cpp`
- [Application Lifecycle](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/app.cpp): runtime orchestrator · `app/src/core/app.cpp`
- [Window & Context](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/window.cpp): platform runtime · `app/src/core/window.cpp`
- [Event State](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/core/event_state.cpp): input state · `app/src/core/event_state.cpp`
- [Camera Controller](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/camera_controller_system.cpp): input system · `app/src/systems/camera_controller_system.cpp`
- [Editor & Diagnostics](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/imgui_system.cpp): frame systems · ImGui, ImGuizmo, gizmo, and grid tooling. · `app/src/systems/imgui_system.cpp`

### Scene & ECS

- [Entity Registry](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/entities/registry.cpp): ECS registry · Owns composable entity and component state. · `app/src/entities/registry.cpp`
- [Scene Manager](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/scene/scene_manager.cpp): scene composition · `app/src/scene/scene_manager.cpp`
- [File Importer](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/assets/file_importer.cpp): asset ingestion · `app/src/assets/file_importer.cpp`
- [Mesh Asset System](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/mesh_asset_system.cpp): scene system · `app/src/systems/mesh_asset_system.cpp`
- [Primitive Mesh System](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/primitive_mesh_system.cpp): scene system · `app/src/systems/primitive_mesh_system.cpp`

### Fluid Simulation

- [Fluid Components](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/include/components/fluid_domain.hpp): ECS component group · Domain, physics, FluidX3D configuration, status, and references. · `app/include/components/fluid_domain.hpp`
- [FluidX3D System](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/fluidx3d_system.cpp): solver integration · `app/src/systems/fluidx3d_system.cpp`
- [Domain Box](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/domain_box.cpp): domain visualization · `app/src/systems/domain_box.cpp`

### Graphics & Rendering

- [Graphics Context](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/include/graphics/graphics_context.hpp): GPU context abstraction · `app/include/graphics/graphics_context.hpp`
- [GPU Resource Managers](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/graphics/mesh_manager.cpp): mesh, texture & shader resources · Transfers and manages render resources. · `app/src/graphics/mesh_manager.cpp`
- [Render System](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/systems/render_system.cpp): frame renderer · Dispatches rendering techniques from ECS state. · `app/src/systems/render_system.cpp`
- [Volume Ray Marching](https://github.com/wesleycramblitt/scientificsimulator/blob/main/app/src/graphics/render_techniques/volume_render_technique.cpp): render technique · `app/src/graphics/render_techniques/volume_render_technique.cpp`
- [Volume Shader](https://github.com/wesleycramblitt/scientificsimulator/blob/main/shaders/volume/ray_march.frag): GLSL shader · `shaders/volume/ray_march.frag`

### Other components

- [CMake Build](https://github.com/wesleycramblitt/scientificsimulator/blob/main/CMakeLists.txt): build · Native application build boundary. · `CMakeLists.txt`

## Connections

- CMake Build → Executable Entry: builds
- Executable Entry → Application Lifecycle: starts
- Application Lifecycle → Window & Context: creates
- Window & Context → Graphics Context: provides context
- Application Lifecycle → Event State: updates per frame
- Application Lifecycle → Scene Manager: orchestrates
- Scene Manager → Entity Registry: creates entities
- File Importer → Mesh Asset System: imports models
- Mesh Asset System → Entity Registry: populates mesh entities
- Primitive Mesh System → Entity Registry: adds built-in geometry
- Application Lifecycle → FluidX3D System: runs per frame
- FluidX3D System → Entity Registry: reads and writes state
- Fluid Components → FluidX3D System: configures solver
- FluidX3D System → Domain Box: updates domain view
- Camera Controller → Event State: consumes input
- Camera Controller → Entity Registry: updates camera
- Editor & Diagnostics → Entity Registry: edits and inspects
- Application Lifecycle → Render System: renders each frame
- Render System → Entity Registry: reads scene state
- Render System → GPU Resource Managers: uses GPU assets
- GPU Resource Managers → Graphics Context: uploads through
- Render System → Volume Ray Marching: dispatches
- Volume Ray Marching → Volume Shader: uses
- Render System → Graphics Context: draws through