# ovi-lab/hpui-core architecture

> Architecture diagram of the GitHub repository ovi-lab/hpui-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ovi-lab/hpui-core
- Repository: https://github.com/ovi-lab/hpui-core

## Overview

##### Main Components
- Editor Components: Located in the “Editor” directory. These include custom inspectors, property drawers, and assembly definitions (asmdef files) that group editor-specific code. Their role is to provide a customized editing experience to configure HPUI properties and interactables.
- Runtime Components: Found in the “Runtime” directory. This contains several submodules:
- Assets (including HPUI UI prefabs for interactables and continuous user interfaces),
- Interaction logic (under “Runtime/Interaction” with scripts for interactables, gesture logic, detection, and handling ray-cast or sphere-cast based interactions),
- Tracking (located in “Runtime/Tracking” with hand skeleton drivers, joint follower scripts, etc.),
- Components and Utils that provide supporting functionality (e.g., UI behavior, event handling, helper classes, filter functions).
- Legacy Assets and Scripts: The “Assets_Legacy” directories in both Editor and Runtime hold older or backward-compatible versions that may be integrated or maintained for legacy projects.
- Resources: Under “Runtime/Resources” where default joint data and configurable assets reside (used for hand joint definitions).
- Samples: Sample scenes and scripts in the “Samples~” directory illustrate usage scenarios (e.g., creating sample HPUI interaction scenes).
- Tests: The “Tests” directory includes assembly definitions and test scripts that ensure the proper behavior of components like gesture logic, interactable definitions, and interactor behavior.
- Documentation: Contains usage, developer guides, and Doxygen configuration files. It is key for understanding module functions and design guidelines.

##### Component Relationships and Data Flow
- At the core, runtime modules manage the actual hand interaction behavior:
- Tracking gathers data from head-mounted display sensors and hand tracking systems.
- The Interaction module uses this tracking data to detect and process gestures (using scripts in “Runtime/Interaction” and “Runtime/Interaction/Logic”).
- The UI module (under “Runtime/UI”) contains and manages HPUI visual representations, linking with Interaction components to update based on hand inputs.
- Some utility modules (“Runtime/Utils”) and Resources provide supporting functions (e.g., filtering, data defaults).
- The Editor layer works as a complementary development experience by providing custom property drawers, inspectors, and type selectors (as found in the “Editor” directory). This allows developers to configure HPUI assets properly within Unity.
- Samples demonstrate how these layers coordinate in a real scene, showing the integration between custom editor configurations, runtime behavior, and component interactions.
- Testing components ensure that critical parts of the transformation from hand tracking to UI response behave as expected.

##### Architectural Patterns and Design Principles
- Modular Organization: Clear division between Editor and Runtime, as well as further separation within Runtime into Interaction, Tracking, UI, and Utils. This modular division (supported by the use of .asmdef files) makes the system maintainable and independent.
- Event-Driven and Component-Based Architecture: In Unity, using components attached to game objects means systems like “HPUI Events”, “Gesture Logic”, etc., trigger and respond to events, promoting loose coupling.
- Extensibility and Maintainability: Custom inspectors and property drawers in the Editor allow flexibility in defining new interactable types without changing the core runtime modules.
- Legacy Support: The presence of legacy directories suggests that backward compatibility is maintained for earlier assets and scripts.

##### Incorporate Relevant Technologies and Frameworks
- Unity: The entire structure is based on the Unity engine with a dedicated focus on XR/VR interactions.
- C# and Unity Assembly Definitions (.asmdef files) to modularize code.
- Doxygen for documentation generation, visible in the Documentation directories and Doxyfile.
- GitHub Actions workflows (in the .github directory) used for continuous integration, for example, static analysis.

##### Specific Elements
- Clear Labels: Each main block should be clearly labeled such as “Editor Tools”, “Runtime Interaction / UI”, “Tracking Engine”, “Legacy Support”, “Testing Framework”, “Sample Application”.
- Layered Architecture: Consider a layered design where the lowest layer is the hardware/sensors (external XR input), above which sits the Tracking module, then the Interaction/Logic layer, and finally the UI and Presentation layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Module
    XRInput["XR Input System"]:::external

    %% Editor Tools Subgraph
    subgraph "Editor Tools"
        EditorComp["Editor Components"]:::editor
        LegacyEditor["Legacy (Editor)"]:::legacy
    end

    %% Runtime Modules Subgraph
    subgraph "Runtime Modules"
        AssetsComp["Components & Assets"]:::runtime
        TrackingEngine["Tracking Engine"]:::runtime
        InteractionLogic["Interaction Logic"]:::runtime
        UIModule["UI Module"]:::runtime
        Utils["Utils"]:::runtime
        Resources["Resources"]:::runtime
        LegacyRuntime["Legacy (Runtime)"]:::legacy
    end

    %% Integration Subgraph for Samples, Tests, and Documentation
    subgraph "Integration"
        Samples["Sample Application"]:::samples
        Tests["Testing Framework"]:::tests
        Documentation["Documentation"]:::documentation
    end

    %% Data Flow and Relationships
    XRInput -->|"feeds"| TrackingEngine
    Resources -->|"providesDefaults"| TrackingEngine
    TrackingEngine -->|"dataFlows"| InteractionLogic
    AssetsComp -->|"supports"| InteractionLogic
    Utils -->|"supports"| InteractionLogic
    InteractionLogic -->|"updates"| UIModule

    EditorComp -->|"configures"| AssetsComp
    EditorComp -->|"configures"| InteractionLogic
    EditorComp -->|"configures"| UIModule

    %% Legacy Relationship
    LegacyEditor ---|"correlates"| LegacyRuntime

    %% Integration with Runtime
    UIModule -->|"demonstrates"| Samples
    UIModule -->|"verifiedBy"| Tests
    UIModule -->|"documentedIn"| Documentation

    %% Click Events
    click EditorComp "https://github.com/ovi-lab/hpui-core/tree/master/Editor"
    click LegacyEditor "https://github.com/ovi-lab/hpui-core/tree/master/Editor/Assets_Legacy"
    click AssetsComp "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/Assets"
    click TrackingEngine "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/Tracking"
    click InteractionLogic "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/Interaction"
    click UIModule "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/UI"
    click Utils "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/Utils"
    click Resources "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/Resources"
    click LegacyRuntime "https://github.com/ovi-lab/hpui-core/tree/master/Runtime/Assets_Legacy"
    click Samples "https://github.com/ovi-lab/hpui-core/tree/master/Samples~"
    click Tests "https://github.com/ovi-lab/hpui-core/tree/master/Tests"
    click Documentation "https://github.com/ovi-lab/hpui-core/tree/master/Documentation~"

    %% Styles
    classDef external fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef editor fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef runtime fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef legacy fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef samples fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef tests fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef documentation fill:#dda0dd,stroke:#333,stroke-width:2px;
```
