# lint111/vbvs--vixen architecture

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

- Interactive diagram: https://gitdiagram.com/lint111/vbvs--vixen
- Repository: https://github.com/lint111/vbvs--vixen

## Overview

##### Project type and purpose
- VIXEN is a modular C++-based Vulkan rendering framework and toolchain.
- It provides:
– A node-based RenderGraph for declarative frame construction.
– A caching layer (CashSystem) for Vulkan objects.
– An event messaging bus (EventBus).
– Shader management (compile, reflection, bundling).
– Resource state management.
– Application scaffolding (VulkanApplicationBase, GraphApplication).

##### File structure
- Top-level “VIXEN” directory contains CMake targets:
– CashSystem (caches pipelines, shaders, descriptors, meshes, textures)
– EventBus (intra-module message passing)
– RenderGraph (core graph compiler + node libraries + tests)
– ResourceManagement (resource lifetime & state)
– ShaderManagement (SPIR-V reflection, shader bundling, caching)
– include/, source/, Shaders/, BuiltAssets/, cache/, generated/
- Documentation under documentation/ explains each module’s architecture.
- Tests for each subsystem reinforce intended responsibilities.

##### Key excerpts from documentation
- GraphArchitecture describes the RenderGraph’s compile & execution phases.
- CashSystem docs outline resource caching patterns.
- ShaderManagement docs show pre-compilation workflows.
- EventBus docs explain how messages flow between threads/modules.

##### Main components
a. Application Layer
– main.cpp → VulkanApplicationBase → VulkanGraphApplication
– Configuration code that instantiates the RenderGraph, EventBus, Logger
b. RenderGraph Module
– GraphCompiler, NodeRegistry, NodeInstances, Scheduler/LoopManager
– Uses ResourceManagement, CashSystem, EventBus
c. CashSystem Module
– CacherBase + specialized Cachers (Pipeline, DescriptorSet, Mesh, Texture…)
– Interacts with VulkanResources to create/retain engine objects
d. ShaderManagement Module
– ShaderCompiler, SPIRVReflection, ShaderCacheManager, AsyncShaderBundleBuilder
– Reads shader source files, writes out SPIR-V, integrates with CashSystem
e. EventBus Module
– MessageBus, WorkerThreadBridge, Message types
– Connects subsystems that emit or consume events (e.g., resource changes)
f. ResourceManagement Module
– ResourceState, RM.h
– Manages state transitions and tracks lifetimes of Vulkan handles
g. Vulkan Backend
– VulkanInstance, VulkanDevice, SwapChain, Descriptor, Pipeline, Buffer, Image
– Wrapped by VulkanResources library code
h. Supporting Utilities
– Logger (ILoggable, FrameRateLogger)
– EngineTime
– TextureHandling loaders (STB, GLI)
i. External/Infrastructure
– File system (shader files, manifest.json, cache files)
– GPU driver

##### Relationships & data flows
- At startup: Application → constructs VulkanInstance/Device → EventBus, Logger, EngineTime initialized
- Application → configures RenderGraph (nodes + parameters)
- RenderGraph Compiler → queries ShaderManagement for compiled modules → asks CashSystem for pipelines & descriptor layouts → instructs VulkanResources to create handles
- During frame loop: RenderGraph executes nodes → enqueues Vulkan commands → uses ResourceManagement to track resource states → EventBus broadcasts lifecycle events (e.g., RenderGraphEvents)
- ShaderManagement watches filesystem → rebuilds shaders on the fly → notifies CashSystem to update caches → graph recompilation triggered
- Logger subscribes to events from RenderGraph (performance), ShaderManagement (compile logs), CashSystem (cache hits/misses)

