# marcushcarter/lumen architecture

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

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

## Overview

Lumen is a C++ game engine with an editor and game runtime. A typical editor workflow begins by selecting or creating a project, editing scene and asset documents in viewports, then running or exporting the project; the runtime loads a project and advances simulation and rendering. The tree also shows substantial animation, physics, terrain, and rendering subsystems. The excerpts confirm the application’s window/renderer setup and document lifecycle, but most domain wiring is unsampled, so those connections are marked unverified rather than asserted.

Main entry points: [`core/application/application.cpp`](https://github.com/marcushcarter/lumen/blob/main/core/application/application.cpp) (Application Loop), [`editor/application/editor_application.cpp`](https://github.com/marcushcarter/lumen/blob/main/editor/application/editor_application.cpp) (Editor Application), [`editor/documents/document_manager.cpp`](https://github.com/marcushcarter/lumen/blob/main/editor/documents/document_manager.cpp) (Document Manager), [`core/rendering/renderer.cpp`](https://github.com/marcushcarter/lumen/blob/main/core/rendering/renderer.cpp) (Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Editor"]
  node_project_manager["Project Manager"]
  node_editor_app["Editor Application"]
  node_documents["Document Manager"]
  node_scene_editor["Scene Editing<br/>[scene_panel.cpp]"]
  node_asset_docs["Asset Documents"]
  node_preview["Preview Viewport"]
  node_play["Play Session<br/>[play_session.cpp]"]
  node_exporter["Project Export"]
end

subgraph group_runtime["Application Runtime"]
  node_game_app["Game Application"]
  node_application["Application Loop<br/>[application.cpp]"]
end

subgraph group_content["Project and Content"]
  node_project["Project Loading<br/>[project.cpp]"]
  node_scene["Scene Data<br/>[scene_file.cpp]"]
  node_terrain["Terrain Source<br/>[terrain_source.cpp]"]
end

subgraph group_engine["Engine Systems"]
  node_renderer["Renderer<br/>[renderer.cpp]"]
  node_render_graph["Render Graph<br/>[render_graph.cpp]"]
  node_render_features["Render Features"]
  node_animation["Animation System<br/>[pose_system.cpp]"]
  node_dynamics["Character Dynamics<br/>[dynamics.cpp]"]
  node_physics["Physics World<br/>[physics_world.cpp]"]
  node_gameplay["Game Session<br/>[game_session.h]"]
end

subgraph group_drivers["Platform Drivers"]
  node_window["Windows Driver"]
  node_vulkan_context["Vulkan Context"]
  node_vulkan_device["Vulkan Device"]
  node_imgui["ImGui Driver<br/>[imgui_driver.cpp]"]
end

node_user(("Editor User"))

node_user -.->|"chooses project"| node_project_manager
node_project_manager -.->|"opens project"| node_editor_app
node_editor_app -.->|"manages documents"| node_documents
node_documents -.->|"opens scene"| node_scene_editor
node_documents -.->|"opens assets"| node_asset_docs
node_scene_editor -.->|"shows viewport"| node_preview
node_editor_app -.->|"starts play session"| node_play
node_editor_app -.->|"exports project"| node_exporter
node_game_app -.->|"runs"| node_application
node_application -->|"creates window"| node_window
node_application -->|"initializes UI"| node_imgui
node_application -->|"records frames"| node_renderer
node_application -.->|"creates render path"| node_render_features
node_application -.->|"loads project"| node_project
node_application -.->|"updates scene"| node_scene
node_application -.->|"updates poses"| node_animation
node_application -.->|"ticks gameplay"| node_gameplay
node_gameplay -.->|"simulates physics"| node_physics
node_gameplay -.->|"updates characters"| node_dynamics
node_animation -.->|"evaluates dynamics"| node_dynamics
node_renderer -.->|"records passes"| node_render_graph
node_render_graph -.->|"dispatches features"| node_render_features
node_renderer -.->|"submits GPU work"| node_vulkan_device
node_vulkan_device -.->|"uses context"| node_vulkan_context
node_scene -.->|"references terrain"| node_terrain

click node_project_manager "https://github.com/marcushcarter/lumen/blob/main/editor/project_manager/project_manager.cpp"
click node_editor_app "https://github.com/marcushcarter/lumen/blob/main/editor/application/editor_application.cpp"
click node_documents "https://github.com/marcushcarter/lumen/blob/main/editor/documents/document_manager.cpp"
click node_scene_editor "https://github.com/marcushcarter/lumen/blob/main/editor/documents/scene/scene_panel.cpp"
click node_asset_docs "https://github.com/marcushcarter/lumen/tree/main/editor/documents"
click node_preview "https://github.com/marcushcarter/lumen/blob/main/editor/viewport/preview_viewport.cpp"
click node_play "https://github.com/marcushcarter/lumen/blob/main/editor/play/play_session.cpp"
click node_exporter "https://github.com/marcushcarter/lumen/blob/main/editor/export/project_exporter.cpp"
click node_game_app "https://github.com/marcushcarter/lumen/blob/main/game/application/game_application.cpp"
click node_application "https://github.com/marcushcarter/lumen/blob/main/core/application/application.cpp"
click node_project "https://github.com/marcushcarter/lumen/blob/main/core/project/project.cpp"
click node_scene "https://github.com/marcushcarter/lumen/blob/main/core/scene/scene_file.cpp"
click node_terrain "https://github.com/marcushcarter/lumen/blob/main/core/terrain/terrain_source.cpp"
click node_renderer "https://github.com/marcushcarter/lumen/blob/main/core/rendering/renderer.cpp"
click node_render_graph "https://github.com/marcushcarter/lumen/blob/main/core/rendering/render_graph.cpp"
click node_render_features "https://github.com/marcushcarter/lumen/blob/main/core/rendering/features/geometry/geometry_feature.cpp"
click node_animation "https://github.com/marcushcarter/lumen/blob/main/core/animation/pose_system.cpp"
click node_dynamics "https://github.com/marcushcarter/lumen/blob/main/core/animation/dynamics.cpp"
click node_physics "https://github.com/marcushcarter/lumen/blob/main/core/physics/physics_world.cpp"
click node_gameplay "https://github.com/marcushcarter/lumen/blob/main/core/game/game_session.h"
click node_window "https://github.com/marcushcarter/lumen/blob/main/drivers/windows/window_driver_win32.cpp"
click node_vulkan_context "https://github.com/marcushcarter/lumen/blob/main/drivers/vulkan/context_driver_vulkan.cpp"
click node_vulkan_device "https://github.com/marcushcarter/lumen/blob/main/drivers/vulkan/device_driver_vulkan.cpp"
click node_imgui "https://github.com/marcushcarter/lumen/blob/main/drivers/imgui/imgui_driver.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_project_manager,node_editor_app,node_documents,node_scene_editor,node_asset_docs,node_preview,node_play,node_exporter,node_user toneBlue
class node_game_app,node_application toneAmber
class node_project,node_scene,node_terrain toneMint
class node_renderer,node_render_graph,node_render_features,node_animation,node_dynamics,node_physics,node_gameplay toneRose
class node_window,node_vulkan_context,node_vulkan_device,node_imgui toneIndigo
```

## Components

### Editor

- [Project Manager](https://github.com/marcushcarter/lumen/blob/main/editor/project_manager/project_manager.cpp): `editor/project_manager/project_manager.cpp`
- [Editor Application](https://github.com/marcushcarter/lumen/blob/main/editor/application/editor_application.cpp): `editor/application/editor_application.cpp`
- [Document Manager](https://github.com/marcushcarter/lumen/blob/main/editor/documents/document_manager.cpp): `editor/documents/document_manager.cpp`
- [Scene Editing](https://github.com/marcushcarter/lumen/blob/main/editor/documents/scene/scene_panel.cpp): `editor/documents/scene/scene_panel.cpp`
- [Asset Documents](https://github.com/marcushcarter/lumen/tree/main/editor/documents): `editor/documents`
- [Preview Viewport](https://github.com/marcushcarter/lumen/blob/main/editor/viewport/preview_viewport.cpp): `editor/viewport/preview_viewport.cpp`
- [Play Session](https://github.com/marcushcarter/lumen/blob/main/editor/play/play_session.cpp): `editor/play/play_session.cpp`
- [Project Export](https://github.com/marcushcarter/lumen/blob/main/editor/export/project_exporter.cpp): `editor/export/project_exporter.cpp`

### Application Runtime

- [Game Application](https://github.com/marcushcarter/lumen/blob/main/game/application/game_application.cpp): `game/application/game_application.cpp`
- [Application Loop](https://github.com/marcushcarter/lumen/blob/main/core/application/application.cpp): `core/application/application.cpp`

### Project and Content

- [Project Loading](https://github.com/marcushcarter/lumen/blob/main/core/project/project.cpp): `core/project/project.cpp`
- [Scene Data](https://github.com/marcushcarter/lumen/blob/main/core/scene/scene_file.cpp): `core/scene/scene_file.cpp`
- [Terrain Source](https://github.com/marcushcarter/lumen/blob/main/core/terrain/terrain_source.cpp): `core/terrain/terrain_source.cpp`

### Engine Systems

- [Renderer](https://github.com/marcushcarter/lumen/blob/main/core/rendering/renderer.cpp): `core/rendering/renderer.cpp`
- [Render Graph](https://github.com/marcushcarter/lumen/blob/main/core/rendering/render_graph.cpp): `core/rendering/render_graph.cpp`
- [Render Features](https://github.com/marcushcarter/lumen/blob/main/core/rendering/features/geometry/geometry_feature.cpp): `core/rendering/features/geometry/geometry_feature.cpp`
- [Animation System](https://github.com/marcushcarter/lumen/blob/main/core/animation/pose_system.cpp): `core/animation/pose_system.cpp`
- [Character Dynamics](https://github.com/marcushcarter/lumen/blob/main/core/animation/dynamics.cpp): `core/animation/dynamics.cpp`
- [Physics World](https://github.com/marcushcarter/lumen/blob/main/core/physics/physics_world.cpp): `core/physics/physics_world.cpp`
- [Game Session](https://github.com/marcushcarter/lumen/blob/main/core/game/game_session.h): `core/game/game_session.h`

### Platform Drivers

- [Windows Driver](https://github.com/marcushcarter/lumen/blob/main/drivers/windows/window_driver_win32.cpp): `drivers/windows/window_driver_win32.cpp`
- [Vulkan Context](https://github.com/marcushcarter/lumen/blob/main/drivers/vulkan/context_driver_vulkan.cpp): `drivers/vulkan/context_driver_vulkan.cpp`
- [Vulkan Device](https://github.com/marcushcarter/lumen/blob/main/drivers/vulkan/device_driver_vulkan.cpp): `drivers/vulkan/device_driver_vulkan.cpp`
- [ImGui Driver](https://github.com/marcushcarter/lumen/blob/main/drivers/imgui/imgui_driver.cpp): `drivers/imgui/imgui_driver.cpp`

### Other components

- **Editor User**

## Connections

- Editor User → Project Manager: chooses project
- Project Manager → Editor Application: opens project
- Editor Application → Document Manager: manages documents
- Document Manager → Scene Editing: opens scene
- Document Manager → Asset Documents: opens assets
- Scene Editing → Preview Viewport: shows viewport
- Editor Application → Play Session: starts play session
- Editor Application → Project Export: exports project
- Game Application → Application Loop: runs
- Application Loop → Windows Driver: creates window (evidence: `core/application/application.cpp`)
- Application Loop → ImGui Driver: initializes UI (evidence: `core/application/application.cpp`)
- Application Loop → Renderer: records frames (evidence: `core/application/application.cpp`)
- Application Loop → Render Features: creates render path
- Application Loop → Project Loading: loads project
- Application Loop → Scene Data: updates scene
- Application Loop → Animation System: updates poses
- Application Loop → Game Session: ticks gameplay
- Game Session → Physics World: simulates physics
- Game Session → Character Dynamics: updates characters
- Animation System → Character Dynamics: evaluates dynamics
- Renderer → Render Graph: records passes
- Render Graph → Render Features: dispatches features
- Renderer → Vulkan Device: submits GPU work
- Vulkan Device → Vulkan Context: uses context
- Scene Data → Terrain Source: references terrain
