# mouadhaikal/vulkan-renderer architecture

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

- Interactive diagram: https://gitdiagram.com/mouadhaikal/vulkan-renderer
- Repository: https://github.com/mouadhaikal/vulkan-renderer

## Overview

##### Project Type & Purpose
- Type: A native, cross-platform real-time rendering engine written in C++17, using Vulkan for low-level GPU control.
- Purpose: Load 3D assets, manage scene state, run a render loop with advanced features (normal mapping, MSAA, mipmapping, Blinn-Phong lighting) and expose an interactive GUI layer via ImGui/ImPlot.

##### File Structure
- Top-level directories:
- / & src/: C++ modules (App, Camera, Renderer, Scene, etc.)
- shaders/: GLSL & SPIR-V shader assets + compile scripts
- assets/: models & textures
- vendor/: external libraries (Assimp, stb_image, ImGui)
- docs/: screenshots & recordings
- Key config/build files: CMakeLists.txt, buildAndRun.sh
- Patterns:
- “App” module orchestrates subsystems
- Scene graph (scene.hpp/cpp) holds Model, Mesh, Material
- Renderer module handles Vulkan setup, swapchain, pipelines
- InputHandler + GUI modules feed into App event loop
- TextureManager abstracts GPU texture uploads

##### Extract Insights from README
- Core dependencies: Vulkan SDK, GLFW (window + input), Assimp (model loading), stb_image (texture loading), ImGui/ImPlot (GUI).
- Runtime flow:
- Initialization: asset import → GPU resource creation → pipeline setup
- Shutdown: cleanup Vulkan resources
- Features to highlight: docking UI, tangent-space normal mapping, multiple light types, MSAA, mipmapping.

##### Main Components & Relationships
A. Application Layer
- App (core orchestrator)
- InputHandler ← GLFW
- GUI ← ImGui/ImPlot
- Logger
B. Domain/Scene Layer
- Scene Graph
- Model, Mesh, Material
C. Resource Management
- AssetLoader (Assimp) → Mesh + Material
- TextureManager (stb_image) → GPU textures + mipmaps
- ShaderCompiler (glslc → SPIR-V)
D. Rendering Infrastructure
- Renderer
– Vulkan Instance, Devices, Swapchain
– RenderPass, Framebuffers
– GraphicsPipeline (vertex + fragment shaders)
– CommandBuffers, DescriptorSets
- GPU Hardware
E. External Services & Build
- CMake build system
- Shell scripts (buildAndRun.sh, shaders/compile.sh)
- Platform (Windows, Linux)

- Input flow: User → GLFW → InputHandler → App
- Data flow: Assimp→Scene → Renderer → GPU → Framebuffer
- Control flow: App triggers ResourceManager, Renderer, GUI each frame
- Build flow: GLSL → glslc → SPIR-V → embedded in pipeline