##### Architectural patterns & design principles
- Modular library approach (each subsystem is a CMake target)
- Node-based graph execution (dataflow programming)
- Caching façade for expensive Vulkan objects
- Event-driven internal communication
- Separation of interface (include/) and implementation (src/)
- Code generation (generated/sdi) for shader interface descriptors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer" 
        Main["main.cpp"]:::application
        VulkanBase["VulkanApplicationBase"]:::application
        VulkanGraphApp["VulkanGraphApplication"]:::application
    end

    %% Core Modules
    subgraph "RenderGraph Module" 
        RG_Core_Inc["Core (include)"]:::core
        RG_Data_Inc["Data (include)"]:::core
        RG_Nodes_Inc["Nodes (include)"]:::core
        RG_Core_Src["Core (src)"]:::core
        RG_Nodes_Src["Nodes (src)"]:::core
    end

    subgraph "CashSystem Module"
        Cash_Inc["CashSystem (include)"]:::core
        Cash_Src["CashSystem (src)"]:::core
    end

    subgraph "ShaderManagement Module"
        Shader_Inc["ShaderManagement (include)"]:::core
        Shader_Src["ShaderManagement (src)"]:::core
        Shader_CMake["cmake"]:::core
    end

    subgraph "EventBus Module"
        Event_Inc["EventBus (include)"]:::comm
        Event_Src["EventBus (src)"]:::comm
    end

    subgraph "ResourceManagement Module"
        RM_Inc["ResourceManagement (include)"]:::core
    end

    %% Infrastructure Modules
    subgraph "VulkanResources"
        VR_Inc["VulkanResources (include)"]:::infra
        VR_Src["VulkanResources (src)"]:::infra
    end

    subgraph "FileSystem / Asset Caches"
        Shaders["Shaders"]:::infra
        BuiltAssets["BuiltAssets"]:::infra
        CacheFiles["cache"]:::infra
    end

    GPU["GPU Driver"]:::infra

    %% Utilities
    subgraph "Logger Utilities"
        Logger_h["Logger.h"]:::util
        Logger_cpp["Logger.cpp"]:::util
        ILoggable_h["ILoggable.h"]:::util
        ILoggable_cpp["ILoggable.cpp"]:::util
        FrameRate_h["FrameRateLogger.h"]:::util
        FrameRate_cpp["FrameRateLogger.cpp"]:::util
    end

    subgraph "EngineTime Utility"
        ET_h["EngineTime.h"]:::util
        ET_cpp["EngineTime.cpp"]:::util
    end

    subgraph "TextureHandling Loaders"
        TexInc["Loading (include)"]:::util
        TexSrc["Loading (src)"]:::util
    end

    %% Connections - Startup
    Main -->|"instantiates"| VulkanBase
    VulkanBase --> VulkanGraphApp
    VulkanBase --> Event_Inc
    VulkanBase --> Logger_h
    VulkanBase --> ET_h

    %% Configuration
    VulkanGraphApp --> RG_Core_Inc
    VulkanGraphApp --> Event_Inc
    VulkanGraphApp --> Logger_h

    %% RenderGraph interactions
    RG_Core_Inc -->|uses| Shader_Inc
    RG_Core_Inc -->|requests pipelines| Cash_Inc
    RG_Core_Inc -->|manages states via| RM_Inc
    RG_Core_Inc -->|dispatches events via| Event_Inc

    Cash_Inc --> VR_Inc
    RM_Inc --> VR_Inc

    Shader_Inc -->|reads sources from| Shaders
    Shader_Inc --> Shader_Src
    Shader_Src --> Shader_CMake
    Shader_Src --> Cash_Inc
    Shader_Src --> CacheFiles
    Shader_Src --> GPU

    Event_Inc --> Event_Src
    Event_Inc -->|publishes| Logger_h

    %% Frame loop
    RG_Core_Src -->|enqueues commands to| VR_Src
    RG_Core_Src --> RM_Inc
    RG_Core_Src --> Event_Inc

    %% Utilities subscriptions
    Logger_h -->|subscribes to| RG_Core_Src
    Logger_h -->|subscribes to| Shader_Src
    Logger_h -->|subscribes to| Cash_Src

    ET_h --> VulkanBase
    TexInc --> VulkanBase

    %% Infra
    VR_Inc --> GPU
    VR_Src --> GPU

    %% Click Events
    click Main "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/source/main.cpp"
    click VulkanBase "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/source/VulkanApplicationBase.cpp"
    click VulkanGraphApp "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/source/VulkanGraphApplication.cpp"
    click VulkanBase "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/include/VulkanApplicationBase.h"
    click VulkanGraphApp "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/include/VulkanGraphApplication.h"

    click RG_Core_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/RenderGraph/include/Core"
    click RG_Data_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/RenderGraph/include/Data"
    click RG_Nodes_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/RenderGraph/include/Nodes"
    click RG_Core_Src "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/RenderGraph/src/Core"
    click RG_Nodes_Src "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/RenderGraph/src/Nodes"

    click Cash_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/CashSystem/include/CashSystem"
    click Cash_Src "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/CashSystem/src"

    click Shader_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/ShaderManagement/include/ShaderManagement"
    click Shader_Src "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/ShaderManagement/src"
    click Shader_CMake "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/ShaderManagement/cmake"

    click Event_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/EventBus/include/EventBus"
    click Event_Src "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/EventBus/src"

    click RM_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/ResourceManagement/include/ResourceManagement"

    click VR_Inc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/include/VulkanResources"
    click VR_Src "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/source/VulkanResources"

    click Logger_h "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/logger/Logger.h"
    click Logger_cpp "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/logger/Logger.cpp"
    click ILoggable_h "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/logger/ILoggable.h"
    click ILoggable_cpp "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/logger/ILoggable.cpp"
    click FrameRate_h "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/logger/FrameRateLogger.h"
    click FrameRate_cpp "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/logger/FrameRateLogger.cpp"

    click ET_h "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/include/Time/EngineTime.h"
    click ET_cpp "https://github.com/lint111/vbvs--vixen/blob/main/VIXEN/source/Time/EngineTime.cpp"

    click TexInc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/include/TextureHandling/Loading"
    click TexSrc "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/source/TextureHandling/Loading"

    click Shaders "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/Shaders"
    click BuiltAssets "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/BuiltAssets"
    click CacheFiles "https://github.com/lint111/vbvs--vixen/tree/main/VIXEN/cache"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef infra fill:#d4edda,stroke:#333,stroke-width:1px
    classDef util fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef comm fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef application fill:#d1ecf1,stroke:#333,stroke-width:1px
```
