# not-elm/desktop_homunculus architecture

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

- Interactive diagram: https://gitdiagram.com/not-elm/desktop_homunculus
- Repository: https://github.com/not-elm/desktop_homunculus

## Overview

##### Main Components
- Core Application Logic:
- Entry Point (src/main.rs) and initialization code.
- Modules for handling the desktop window on different platforms (src/application_windows and src/global_window with platform-specific code for macOS and Windows).
- Systems managing the mascot behavior (src/mascot), including drag, rendering layers, sitting, etc.
- VRM and VRMA modules (e.g. src/vrm, src/vrma) for loading models, handling expressions, managing animations/transitions, and retargeting.
- System parameters (src/system_param) which include bone offsets, cameras, monitors, and other low-level integration aspects.

- Assets Management:
- Assets directory housing models, animations (organized into group folders under assets/animations), and UI-related files.
- The animations are logically grouped by action (idle, drag, sit_down, etc.), which is a core design element.

- Desktop UI:
- The UI folder (ui/) contains a TypeScript/React-like application (tsx files, Vite config) that provides settings and controls (e.g., mascot settings, menu actions) to alter animation behavior.

- Build & Deployment:
- The build directory contains platform-specific build scripts and resources for Windows, macOS, Android, and even web.

##### Relationships and Data Flow
- How the UI (frontend) interacts with the core application:
- E.g., a settings change in the UI component (ui/src/Settings.tsx) sends commands to the core, which then uses modules from src/mascot and src/settings to update the mascot’s state.

- Assets Flow:
- How the assets folder is consumed by the VRMA/VRM modules for loading animation files and VRM models.
- Different directories under assets/animations correspond to action groups used by the animation system.

- Platform-Specific Behaviors:

- Build and Deployment Pipelines:

##### Architectural Patterns and Technologies
- Modular design with clear separation:
- Core logic is in Rust; UI is written in TypeScript with React-style components.
- The animation system uses action-transition patterns (auto, manual, none) that drive the state evolution for the mascots.

- Dependencies and external libraries:
- The project uses Rust’s Cargo for dependency management (Cargo.toml and Cargo.lock) and likely leverages libraries such as Bevy (reference in credits) as part of its game/application template for rendering.
- The UI is built using the modern TypeScript workflow (Vite configuration, pnpm lock files).

- Cross-Platform Considerations:
- The codebase provides specific modules and builds for handling differences across Windows, macOS, and other platforms.

##### Instructing the Principal Software Engineer
- Next, drill down into each segment:
- For the Assets, show the structured directories (models and various animation groups) that feed into the VRM and VRMA modules.

- Flow from the assets directory into VRM loading routines.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Application
    subgraph "Core Application"
        EntryPoint["Entry Point (src/main.rs)"]:::backend
        subgraph "Window Management"
            AppWindows["Application Windows (src/application_windows.rs & dir)"]:::backend
            GlobalWindow["Global Window (src/global_window.rs & dir)"]:::backend
        end
        subgraph "Mascot Management"
            Mascot["Mascot Logic (src/mascot.rs & dir)"]:::backend
        end
        subgraph "VRM Handling"
            VRM["VRM Loader (src/vrm.rs & dir)"]:::backend
        end
        subgraph "VRMA Animation"
            VRMA["VRMA Engine (src/vrma.rs & dir)"]:::backend
        end
        subgraph "System Parameters"
            SystemParam["System Parameters (src/system_param.rs & dir)"]:::backend
        end
    end

    %% Assets Management
    subgraph "Assets"
        Models["Models (assets/models)"]:::assets
        Animations["Animations (assets/animations)"]:::assets
        UIAssets["UI Assets (assets/ui)"]:::assets
    end

    %% Desktop User Interface (UI)
    subgraph "Desktop User Interface"
        UIApp["UI Application (ui/)"]:::frontend
        UISrc["UI Source Code (ui/src/)"]:::frontend
    end

    %% Build and Deployment Pipeline
    subgraph "Build & Deployment"
        BuildScript["Build Script (build.rs)"]:::build
        BuildResources["Build Resources (build/)"]:::build
        CIWorkflow["CI/CD Workflows (.github/workflows)"]:::build
    end

    %% Relationships and Data Flow

    %% UI interactions with Core Mascot Management
    UISrc -->|"sendsSettingsCommand"| Mascot
    UIApp -->|"controlsMascot"| Mascot

    %% Assets flow to Animation and Model Loading
    Animations -->|"feedsAnimation"| VRMA
    Models -->|"feedsModel"| VRM
    UIAssets -->|"supportsUI"| UIApp

    %% System Parameters configures Window Management
    SystemParam -->|"configures"| AppWindows
    SystemParam -->|"configures"| GlobalWindow

    %% Build Pipeline integration with Core Application
    BuildScript -->|"builds"| EntryPoint
    BuildResources -->|"packages"| EntryPoint
    CIWorkflow -->|"triggersBuild"| BuildScript

    %% Optional arrow: Core Application Entry initiates Window Management
    EntryPoint -->|"initializes"| AppWindows
    EntryPoint -->|"initializes"| GlobalWindow

classDef backend fill:#aec6cf,stroke:#000,stroke-width:1px;
classDef frontend fill:#98fb98,stroke:#000,stroke-width:1px;
classDef assets fill:#fdfd96,stroke:#000,stroke-width:1px;
classDef build fill:#ffb347,stroke:#000,stroke-width:1px;

%% Click Events
click EntryPoint "https://github.com/not-elm/desktop_homunculus/blob/main/src/main.rs"
click AppWindows "https://github.com/not-elm/desktop_homunculus/blob/main/src/application_windows.rs"
click GlobalWindow "https://github.com/not-elm/desktop_homunculus/blob/main/src/global_window.rs"
click Mascot "https://github.com/not-elm/desktop_homunculus/blob/main/src/mascot.rs"
click VRM "https://github.com/not-elm/desktop_homunculus/blob/main/src/vrm.rs"
click VRMA "https://github.com/not-elm/desktop_homunculus/blob/main/src/vrma.rs"
click SystemParam "https://github.com/not-elm/desktop_homunculus/blob/main/src/system_param.rs"
click Models "https://github.com/not-elm/desktop_homunculus/tree/main/assets/models"
click Animations "https://github.com/not-elm/desktop_homunculus/tree/main/assets/animations"
click UIAssets "https://github.com/not-elm/desktop_homunculus/tree/main/assets/ui"
click UIApp "https://github.com/not-elm/desktop_homunculus/tree/main/ui/"
click UISrc "https://github.com/not-elm/desktop_homunculus/tree/main/ui/src/"
click BuildScript "https://github.com/not-elm/desktop_homunculus/blob/main/build.rs"
click BuildResources "https://github.com/not-elm/desktop_homunculus/tree/main/build/"
click CIWorkflow "https://github.com/not-elm/desktop_homunculus/tree/main/.github/workflows"
```