##### Architectural Patterns
- Layered architecture: Presentation (GUI, Input), Application (App), Domain (Scene/Assets), Infrastructure (Renderer, GPU).
- Resource encapsulation: TextureManager & AssetLoader isolate file I/O and GPU uploads.
- Pipeline abstraction: Renderer module wraps Vulkan boilerplate and exposes renderFrame().

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        InputHandler["InputHandler"]:::core
        GUI["GUI"]:::core
        Logger["Logger"]:::core
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        App["App"]:::core
        Utilities["Utilities"]:::manager
    end

    %% Domain/Scene Layer
    subgraph "Domain/Scene Layer"
        direction TB
        SceneGraph["Scene Graph"]:::core
        Model["Model"]:::core
        Mesh["Mesh"]:::core
        Material["Material"]:::core
        Camera["Camera"]:::core
    end

    %% Resource Management
    subgraph "Resource Management"
        direction TB
        AssetLoader["AssetLoader"]:::manager
        TextureManager["TextureManager"]:::manager
        ShaderCompilation["Shader Compilation"]:::disk
    end

    %% Rendering Infrastructure
    subgraph "Rendering Infrastructure"
        direction TB
        Renderer["Renderer"]:::core
        GPU["GPU Hardware"]:::gpu
    end

    %% Build & External
    subgraph "Build & External"
        direction TB
        BuildSystem["Build System & Scripts"]:::disk
        ExternalLibs["External Libraries"]:::externalLib
        AssetsModels["assets/models"]:::disk
        AssetsTextures["assets/textures"]:::disk
    end

    %% External Dependencies
    Assimp[(Assimp)]:::externalLib
    stb_image[(stb_image)]:::externalLib
    ImGui[(ImGui/ImPlot)]:::externalLib
    GLFW[(GLFW)]:::externalLib

    %% User
    User((User)):::externalLib

    %% Relationships
    User -->|"controls"| InputHandler
    InputHandler -->|"events"| App
    App -->|"calls"| SceneGraph
    App -->|"updates"| Camera
    App -->|"invokes"| Renderer
    App -->|"renders GUI"| GUI
    App -->|"logs to"| Logger

    SceneGraph -->|"contains"| Model
    SceneGraph -->|"contains"| Mesh
    SceneGraph -->|"contains"| Material

    AssetLoader -->|"loads models"| SceneGraph
    TextureManager -->|"uploads textures"| Renderer
    ShaderCompilation -.->|"compiles shaders"| Renderer

    AssetsModels -->|"source files"| AssetLoader
    AssetsTextures -->|"source files"| TextureManager

    BuildSystem -.->|"triggers"| ShaderCompilation
    BuildSystem -.->|"build scripts"| Renderer

    Renderer -->|"submits commands"| GPU

    ExternalLibs -->|"provides"| ImGui
    ExternalLibs -->|"provides"| stb_image
    ExternalLibs -->|"provides"| Assimp
    ExternalLibs -->|"provides"| GLFW

    GLFW -->|"input backend"| InputHandler
    ImGui -->|"GUI backend"| GUI
    Assimp -->|"model loader"| AssetLoader
    stb_image -->|"texture loader"| TextureManager

    %% Click Events
    click App "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/app.hpp"
    click App "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/app.cpp"
    click App "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/main.cpp"
    click InputHandler "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/inputHandler.hpp"
    click InputHandler "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/inputHandler.cpp"
    click GUI "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/gui.hpp"
    click GUI "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/gui.cpp"
    click Logger "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/logger.hpp"
    click Logger "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/logger.cpp"
    click Camera "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/camera.hpp"
    click Camera "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/camera.cpp"
    click SceneGraph "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/scene.hpp"
    click SceneGraph "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/scene.cpp"
    click Model "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/model.hpp"
    click Model "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/model.cpp"
    click Mesh "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/mesh.hpp"
    click Mesh "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/mesh.cpp"
    click Material "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/material.hpp"
    click Material "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/material.cpp"
    click TextureManager "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/textureManager.hpp"
    click TextureManager "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/textureManager.cpp"
    click Renderer "https://github.com/mouadhaikal/vulkan-renderer/blob/main/include/renderer.hpp"
    click Renderer "https://github.com/mouadhaikal/vulkan-renderer/blob/main/src/renderer.cpp"
    click ShaderCompilation "https://github.com/mouadhaikal/vulkan-renderer/blob/main/shaders/compile.sh"
    click ShaderCompilation "https://github.com/mouadhaikal/vulkan-renderer/tree/main/shaders/glsl"
    click ShaderCompilation "https://github.com/mouadhaikal/vulkan-renderer/tree/main/shaders/glslc"
    click ShaderCompilation "https://github.com/mouadhaikal/vulkan-renderer/tree/main/shaders/spirv"
    click AssetsModels "https://github.com/mouadhaikal/vulkan-renderer/tree/main/assets/models"
    click AssetsTextures "https://github.com/mouadhaikal/vulkan-renderer/tree/main/assets/textures"
    click BuildSystem "https://github.com/mouadhaikal/vulkan-renderer/blob/main/CMakeLists.txt"
    click BuildSystem "https://github.com/mouadhaikal/vulkan-renderer/blob/main/buildAndRun.sh"
    click ExternalLibs "https://github.com/mouadhaikal/vulkan-renderer/tree/main/vendor/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000;
    classDef manager fill:#90EE90,stroke:#000;
    classDef disk fill:#FFA500,stroke:#000;
    classDef externalLib fill:#D8BFD8,stroke:#000;
    classDef gpu fill:#FF6347,stroke:#000;
```
