# ynput/ayon-substance-designer architecture

> Architecture diagram of the GitHub repository ynput/ayon-substance-designer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ynput/ayon-substance-designer
- Repository: https://github.com/ynput/ayon-substance-designer

## Overview

##### Project type and purpose
- This is an integration-plugin project: a Python-based Adobe Substance Designer addon that plugs into the AYON pipeline.
- Its goal is to let an artist inside Substance Designer create, load, and publish assets directly to an AYON server.

##### File structure
- Top-level directories:
- client/ayon_substancedesigner – the Substance Designer plugin and its API wrappers
- server/settings – default configuration for image I/O and main AYON settings
- docs – mkdocs‐based documentation
- Key Python packaging files: pyproject.toml, package.py, create_package.py
- CI/CD workflows under .github/workflows orchestrate linting, labeling, releases, and deployment to Ynput Cloud.

##### README
- Confirms the plugin’s purpose: “Adobe Substance Designer integration for AYON.”
- Points to the Substance 3D Designer scripting API, implying heavy use of Adobe’s Python scripting bridge.

##### Main components
a. Substance Designer host application
b. AYON plugin (client/ayon_substancedesigner)
- subdivided into API modules (lib, pipeline, plugin, project_creation)
- plugin hooks (addon.py) and deploy scripts
- sub-modules for create/load/publish steps
c. AYON Server
- Core AYON REST API endpoints
- Data store for assets, versions, and workfiles
- imageio service (server/settings/imageio.py)
d. External dependencies
- Adobe scripting API (External)
- CI/CD (GitHub Actions)
- Documentation site (MkDocs)

##### Relationships and interactions
- User triggers action in Substance Designer → the plugin’s addon.py
- Plugin calls into its internal API modules (client/api/*.py)
- API modules construct REST calls to the AYON Server for:
- Project creation
- Pipeline retrieval
- Uploading published assets (SBSAR, textures, workfiles)
- Server responds with job IDs, metadata, and storage URLs
- Plugin downloads or loads textures/workfiles when requested
- CI/CD workflows run on git events to lint, tag, and publish the plugin package

##### Architectural patterns and design principles
- Modular API wrapper: separate lib, pipeline, plugin, and project_creation concerns
- Plugin command pattern: each create/load/publish is its own module under plugins/
- Config-driven behavior: server/settings defines environment specifics
- Standard Python packaging and deployment (pyproject.toml, create_package.py)

##### Final advice
- Be meticulous: break the plugin into its API layer and command modules
- Full lifecycle: creation, loading, publishing, and CI/CD
- Don’t overthink—represent each logical component (api/lib, api/pipeline, plugins/create, etc.) as its own node for maximum clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Host
    SD["Substance Designer"]:::external

    %% AYON Plugin
    subgraph "AYON Plugin" 
        direction TB
        APIV1["lib.py"]:::client
        APIV2["pipeline.py"]:::client
        APIV3["plugin.py"]:::client
        APIV4["project_creation.py"]:::client
        ADDON["addon.py"]:::client
        DEPLOY["deploy/ayon_plugin.py"]:::client
        VERSION["version.py"]:::client

        subgraph "Commands"
            direction TB
            subgraph Create
                direction TB
                CSBSAR["create_sbsar.py"]:::client
                CTEX["create_textures.py"]:::client
                CWORK["create_workfile.py"]:::client
            end
            subgraph Load
                direction TB
                LTEXT["load_texture.py"]:::client
            end
            subgraph Publish
                direction TB
                PCF["collect_current_file.py"]:::client
                PCTI["collect_textureset_images.py"]:::client
                PCWR["collect_workfile_representation.py"]:::client
                ESBSAR["extract_sbsar.py"]:::client
                ETEX["extract_textures.py"]:::client
                IWORK["increment_workfile.py"]:::client
                SWORK["save_workfile.py"]:::client
            end
        end
    end

    %% AYON Server
    subgraph "AYON Server"
        direction TB
        API["Core REST API"]:::server
        DS["Data Store (Assets, Versions, Workfiles)"]:::server
        IMGIO["imageio Service"]:::server
    end

    %% External Services
    ADOBE["Adobe Scripting API"]:::external
    DOCS["MkDocs Documentation"]:::external
    CI["GitHub Actions CI/CD"]:::external

    %% Relationships
    SD -->|triggers| ADDON
    ADDON -->|uses| APIV1
    ADDON -->|uses| APIV2
    ADDON -->|uses| APIV3
    ADDON -->|uses| APIV4
    ADDON -->|deploy| DEPLOY
    ADDON -->|version| VERSION

    APIV1 -->|HTTP calls| API
    APIV2 -->|HTTP calls| API
    APIV3 -->|HTTP calls| API
    APIV4 -->|HTTP calls| API

    CSBSAR --> API
    CTEX --> API
    CWORK --> API

    LTEXT --> API

    PCF --> API
    PCTI --> API
    PCWR --> API
    ESBSAR --> API
    ETEX --> API
    IWORK --> API
    SWORK --> API

    API -->|responds| APIV3
    API --> DS
    API --> IMGIO
    IMGIO --> DS

    ADOBE -.-> SD
    DOCS -.-> APIV1
    CI -.-> DEPLOY
    CI -.-> ADDON

    %% Click Events
    click SD "https://github.com/ynput/ayon-substance-designer/tree/develop/External"
    click ADDON "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/addon.py"
    click APIV1 "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/api/lib.py"
    click APIV2 "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/api/pipeline.py"
    click APIV3 "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/api/plugin.py"
    click APIV4 "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/api/project_creation.py"
    click DEPLOY "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/deploy/ayon_plugin.py"
    click CSBSAR "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/create/create_sbsar.py"
    click CTEX "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/create/create_textures.py"
    click CWORK "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/create/create_workfile.py"
    click LTEXT "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/load/load_texture.py"
    click PCF "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/collect_current_file.py"
    click PCTI "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/collect_textureset_images.py"
    click PCWR "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/collect_workfile_representation.py"
    click ESBSAR "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/extract_sbsar.py"
    click ETEX "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/extract_textures.py"
    click IWORK "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/increment_workfile.py"
    click SWORK "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/plugins/publish/save_workfile.py"
    click VERSION "https://github.com/ynput/ayon-substance-designer/blob/develop/client/ayon_substancedesigner/version.py"
    click IMGIO "https://github.com/ynput/ayon-substance-designer/blob/develop/server/settings/imageio.py"
    click DS "https://github.com/ynput/ayon-substance-designer/blob/develop/server/settings/main.py"
    click DOCS "https://github.com/ynput/ayon-substance-designer/tree/develop/docs/"
    click CI "https://github.com/ynput/ayon-substance-designer/tree/develop/.github/workflows/"

    %% Styles
    classDef client fill:#B3D4FC,stroke:#094A8F,color:#000;
    classDef server fill:#D4FCD4,stroke:#187F1F,color:#000;
    classDef external fill:#FCE5CD,stroke:#A65F00,color:#000;
```
