# penquinz01/lazzo-engine architecture

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

- Interactive diagram: https://gitdiagram.com/penquinz01/lazzo-engine
- Repository: https://github.com/penquinz01/lazzo-engine

## Overview

1. **Repo shape and build boundaries**  
   This repository is split into two main Visual Studio projects: `Lazzo/` is the engine code, and `SandBox/` is a small test application that exercises the engine. `premake5.lua` and `GenerateProject.bat` are the build-generation layer, while `vendor/` holds third-party dependencies.

2. **Engine core as the reusable boundary**  
   The engine lives under `Lazzo/src/Lazzo/` and is structured as a reusable runtime library rather than a standalone game. The key public-facing pieces are `Application`, `Window`, `Events`, `GraphicsAPI`, `UI`, and `Log`, with `Core.h` and `Lazzo.h` likely acting as umbrella/include and export-definition headers.

3. **Application lifecycle and main loop**  
   `Application.cpp/.h` appears to define the engine-owned runtime loop and high-level app lifecycle. `EntryPoint.h` suggests the executable entry point is centralized in the engine and calls into a user-defined application class, which is the usual boundary between engine startup and game/app code.

4. **Sandbox as the consumer app**  
   `SandBox/src/SandboxApp.cpp` is the testbed for engine features. Architecturally, this is where an application built on top of the engine would plug in custom behavior without modifying the engine core.

5. **Windowing and platform integration**  
   `Window/Window.cpp/.h` is the abstraction over native window creation and event pumping. The README says SDL is used for window and input handling, so SDL is the platform boundary where OS events enter the engine.

6. **Event system as the input/data translation layer**  
   `Window/Events/` contains the engine’s internal event types, such as `KeyDownEvent`. This layer likely translates SDL callbacks/events into engine-specific event objects so the rest of the engine does not depend directly on SDL types.

7. **Rendering backend abstraction**  
   `Window/GraphicsAPI/GraphicsAPI.h` plus `OpenGLAPI.cpp/.h` indicate a backend interface with at least one concrete implementation: OpenGL. `GraphicsFactory.h` suggests the engine selects or constructs the active rendering backend through a factory boundary, keeping higher-level code independent of the API choice.

8. **UI integration on top of the graphics context**  
   `Window/UI/ImguiUI.cpp/.h` shows Dear ImGui integration as an engine subsystem layered on top of the window and graphics context. This is probably used for editor/debug UI and depends on the OpenGL/SDL setup being initialized first.

9. **Logging as a cross-cutting service**  
   `Log.cpp/.h` is a shared diagnostic subsystem used across engine modules. It is likely initialized early and available to both engine internals and sandbox code for runtime tracing and debugging.

10. **Dependency and initialization flow**  
   The runtime order implied by the structure is: build system generates the solution, the executable starts through the engine entry point, `Application` creates/owns the `Window`, the `Window` initializes SDL and an OpenGL context via the graphics API layer, then the main loop processes SDL events, dispatches engine events, renders, and optionally draws ImGui UI.

11. **Technology choices that affect architecture**  
   The important external technologies are C++, SDL2, OpenGL, and ImGui. SDL is the platform abstraction for windowing/input, OpenGL is the rendering backend, and ImGui is an immediate-mode UI layer tied to the graphics context.

12. **Current maturity and planned expansion**  
   The README roadmap shows the engine is still early-stage: only core runtime, windowing, events, logging, and basic OpenGL/ImGui integration are present. Future layers like ECS, renderer systems, lighting, animation, and physics will likely sit above the current engine core rather than replace it.

