# ynput/ayon-motionbuilder architecture

> Architecture diagram of the GitHub repository ynput/ayon-motionbuilder, 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-motionbuilder
- Repository: https://github.com/ynput/ayon-motionbuilder

## Overview

##### Project type and purpose
- This is not a full-stack website or microservice mesh, but an Autodesk MotionBuilder addon (“client”) that integrates MotionBuilder into the Ayon pipeline. It provides import/export hooks, menu items, and publishing workflows inside MotionBuilder, and it communicates with an Ayon “server” (pipeline service) for settings, versioning, and publishing.

##### File structure
- Top-level:
- client/ayon_motionbuilder – Python package loaded as the MotionBuilder addon
- server/settings.py – empty stub for server-side configs (Ayon server)
- create_package.py & package.py & pyproject.toml – scripts and config for building the addon
- docs/ & mkdocs.yml – documentation site
- .github/workflows – CI/CD (lint, release, upload to Ynput cloud)
- client/ayon_motionbuilder splits into:
- addon.py & version.py – entry points for the plugin
- api/ – wrappers to talk to Ayon’s REST API, pipeline utils, menu and plugin registration
- hooks/ – code injected into MotionBuilder at startup or via scripts
- plugins/{create,load,publish}/ – discrete workflow steps (create animations, load caches, publish work files)

##### README for additional insights
- Describes required user settings (MotionBuilder binary path in Ayon UI)
- Lists supported workflows (import model/rig/animation, export animation, open/save/publish workfiles)
- Instructs users to run create_package.py to assemble the addon for distribution

##### Components and interactions
a. Main components
1. Autodesk MotionBuilder Application (external 3D DCC)
2. Ayon MotionBuilder Addon (the client plugin)
– Entry module (addon.py)
– API submodule (lib.py, pipeline.py, menu.py, plugin.py)
– Hooks (startup scripts, injected Python)
– Workflow plugins (create, load, publish)
3. Ayon Pipeline Server (settings registry, version control, publishing endpoints)
4. Packaging & CI/CD
– create_package.py / package.py (build logic)
– GitHub Actions (lint, release, upload)
5. Documentation site (mkdocs)
b. Relationships & data flow
- On MotionBuilder launch, the Addon’s startup hook registers menu items and initializes the API.
- When the user invokes a workflow (e.g., “Publish Animation”), the plugin calls into api/pipeline.py, which sends HTTP requests to the Ayon server.
- The server responds with project settings, version numbers, storage locations.
- The plugin reads/writes the MotionBuilder scene and pushes files back to Ayon’s storage.
- Packaging scripts bundle the client code into an installable MotionBuilder addon, while GitHub Actions automate testing and releases.
c. Architectural patterns & design principles
- Modular plugin design: each workflow step is its own plugin under plugins/
- Clear separation of concerns between MotionBuilder API calls (hooks/), pipeline communication (api/), and packaging
- CI/CD ensures repeatable builds and automated release to cloud or PyPI
d. Key technologies/frameworks
- Python 3.x packaging (pyproject.toml)
- Ayon REST API (HTTP client inside api/lib.py)
- MotionBuilder Python environment (injected hooks & scripts)
- GitHub Actions for CI/CD
- MkDocs for documentation

