# lvoxx/lspotato architecture

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

- Interactive diagram: https://gitdiagram.com/lvoxx/lspotato
- Repository: https://github.com/lvoxx/lspotato

## Overview

##### Project Type and Purpose
- This is a full-stack (local) Blender add-on written in Python.
- Purpose: provide “potato-style” automation inside Blender (mesh tweaks, material setup, custom utilities, auto-sync LSCherry shaders), plus CLI packaging/install commands.

##### File Structure Analysis
Top-level:
- package.py + potato.{sh,bat} – CLI entry point for packaging/installing/uninstalling/reloading the add-on.
- assets/ – static images used in README/UI.
- src/ – main Python code.
– constants/ – global configuration and version flags.
– features/ – grouped by functionality:
· autosync/… – auto-sync LSCherry provider & global configuration handlers/operators/ui layers.
· checkfor_update/… – “check-for-update” operators, UI & utils.
· find_lscherry/… – locate and repair LSCherry installations.
· make_local/… – convert remote materials/local copies.
· replace_nodes/… – node-replacement operators/UI.
· panels.py – central registration of UI panels.
– utils/ – helper modules for debugging, drawing UI, Blender/LSCherry introspection.
- .github/ – issue templates.
- venv/ – local Python environment.

##### Key Architectural Insights from README
- -on is loaded at Blender startup → registers features, UI panels, operators.
- Two subsystems: LSCherry Toon Shader loader and Potato Automation tools.
- Background processes (auto-reload, mesh fairing, UV mapping, validation).
- CLI tools orchestrate packaging/install lifecycle.

##### Main Components
a. Blender Environment
- Blender Startup → Add-on Manager
b. CLI Tool (“potato”)
- package/install/uninstall/reload
c. Core Add-on Components
1. Initialization Layer
– package.py entry hooks into Blender’s add-on registry
– registers operators, handlers, panels
2. LSCherry Toon Shader System
– src/constants (version, blend modes)
– src/features/find_lscherry (path resolution, download/repair)
– src/features/autosync/cherry_provider (sync handlers, UI)
3. Potato Automation System
– src/features/make_local
– src/features/replace_nodes
– src/features/checkfor_update
– src/utils (common utilities)
d. UI Layer
– src/features/panels.py defines shader editor panel, properties panel, tools panel
– each feature folder has ui.py (panel sub-sections)
e. Background Systems
– auto-reload libraries (dev reload)
– mesh fairing & planar UV (in utils)
– material validation
f. Data Flow & Interactions
– User clicks UI → triggers Operator → uses Utilities → updates Blender data (meshes, materials) → UI updates
– CLI calls package.py → builds .zip into dist/ → Blender sees changed add-on → optional auto-reload

##### Architectural Patterns & Principles
- Modular feature-based layout: each feature encapsulates operators, handlers, properties, UI, sync logic.
- Blender’s event-driven operator/handler model for UI interactions.
- Separation of concerns: constants vs. features vs. utilities vs. CLI.
- Dev-friendly hot-reload cycle.

