# marcushcarter/ballistic architecture

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

- Interactive diagram: https://gitdiagram.com/marcushcarter/ballistic
- Repository: https://github.com/marcushcarter/ballistic

## Overview

#### Purpose and Build Surface
Ballistic is a C++ graphics/game-engine-style runtime with an integrated editor, built through CMake. The root build composes core, drivers, editor, platform, and third-party code: `CMakeLists.txt`, `core/CMakeLists.txt`, `editor/CMakeLists.txt`. Assets can be embedded at build time via `cmake/EmbedAssets.cmake`.

#### Process Entry Points
Windows platform launch code selects the executable startup path and application mode: `platform/windows/ballistic_main.cpp`, `platform/windows/ballistic_console_wrapper.cpp`. Runtime application abstractions are centered in `core/application/application.h` and `core/application/application.cpp`; specialized editor and game applications are `editor/editor_application.cpp` and `game/game_application.cpp`.

#### Core Runtime and Project Boundary
The core layer owns application lifecycle, project state, asset identifiers, paths, logging, and image/resource access. Project-level state is represented by `core/project/project.h` and `core/project/project.cpp`; stable asset identity uses `core/assets/guid.h`. Embedded-resource and filesystem/image I/O form the asset-access boundary in `core/io/embedded_resource.h`, `core/io/path.h`, and `core/io/image_io.h`.

#### Rendering Architecture
Rendering is organized as a render graph executed by a renderer over a render context: `core/rendering/render_graph.h`, `core/rendering/renderer.h`, `core/rendering/render_context.h`. The graph/profiler boundary permits inspection of pass and resource execution through `core/rendering/render_graph_profiler.cpp`. Render paths select high-level modes—editor, game, project manager, or scene—via `core/rendering/render_path/render_path.cpp` and the headers under `core/rendering/render_path/`.

#### Render Features and Frame Flow
A chosen render path assembles feature passes into the graph. Core stages include geometry, visibility, presentation, and editor overlays: `core/rendering/features/geometry_feature.cpp`, `core/rendering/features/visibility_feature.cpp`, `core/rendering/features/present_feature.cpp`, `core/rendering/features/editor/imgui_feature.cpp`. Experimental/test graphics features (ambient occlusion, deferred lighting, subsurface scattering) are isolated under `core/rendering/features/test/`, indicating they are optional rather than the primary pipeline.

#### Platform and GPU Drivers
Rendering depends on Vulkan-specific context and device drivers: `drivers/vulkan/context_driver_vulkan.cpp`, `drivers/vulkan/device_driver_vulkan.cpp`, with Vulkan Memory Allocator implementation in `drivers/vulkan/impl/vk_mem_alloc_impl.cpp`. The native desktop boundary is Win32 windowing and dialogs: `drivers/windows/window_driver_win32.cpp`, `drivers/windows/dialogs_win32.cpp`. ImGui integration bridges editor UI to GPU textures through `drivers/imgui/imgui_driver.cpp` and `drivers/imgui/imgui_texture_cache.cpp`.

#### Editor Surface and Observability
The editor orchestrates UI, viewport rendering, project management, settings, console output, and profiling: `editor/editor.cpp`, `editor/editor_ui.cpp`, `editor/viewport/viewport.cpp`. It exposes runtime observability through render/resource/timeline profilers and memory profiling: `editor/profiler/profiler.cpp`, `editor/profiler/profiler_resources.cpp`, `editor/memory_profiler/memory_profiler.cpp`. External dependencies are vendored/submoduled under `thirdparty/`, notably ImGui, ImPlot, GLM, STB, and IconFontCppHeaders.