Main entry points: [`Lazzo/src/Lazzo/Window/Window.h`](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/Window.h) (Window), [`SandBox/src/SandboxApp.cpp`](https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/src/SandboxApp.cpp) (Sandbox App), [`Lazzo/Lazzo.vcxproj`](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/Lazzo.vcxproj) (Lazzo proj), [`Lazzo/src/Lazzo/Application.h`](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Application.h) (Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_premake5["Premake<br/>build generator<br/>[premake5.lua]"]
  node_generate_bat["Generate<br/>build script"]
  node_solution["Solution<br/>[Lazzo.slnx]"]
end

subgraph group_engine["Engine"]
  node_engine_proj["Lazzo proj<br/>engine project<br/>[Lazzo.vcxproj]"]
  node_lazzo_hdr["Lazzo.h<br/>engine umbrella<br/>[Lazzo.h]"]
  node_core_hdr["Core.h<br/>core defs<br/>[Core.h]"]
  node_entrypoint["Entry Point<br/>engine bootstrap<br/>[EntryPoint.h]"]
  node_application["Application<br/>runtime loop<br/>[Application.h]"]
  node_log["Log<br/>diagnostics<br/>[Log.h]"]
end

subgraph group_platform["Platform"]
  node_window["Window<br/>platform abstraction<br/>[Window.h]"]
  node_events["Events<br/>event model<br/>[Events.h]"]
  node_graphics_api["Graphics API<br/>render interface<br/>[GraphicsAPI.h]"]
  node_opengl_api["OpenGL<br/>render backend<br/>[OpenGLAPI.h]"]
  node_graphics_factory["Factory<br/>backend selection<br/>[GraphicsFactory.h]"]
  node_imgui_ui["ImGui UI<br/>ui integration<br/>[ImguiUI.h]"]
end

subgraph group_app["Apps"]
  node_sandbox_proj["Sandbox proj<br/>app project<br/>[SandBox.vcxproj]"]
  node_sandbox_app["Sandbox App<br/>sample app<br/>[SandboxApp.cpp]"]
  node_imgui_ini["ImGui config<br/>ui state<br/>[imgui.ini]"]
end

subgraph group_deps["Deps"]
end

node_generate_bat -->|"invokes"| node_premake5
node_premake5 -->|"creates"| node_solution
node_solution -->|"contains"| node_engine_proj
node_solution -->|"contains"| node_sandbox_proj
node_engine_proj -->|"exports"| node_lazzo_hdr
node_engine_proj -->|"implements"| node_application
node_engine_proj -->|"implements"| node_window
node_engine_proj -->|"implements"| node_log
node_application -->|"boots"| node_entrypoint
node_entrypoint -->|"launches"| node_sandbox_app
node_sandbox_proj -->|"contains"| node_sandbox_app
node_sandbox_app -->|"inherits"| node_application
node_application -->|"owns"| node_window
node_window -->|"emits"| node_events
node_window -->|"requests"| node_graphics_factory
node_graphics_factory -->|"selects"| node_graphics_api
node_graphics_api -->|"implements"| node_opengl_api
node_window -->|"hosts"| node_imgui_ui
node_imgui_ui -->|"depends on"| node_opengl_api
node_sandbox_app -.->|"uses"| node_imgui_ui
node_sandbox_app -.->|"logs"| node_log
node_application -->|"dispatches"| node_events
node_window -.->|"reports"| node_log
node_sandbox_app -.->|"persists"| node_imgui_ini

click node_premake5 "https://github.com/penquinz01/lazzo-engine/blob/main/premake5.lua"
click node_generate_bat "https://github.com/penquinz01/lazzo-engine/blob/main/GenerateProject.bat"
click node_solution "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo.slnx"
click node_engine_proj "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/Lazzo.vcxproj"
click node_sandbox_proj "https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/SandBox.vcxproj"
click node_lazzo_hdr "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo.h"
click node_core_hdr "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Core.h"
click node_entrypoint "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/EntryPoint.h"
click node_application "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Application.h"
click node_log "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Log.h"
click node_window "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/Window.h"
click node_events "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/Events/Events.h"
click node_graphics_api "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/GraphicsAPI/GraphicsAPI.h"
click node_opengl_api "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/GraphicsAPI/OpenGLAPI.h"
click node_graphics_factory "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/GraphicsFactory.h"
click node_imgui_ui "https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/UI/ImguiUI.h"
click node_sandbox_app "https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/src/SandboxApp.cpp"
click node_imgui_ini "https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/imgui.ini"

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_premake5,node_generate_bat,node_solution toneBlue
class node_engine_proj,node_lazzo_hdr,node_core_hdr,node_entrypoint,node_application,node_log toneAmber
class node_window,node_events,node_graphics_api,node_opengl_api,node_graphics_factory,node_imgui_ui toneMint
class node_sandbox_proj,node_sandbox_app,node_imgui_ini toneRose
```

## Components

### Build

Project generation and solution boundaries

- [Premake](https://github.com/penquinz01/lazzo-engine/blob/main/premake5.lua): build generator · Generates project and solution files · `premake5.lua`
- [Generate](https://github.com/penquinz01/lazzo-engine/blob/main/GenerateProject.bat): build script · Batch entry for project generation · `GenerateProject.bat`
- [Solution](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo.slnx): VS solution · Top-level Visual Studio solution · `Lazzo.slnx`

### Engine

Reusable runtime library

- [Lazzo proj](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/Lazzo.vcxproj): engine project · Reusable engine library project · `Lazzo/Lazzo.vcxproj`
- [Lazzo.h](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo.h): engine umbrella · Public engine include surface · `Lazzo/src/Lazzo.h`
- [Core.h](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Core.h): core defs · Core macros and common engine definitions · `Lazzo/src/Lazzo/Core.h`
- [Entry Point](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/EntryPoint.h): engine bootstrap · Central executable entry that starts the user application · `Lazzo/src/Lazzo/EntryPoint.h`
- [Application](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Application.h): runtime loop · Owns lifecycle and main loop · `Lazzo/src/Lazzo/Application.h`
- [Log](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Log.h): diagnostics · Cross-cutting logging service · `Lazzo/src/Lazzo/Log.h`

### Platform

Windowing, input, rendering, and UI integration

- [Window](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/Window.h): platform abstraction · Native window and event pumping boundary · `Lazzo/src/Lazzo/Window/Window.h`
- [Events](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/Events/Events.h): event model · Engine event types and dispatch layer · `Lazzo/src/Lazzo/Window/Events/Events.h`
- [Graphics API](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/GraphicsAPI/GraphicsAPI.h): render interface · Backend abstraction for rendering APIs · `Lazzo/src/Lazzo/Window/GraphicsAPI/GraphicsAPI.h`
- [OpenGL](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/GraphicsAPI/OpenGLAPI.h): render backend · Concrete OpenGL implementation · `Lazzo/src/Lazzo/Window/GraphicsAPI/OpenGLAPI.h`
- [Factory](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/GraphicsFactory.h): backend selection · Constructs or selects the active graphics backend · `Lazzo/src/Lazzo/Window/GraphicsFactory.h`
- [ImGui UI](https://github.com/penquinz01/lazzo-engine/blob/main/Lazzo/src/Lazzo/Window/UI/ImguiUI.h): ui integration · Immediate-mode UI layer on top of the graphics context · `Lazzo/src/Lazzo/Window/UI/ImguiUI.h`

### Apps

Consumer application built on the engine

- [Sandbox proj](https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/SandBox.vcxproj): app project · Test application project that consumes the engine · `SandBox/SandBox.vcxproj`
- [Sandbox App](https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/src/SandboxApp.cpp): sample app · Engine consumer used to exercise runtime features · `SandBox/src/SandboxApp.cpp`
- [ImGui config](https://github.com/penquinz01/lazzo-engine/blob/main/SandBox/imgui.ini): ui state · Sandbox UI layout/state persistence · `SandBox/imgui.ini`

## Connections

- Generate → Premake: invokes · Batch script runs the generator
- Premake → Solution: creates · Generates the solution and project files
- Solution → Lazzo proj: contains · Solution includes the engine project
- Solution → Sandbox proj: contains · Solution includes the sandbox project
- Lazzo proj → Lazzo.h: exports · Builds the engine public include surface
- Lazzo proj → Application: implements · Compiles runtime lifecycle code
- Lazzo proj → Window: implements · Compiles platform/window subsystem
- Lazzo proj → Log: implements · Compiles logging subsystem
- Application → Entry Point: boots · Startup path enters through engine-provided entrypoint
- Entry Point → Sandbox App: launches · Entrypoint instantiates the user application
- Sandbox proj → Sandbox App: contains · Sandbox project hosts the sample app
- Sandbox App → Application: inherits · Consumer app plugs into engine lifecycle
- Application → Window: owns · Application creates and drives the main window
- Window → Events: emits · Window translates platform input into engine events
- Window → Factory: requests · Window setup asks for a rendering backend
- Factory → Graphics API: selects · Factory binds the abstract backend interface
- Graphics API → OpenGL: implements · OpenGL is the current concrete backend
- Window → ImGui UI: hosts · UI layer is initialized on top of window/context
- ImGui UI → OpenGL: depends on · ImGui rendering requires the graphics backend
- Sandbox App → ImGui UI: uses · Sample app can exercise editor/debug UI
- Sandbox App → Log: logs · Application code can use shared diagnostics
- Application → Events: dispatches · Main loop processes engine events
- Window → Log: reports · Platform failures and lifecycle messages flow to logging
- Sandbox App → ImGui config: persists · Sandbox stores UI state for ImGui