##### Summary Guidance
- Break the plugin into its runtime modules (entry, API, hooks, workflows).
- How those modules interact at startup and during user-driven workflows.
- External dependencies: MotionBuilder host and Ayon server endpoints.
- Build/release subsystem as a secondary but important pathway.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Components
    subgraph "Runtime Environment"
        direction TB
        MBApp["Autodesk MotionBuilder App"]:::external
        subgraph "Ayon MotionBuilder Addon" 
            direction TB
            Entry["Entry Module<br/>addon.py"]:::runtime
            Version["Version Info<br/>version.py"]:::runtime
            subgraph "API Layer"
                direction TB
                RESTClient["REST Client & Utils<br/>lib.py"]:::runtime
                PipelineAPI["Pipeline Comm<br/>pipeline.py"]:::runtime
                MenuReg["Menu Registration<br/>menu.py"]:::runtime
                PluginReg["Plugin Registration<br/>plugin.py"]:::runtime
            end
            subgraph "Hooks"
                direction TB
                Injected["Injected Python<br/>injected_python.py"]:::runtime
                StartupScript["Startup Script<br/>startup_script.py"]:::runtime
                StartupEntry["Startup Entry<br/>startup.py"]:::runtime
            end
            subgraph "Workflow Plugins"
                direction TB
                subgraph "Create"
                    CreateAnim["create_animation.py"]:::runtime
                    CreateWorkfile["create_workfile.py"]:::runtime
                end
                subgraph "Load"
                    LoadCache["load_pointcache.py"]:::runtime
                end
                subgraph "Publish"
                    CollectFile["collect_current_file.py"]:::runtime
                    CollectWorkfile["collect_workfile.py"]:::runtime
                    ExtractAnim["extract_animation.py"]:::runtime
                    IncVersion["increment_workfile_version.py"]:::runtime
                    ValidateScene["validate_scene_saved.py"]:::runtime
                end
            end
        end
        AyonServer["Ayon Pipeline Server"]:::runtime
    end

    %% Build & Deploy
    subgraph "Build & CI/CD" 
        direction TB
        BuildScript["create_package.py"]:::build
        PackageLogic["package.py"]:::build
        PyProj["pyproject.toml"]:::build
        subgraph "GitHub Actions"
            direction TB
            AssignPR["assign_pr_to_project.yml"]:::build
            PRLint["pr_linting.yml"]:::build
            ReleaseTrigger["release_trigger.yml"]:::build
            UploadCloud["upload_to_ynput_cloud.yml"]:::build
            ValidateLabels["validate_pr_labels.yml"]:::build
        end
    end

    %% Documentation
    subgraph "Documentation Portal" 
        direction TB
        DocsSrc["docs/index.md<br/>docs/license.md"]:::doc
        Assets["docs/css/custom.css<br/>docs/img/*"]:::doc
        MkConfig["mkdocs.yml"]:::doc
        MkHooks["mkdocs_hooks.py"]:::doc
    end

    %% Relationships
    MBApp -->|"Python callback"| Entry
    Entry --> Version
    Entry --> RESTClient
    Entry --> PipelineAPI
    Entry --> MenuReg
    Entry --> PluginReg
    Entry --> Injected
    Entry --> StartupScript
    Entry --> StartupEntry
    PipelineAPI -->|"HTTP JSON"| AyonServer
    CollectFile --> PipelineAPI
    CollectWorkfile --> PipelineAPI
    ExtractAnim --> PipelineAPI
    IncVersion --> PipelineAPI
    ValidateScene --> PipelineAPI
    LoadCache --> PipelineAPI
    CreateAnim --> PipelineAPI
    CreateWorkfile --> PipelineAPI

    BuildScript --> PackageLogic
    PackageLogic --> Entry
    PackageLogic --> Version
    AssignPR --> BuildScript
    PRLint --> BuildScript
    ReleaseTrigger --> PackageLogic
    UploadCloud --> ReleaseTrigger
    ValidateLabels --> ReleaseTrigger

    DocsSrc --> MkConfig
    MkHooks --> MkConfig
    Assets --> MkConfig

    %% Click Events
    click Entry "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/addon.py"
    click Version "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/version.py"
    click RESTClient "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/api/lib.py"
    click PipelineAPI "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/api/pipeline.py"
    click MenuReg "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/api/menu.py"
    click PluginReg "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/api/plugin.py"
    click Injected "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/hooks/injected_python.py"
    click StartupScript "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/hooks/startup_script.py"
    click StartupEntry "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/startup/startup.py"
    click CreateAnim "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/create/create_animation.py"
    click CreateWorkfile "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/create/create_workfile.py"
    click LoadCache "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/load/load_pointcache.py"
    click CollectFile "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/publish/collect_current_file.py"
    click CollectWorkfile "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/publish/collect_workfile.py"
    click ExtractAnim "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/publish/extract_animation.py"
    click IncVersion "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/publish/increment_workfile_version.py"
    click ValidateScene "https://github.com/ynput/ayon-motionbuilder/blob/develop/client/ayon_motionbuilder/plugins/publish/validate_scene_saved.py"
    click AyonServer "https://github.com/ynput/ayon-motionbuilder/blob/develop/server/settings.py"
    click BuildScript "https://github.com/ynput/ayon-motionbuilder/blob/develop/create_package.py"
    click PackageLogic "https://github.com/ynput/ayon-motionbuilder/blob/develop/package.py"
    click PyProj "https://github.com/ynput/ayon-motionbuilder/blob/develop/pyproject.toml"
    click AssignPR "https://github.com/ynput/ayon-motionbuilder/blob/develop/.github/workflows/assign_pr_to_project.yml"
    click PRLint "https://github.com/ynput/ayon-motionbuilder/blob/develop/.github/workflows/pr_linting.yml"
    click ReleaseTrigger "https://github.com/ynput/ayon-motionbuilder/blob/develop/.github/workflows/release_trigger.yml"
    click UploadCloud "https://github.com/ynput/ayon-motionbuilder/blob/develop/.github/workflows/upload_to_ynput_cloud.yml"
    click ValidateLabels "https://github.com/ynput/ayon-motionbuilder/blob/develop/.github/workflows/validate_pr_labels.yml"
    click DocsSrc "https://github.com/ynput/ayon-motionbuilder/blob/develop/docs/index.md"
    click Assets "https://github.com/ynput/ayon-motionbuilder/blob/develop/docs/css/custom.css"
    click MkConfig "https://github.com/ynput/ayon-motionbuilder/blob/develop/mkdocs.yml"
    click MkHooks "https://github.com/ynput/ayon-motionbuilder/blob/develop/mkdocs_hooks.py"

    %% Styles
    classDef runtime fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef build fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef doc fill:#E8F5E9,stroke:#388E3C,color:#000
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000
```