Main entry points: [`core/application/application.cpp`](https://github.com/marcushcarter/ballistic/blob/main/core/application/application.cpp) (Application lifecycle), [`editor/editor.cpp`](https://github.com/marcushcarter/ballistic/blob/main/editor/editor.cpp) (Editor orchestration), [`core/rendering/render_graph.h`](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_graph.h) (Render graph), [`CMakeLists.txt`](https://github.com/marcushcarter/ballistic/blob/main/CMakeLists.txt) (CMake build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_cmake["CMake build<br/>build system<br/>[CMakeLists.txt]"]
  node_embed_assets["Asset embedding<br/>CMake module<br/>[EmbedAssets.cmake]"]
end

subgraph group_runtime["Application runtime"]
  node_windows_entry["Windows entry<br/>launch code<br/>[ballistic_main.cpp]"]
  node_application["Application lifecycle<br/>core runtime<br/>[application.cpp]"]
  node_editor_app["Editor application<br/>application mode"]
  node_game_app["Game application<br/>application mode"]
  node_project["Project state<br/>core domain<br/>[project.cpp]"]
  node_asset_access["Asset access<br/>I/O boundary"]
end

subgraph group_rendering["Rendering"]
  node_render_path["Render path selection<br/>render modes<br/>[render_path.cpp]"]
  node_renderer["Renderer<br/>frame executor<br/>[renderer.h]"]
  node_render_graph["Render graph<br/>frame pipeline<br/>[render_graph.h]"]
  node_core_features["Core render passes<br/>feature passes"]
  node_imgui_feature["Editor overlay pass<br/>render feature<br/>[imgui_feature.cpp]"]
  node_render_profiler["Render graph profiler<br/>runtime observability"]
end

subgraph group_drivers["Platform &amp; GPU drivers"]
  node_vulkan_drivers["Vulkan context &amp; device<br/>GPU drivers"]
  node_win32_drivers["Win32 window &amp; dialogs<br/>native desktop driver"]
  node_imgui_driver["ImGui GPU bridge<br/>UI driver<br/>[imgui_driver.cpp]"]
end

subgraph group_editor["Editor &amp; observability"]
  node_editor["Editor orchestration<br/>editor runtime<br/>[editor.cpp]"]
  node_viewport["Editor viewport<br/>editor surface<br/>[viewport.cpp]"]
  node_editor_profiling["Editor profiling<br/>observability UI<br/>[profiler.cpp]"]
end

node_thirdparty[("Vendored dependencies<br/>third-party libraries")]

node_cmake -->|"includes"| node_embed_assets
node_cmake -->|"builds"| node_application
node_cmake -->|"builds"| node_editor
node_windows_entry -->|"starts"| node_application
node_application -->|"selects editor mode"| node_editor_app
node_application -->|"selects game mode"| node_game_app
node_application -->|"owns lifecycle"| node_project
node_project -->|"resolves assets"| node_asset_access
node_application -->|"selects mode"| node_render_path
node_render_path -->|"assembles"| node_render_graph
node_core_features -->|"adds passes"| node_render_graph
node_imgui_feature -->|"adds overlay"| node_render_graph
node_renderer -->|"executes"| node_render_graph
node_renderer -->|"uses GPU services"| node_vulkan_drivers
node_render_graph -->|"reports execution"| node_render_profiler
node_editor_app -->|"hosts"| node_editor
node_editor -->|"manages"| node_viewport
node_viewport -->|"drives editor rendering"| node_render_path
node_editor -->|"renders UI through"| node_imgui_driver
node_imgui_driver -->|"supplies textures"| node_imgui_feature
node_editor -->|"exposes"| node_editor_profiling
node_editor_profiling -->|"presents data"| node_render_profiler
node_application -->|"uses native windowing"| node_win32_drivers
node_thirdparty -.->|"provides UI libraries"| node_editor

click node_cmake "https://github.com/marcushcarter/ballistic/blob/main/CMakeLists.txt"
click node_embed_assets "https://github.com/marcushcarter/ballistic/blob/main/cmake/EmbedAssets.cmake"
click node_windows_entry "https://github.com/marcushcarter/ballistic/blob/main/platform/windows/ballistic_main.cpp"
click node_application "https://github.com/marcushcarter/ballistic/blob/main/core/application/application.cpp"
click node_editor_app "https://github.com/marcushcarter/ballistic/blob/main/editor/editor_application.cpp"
click node_game_app "https://github.com/marcushcarter/ballistic/blob/main/game/game_application.cpp"
click node_project "https://github.com/marcushcarter/ballistic/blob/main/core/project/project.cpp"
click node_asset_access "https://github.com/marcushcarter/ballistic/blob/main/core/io/embedded_resource.h"
click node_render_path "https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_path/render_path.cpp"
click node_renderer "https://github.com/marcushcarter/ballistic/blob/main/core/rendering/renderer.h"
click node_render_graph "https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_graph.h"
click node_core_features "https://github.com/marcushcarter/ballistic/blob/main/core/rendering/features/geometry_feature.cpp"
click node_imgui_feature "https://github.com/marcushcarter/ballistic/blob/main/core/rendering/features/editor/imgui_feature.cpp"
click node_render_profiler "https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_graph_profiler.cpp"
click node_vulkan_drivers "https://github.com/marcushcarter/ballistic/blob/main/drivers/vulkan/context_driver_vulkan.cpp"
click node_win32_drivers "https://github.com/marcushcarter/ballistic/blob/main/drivers/windows/window_driver_win32.cpp"
click node_imgui_driver "https://github.com/marcushcarter/ballistic/blob/main/drivers/imgui/imgui_driver.cpp"
click node_editor "https://github.com/marcushcarter/ballistic/blob/main/editor/editor.cpp"
click node_viewport "https://github.com/marcushcarter/ballistic/blob/main/editor/viewport/viewport.cpp"
click node_editor_profiling "https://github.com/marcushcarter/ballistic/blob/main/editor/profiler/profiler.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_cmake,node_embed_assets toneBlue
class node_windows_entry,node_application,node_editor_app,node_game_app,node_project,node_asset_access toneAmber
class node_render_path,node_renderer,node_render_graph,node_core_features,node_imgui_feature,node_render_profiler toneMint
class node_vulkan_drivers,node_win32_drivers,node_imgui_driver toneRose
class node_editor,node_viewport,node_editor_profiling toneIndigo
class node_thirdparty toneNeutral
```

## Components

### Build

- [CMake build](https://github.com/marcushcarter/ballistic/blob/main/CMakeLists.txt): build system · Composes runtime, editor, drivers, platform, and third-party code. · `CMakeLists.txt`
- [Asset embedding](https://github.com/marcushcarter/ballistic/blob/main/cmake/EmbedAssets.cmake): CMake module · Embeds assets into build outputs. · `cmake/EmbedAssets.cmake`

### Application runtime

- [Windows entry](https://github.com/marcushcarter/ballistic/blob/main/platform/windows/ballistic_main.cpp): launch code · Selects executable startup path and application mode. · `platform/windows/ballistic_main.cpp`
- [Application lifecycle](https://github.com/marcushcarter/ballistic/blob/main/core/application/application.cpp): core runtime · Base runtime application abstraction. · `core/application/application.cpp`
- [Editor application](https://github.com/marcushcarter/ballistic/blob/main/editor/editor_application.cpp): application mode · `editor/editor_application.cpp`
- [Game application](https://github.com/marcushcarter/ballistic/blob/main/game/game_application.cpp): application mode · `game/game_application.cpp`
- [Project state](https://github.com/marcushcarter/ballistic/blob/main/core/project/project.cpp): core domain · Owns project-level state and asset identity. · `core/project/project.cpp`
- [Asset access](https://github.com/marcushcarter/ballistic/blob/main/core/io/embedded_resource.h): I/O boundary · Provides embedded-resource, path, and image access. · `core/io/embedded_resource.h`

### Rendering

- [Render path selection](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_path/render_path.cpp): render modes · Chooses editor, game, project manager, or scene rendering. · `core/rendering/render_path/render_path.cpp`
- [Renderer](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/renderer.h): frame executor · Executes rendering over a render context. · `core/rendering/renderer.h`
- [Render graph](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_graph.h): frame pipeline · Organizes passes and resources for a frame. · `core/rendering/render_graph.h`
- [Core render passes](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/features/geometry_feature.cpp): feature passes · Geometry, visibility, and presentation stages. · `core/rendering/features/geometry_feature.cpp`
- [Editor overlay pass](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/features/editor/imgui_feature.cpp): render feature · `core/rendering/features/editor/imgui_feature.cpp`
- [Render graph profiler](https://github.com/marcushcarter/ballistic/blob/main/core/rendering/render_graph_profiler.cpp): runtime observability · Inspects graph pass and resource execution. · `core/rendering/render_graph_profiler.cpp`

### Platform & GPU drivers

- [Vulkan context & device](https://github.com/marcushcarter/ballistic/blob/main/drivers/vulkan/context_driver_vulkan.cpp): GPU drivers · Supplies Vulkan rendering context and device services. · `drivers/vulkan/context_driver_vulkan.cpp`
- [Win32 window & dialogs](https://github.com/marcushcarter/ballistic/blob/main/drivers/windows/window_driver_win32.cpp): native desktop driver · `drivers/windows/window_driver_win32.cpp`
- [ImGui GPU bridge](https://github.com/marcushcarter/ballistic/blob/main/drivers/imgui/imgui_driver.cpp): UI driver · Bridges editor UI textures to the GPU. · `drivers/imgui/imgui_driver.cpp`

### Editor & observability

- [Editor orchestration](https://github.com/marcushcarter/ballistic/blob/main/editor/editor.cpp): editor runtime · Coordinates UI, viewport, project management, settings, and console. · `editor/editor.cpp`
- [Editor viewport](https://github.com/marcushcarter/ballistic/blob/main/editor/viewport/viewport.cpp): editor surface · `editor/viewport/viewport.cpp`
- [Editor profiling](https://github.com/marcushcarter/ballistic/blob/main/editor/profiler/profiler.cpp): observability UI · Exposes render, resource, timeline, and memory profiling. · `editor/profiler/profiler.cpp`

### Other components

- **Vendored dependencies**: third-party libraries · Includes ImGui, ImPlot, GLM, STB, and IconFontCppHeaders.

## Connections

- CMake build → Asset embedding: includes
- CMake build → Application lifecycle: builds
- CMake build → Editor orchestration: builds
- Windows entry → Application lifecycle: starts
- Application lifecycle → Editor application: selects editor mode
- Application lifecycle → Game application: selects game mode
- Application lifecycle → Project state: owns lifecycle
- Project state → Asset access: resolves assets
- Application lifecycle → Render path selection: selects mode
- Render path selection → Render graph: assembles
- Core render passes → Render graph: adds passes
- Editor overlay pass → Render graph: adds overlay
- Renderer → Render graph: executes
- Renderer → Vulkan context & device: uses GPU services
- Render graph → Render graph profiler: reports execution
- Editor application → Editor orchestration: hosts
- Editor orchestration → Editor viewport: manages
- Editor viewport → Render path selection: drives editor rendering
- Editor orchestration → ImGui GPU bridge: renders UI through
- ImGui GPU bridge → Editor overlay pass: supplies textures
- Editor orchestration → Editor profiling: exposes
- Editor profiling → Render graph profiler: presents data
- Application lifecycle → Win32 window & dialogs: uses native windowing
- Vendored dependencies → Editor orchestration: provides UI libraries