##### Essential Elements
- Component labels (module or feature names)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Tools
    subgraph "CLI Tools" 
        direction TB
        CLI_pkg["package.py"]:::cli
        CLI_sh["potato.sh"]:::cli
        CLI_bat["potato.bat"]:::cli
    end

    %% Blender Startup
    Blender["Blender Startup"]:::external
    AddonMgr["Add-on Manager"]:::external

    %% Initialization Layer
    subgraph "Initialization Layer"
        direction TB
        Init_pkg["package.py"]:::init
        Init_init["src/__init__.py"]:::init
    end

    %% LSCherry Toon Shader System
    subgraph "LSCherry Shader System"
        direction TB
        subgraph "Constants"
            C1["app_const.py"]:::core
            C2["blend_mode.py"]:::core
            C3["lscherry_version.py"]:::core
        end
        subgraph "Find LSCherry"
            F1["lscherry_path.py"]:::core
            F2["download_and_extract.py"]:::core
            F3["repair_lscherry.py"]:::core
            F4["clean_linked_data.py"]:::core
            F5["operators.py"]:::core
            F6["properties.py"]:::core
        end
        subgraph "Auto-Sync Provider"
            A1["handlers.py"]:::core
            A2["operators.py"]:::core
            A3["properties.py"]:::core
            A4["sync.py"]:::core
            A5["ui.py"]:::ui
        end
        subgraph "Global Configuration"
            G1["handlers.py"]:::core
            G2["operators.py"]:::core
            G3["properties.py"]:::core
            G4["sync.py"]:::core
            G5["ui.py"]:::ui
        end
        US["uni.py"]:::core
    end

    %% Potato Automation System
    subgraph "Potato Automation System"
        direction TB
        ML["make_local/operators.py"]:::core
        RN1["replace_nodes/operators.py"]:::core
        RN2["replace_nodes/properties.py"]:::core
        CU1["checkfor_update/operators.py"]:::core
        CU2["checkfor_update/properties.py"]:::core
        CU3["checkfor_update/ui.py"]:::ui
        CU4["checkfor_update/utils.py"]:::core
        subgraph "Shared Utilities"
            U1["debug_code.py"]:::background
            U2["draw_ui.py"]:::background
            U3["get_blender_things.py"]:::background
            U4["get_lscherry_things.py"]:::background
        end
    end

    %% UI Layer
    subgraph "UI Panels"
        direction TB
        PNL["panels.py"]:::ui
        UI_cherry["cherry_provider/ui.py"]:::ui
        UI_global["global_configuration/ui.py"]:::ui
        UI_update["checkfor_update/ui.py"]:::ui
    end

    %% Background Systems
    subgraph "Background Systems"
        direction TB
        AR["Auto-Reload (Dev)"]:::background
        MF["Mesh Fairing & Planar UV"]:::background
        MV["Material Validation"]:::background
    end

    %% Connections
    CLI_pkg -->|"invoke pkg"| AddonMgr
    CLI_sh --> AddonMgr
    CLI_bat --> AddonMgr

    Blender --> AddonMgr
    AddonMgr --> Init_pkg
    AddonMgr --> Init_init

    Init_pkg -->|"register"| C1
    Init_pkg --> C2
    Init_pkg --> C3
    Init_pkg --> F1
    Init_pkg --> A1
    Init_pkg --> ML
    Init_pkg --> PNL

    PNL --> RN1
    PNL --> CU3
    UI_cherry --> A2
    UI_global --> G2
    UI_update --> CU1

    RN1 --> U2
    ML --> U3
    CU1 --> CU4
    F2 -->|"download"| AR
    AR --> Init_pkg
    MF --> U3
    MV --> U4

    %% Click Events CLI
    click CLI_pkg "https://github.com/lvoxx/lspotato/blob/main/package.py"
    click CLI_sh "https://github.com/lvoxx/lspotato/blob/main/potato.sh"
    click CLI_bat "https://github.com/lvoxx/lspotato/blob/main/potato.bat"

    %% Click Events Initialization
    click Init_pkg "https://github.com/lvoxx/lspotato/blob/main/package.py"
    click Init_init "https://github.com/lvoxx/lspotato/blob/main/src/__init__.py"

    %% Click Events Constants
    click C1 "https://github.com/lvoxx/lspotato/blob/main/src/constants/app_const.py"
    click C2 "https://github.com/lvoxx/lspotato/blob/main/src/constants/blend_mode.py"
    click C3 "https://github.com/lvoxx/lspotato/blob/main/src/constants/lscherry_version.py"

    %% Click Events Find LSCherry
    click F1 "https://github.com/lvoxx/lspotato/blob/main/src/features/find_lscherry/lscherry_path.py"
    click F2 "https://github.com/lvoxx/lspotato/blob/main/src/features/find_lscherry/download_and_extract.py"
    click F3 "https://github.com/lvoxx/lspotato/blob/main/src/features/find_lscherry/repair_lscherry.py"
    click F4 "https://github.com/lvoxx/lspotato/blob/main/src/features/find_lscherry/clean_linked_data.py"
    click F5 "https://github.com/lvoxx/lspotato/blob/main/src/features/find_lscherry/operators.py"
    click F6 "https://github.com/lvoxx/lspotato/blob/main/src/features/find_lscherry/properties.py"

    %% Click Events Auto-Sync Provider
    click A1 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/cherry_provider/handlers.py"
    click A2 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/cherry_provider/operators.py"
    click A3 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/cherry_provider/properties.py"
    click A4 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/cherry_provider/sync.py"
    click A5 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/cherry_provider/ui.py"

    %% Click Events Global Configuration
    click G1 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/global_configuration/handlers.py"
    click G2 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/global_configuration/operators.py"
    click G3 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/global_configuration/properties.py"
    click G4 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/global_configuration/sync.py"
    click G5 "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/global_configuration/ui.py"

    %% Click Events Auto-Sync Uni
    click US "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/uni.py"

    %% Click Events Automation
    click ML "https://github.com/lvoxx/lspotato/blob/main/src/features/make_local/operators.py"
    click RN1 "https://github.com/lvoxx/lspotato/blob/main/src/features/replace_nodes/operators.py"
    click RN2 "https://github.com/lvoxx/lspotato/blob/main/src/features/replace_nodes/properties.py"
    click CU1 "https://github.com/lvoxx/lspotato/blob/main/src/features/checkfor_update/operators.py"
    click CU2 "https://github.com/lvoxx/lspotato/blob/main/src/features/checkfor_update/properties.py"
    click CU3 "https://github.com/lvoxx/lspotato/blob/main/src/features/checkfor_update/ui.py"
    click CU4 "https://github.com/lvoxx/lspotato/blob/main/src/features/checkfor_update/utils.py"

    %% Click Events UI Panels
    click PNL "https://github.com/lvoxx/lspotato/blob/main/src/features/panels.py"
    click UI_cherry "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/cherry_provider/ui.py"
    click UI_global "https://github.com/lvoxx/lspotato/blob/main/src/features/autosync/global_configuration/ui.py"
    click UI_update "https://github.com/lvoxx/lspotato/blob/main/src/features/checkfor_update/ui.py"

    %% Click Events Utilities
    click U1 "https://github.com/lvoxx/lspotato/blob/main/src/utils/debug_code.py"
    click U2 "https://github.com/lvoxx/lspotato/blob/main/src/utils/draw_ui.py"
    click U3 "https://github.com/lvoxx/lspotato/blob/main/src/utils/get_blender_things.py"
    click U4 "https://github.com/lvoxx/lspotato/blob/main/src/utils/get_lscherry_things.py"

    %% Styles
    classDef cli fill:#d8b4fe,stroke:#a78bfa
    classDef init fill:#93c5fd,stroke:#3b82f6
    classDef core fill:#fdba74,stroke:#f97316
    classDef ui fill:#a7f3d0,stroke:#10b981
    classDef background fill:#e5e7eb,stroke:#9ca3af
    classDef external fill:#fef3c7,stroke:#fde047
```
