# joseph-wardle/sandwich-pipeline architecture

> Architecture diagram of the GitHub repository joseph-wardle/sandwich-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joseph-wardle/sandwich-pipeline
- Repository: https://github.com/joseph-wardle/sandwich-pipeline

## Overview

1. **Overall shape**
   - This is a Python-based production pipeline repo for multiple DCCs, not a single app.
   - The architecture is split into three major layers: a DCC-agnostic core, per-DCC integrations, and bundled runtime/site assets.
   - The repo is designed to run on multiple OSes and is configured externally through `src/env.py` rather than hardcoding studio-specific paths and credentials.

2. **Process entrypoint and dispatch**
   - `src/__main__.py` is the top-level entrypoint.
   - It dispatches into a DCC-specific launcher under `src/dcc/<dcc>/launch.py` via the shared framework layer.
   - This means the same repo can start Blender, Maya, Houdini, Nuke, Substance Painter, or Substance Designer workflows through a common startup path.

3. **Framework boundary**
   - `src/framework` defines the launcher/runtime abstraction layer.
   - It provides the common interface for “launch a DCC” and “run inside a DCC runtime,” plus dispatch logic.
   - This is the seam that keeps platform startup code separate from pipeline logic and DCC-specific implementation details.

4. **Cross-DCC core services**
   - `src/core` holds the reusable pipeline services shared across all DCCs.
   - Key domains include asset paths/version adapters, shot/version adapters, versioning storage and service logic, ShotGrid integration, playblast generation, texture conversion, telemetry, and UI dialogs.
   - These modules are the main business logic boundary: they should be reusable without knowing which DCC is currently running.

5. **Versioning and file identity**
   - `src/core/versioning` appears to be the central model/service/store for versioned pipeline artifacts.
   - Asset, shot, and environment-specific `version_adapter.py` files suggest that different content types are normalized into a common versioning scheme.
   - This likely underpins save/version browser dialogs, publish flows, and asset/shot file naming.

6. **Asset, shot, and environment modeling**
   - `src/core/asset`, `src/core/shot`, and `src/core/environment` provide content-domain abstractions.
   - `src/core/util/paths.py`, `src/core/asset/paths.py`, and `src/core/shotgrid/paths.py` indicate a strong path-convention layer that maps studio storage layout into objects and services.
   - `src/core/struct` contains serializable data models like timeline and material structures, likely used across publishing, UI, and exports.

7. **Publishing and playblasts**
   - `src/core/playblast` centralizes playblast naming, encoding, presets, temp directory handling, and review upload flow.
   - The `review` subpackage suggests a review-oriented workflow: create playblasts, associate versions/playlists, and upload or sync them to an external review system.
   - DCC-specific playblast modules in Maya and Houdini wrap this core logic with host-specific HUDs, dialogs, and launchers.

8. **ShotGrid integration**
   - `src/core/shotgrid` is a dedicated client boundary for the studio’s ShotGrid backend.
   - It includes entities, errors, caching/memoization, and path helpers, implying the pipeline reads and writes production metadata from ShotGrid rather than embedding that logic in each DCC.
   - This is one of the main external-service integrations in the repo.

9. **Telemetry subsystem**
   - `src/core/telemetry` is a self-contained event collection and upload pipeline.
   - It includes event definitions, scope/config, local spooling, a local stack/ingester, and a standalone `__main__.py`, suggesting telemetry can run independently of the DCC tools.
   - The `telemetry-backend` directory provides the server-side destination: PostgreSQL schema plus Grafana dashboards/provisioning for monitoring tool health and usage.

10. **Per-DCC integration model**
   - Each DCC directory under `src/dcc` follows the same pattern: `launch.py`, `runtime.py`, `site/`, and DCC-specific tool modules.
   - These packages bridge the generic core into host APIs and startup conventions for Blender, Houdini, Maya, Nuke, Substance Painter, and Substance Designer.
   - The architecture keeps host-specific code localized, while shared pipeline rules remain in `src/core`.

11. **Embedded runtime/site customization**
   - The `site/` trees contain startup scripts, shelves, menus, packages, HDAs/gizmos/toolsets, and configuration files that are installed into each DCC’s runtime environment.
   - Examples include Maya shelves and startup scripts, Houdini packages/OTLs/python startup, Nuke menu and gizmos, and Substance Painter startup hooks.
   - This is how the repo injects pipeline behavior into third-party applications without patching those applications directly.

12. **DCC-specific workflows**
   - Maya includes substantial subdomains for asset files, shot files, layout, rig building, publishing, playblasts, and symmetry tools.
   - Houdini includes Solaris/Lop-centric publishing, playblast, shading, shot processing, and bundled third-party tools.
   - Blender has a smaller but focused integration for asset-file handling, launch, publish, and plugin registration.
   - Nuke, Substance Painter, and Substance Designer are narrower integrations centered on launch, startup, and specialized export/publish flows.

13. **Shared resources and packaged data**
   - `resources/` holds first-party non-Python assets such as HDRIs, icons, splash screens, textures, USD kinds, and Substance Designer files.
   - These resources are part of the runtime data model, not just documentation; they support launchers, tool UIs, and render/lookdev workflows.
   - `desktop_launchers/` and `install_desktop_launchers.py` provide OS-level entry points for launching the DCC tooling.

14. **Operational boundaries and configuration**
   - The repo depends on external environment configuration and studio infrastructure, especially `src/env.py`, which is intentionally documented separately.
   - That configuration likely supplies executable paths, ShotGrid credentials, and site-specific filesystem roots.
   - The project also includes Git hooks and CI, but they support code quality rather than altering runtime architecture.

Main entry points: [`src/framework/dispatch.py`](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/dispatch.py) (Dispatch), [`src/core/versioning`](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/versioning) (Versioning), [`src/dcc/maya`](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/maya) (Maya), [`src/dcc/houdini`](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/houdini) (Houdini)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_root["Entry & framework"]
  node_node_main["Main entry<br/>python entrypoint<br/>[__main__.py]"]
  node_node_framework_dispatch["Dispatch<br/>runtime router<br/>[dispatch.py]"]
  node_node_framework_interface["Interface<br/>launcher contract<br/>[interface.py]"]
  node_node_framework_launcher["Launcher<br/>startup orchestration<br/>[launcher.py]"]
  node_node_env["Env config<br/>external configuration<br/>[env.py.md]"]
end

subgraph group_group_core["Shared pipeline core"]
  node_node_versioning[("Versioning<br/>artifact model")]
  node_node_asset_model["Asset model<br/>content domain"]
  node_node_shot_model["Shot model<br/>content domain"]
  node_node_playblast["Playblast<br/>review pipeline"]
  node_node_shotgrid["ShotGrid<br/>external client"]
  node_node_telemetry["Telemetry<br/>event pipeline"]
  node_node_texture["Texture tools<br/>conversion service<br/>[converter.py]"]
  node_node_ui["Shared UI<br/>dialogs and views"]
  node_node_struct["Data structs<br/>serializable models"]
end

subgraph group_group_dcc["DCC integrations"]
  node_node_maya["Maya<br/>dcc integration"]
  node_node_houdini["Houdini<br/>dcc integration"]
  node_node_blender["Blender<br/>dcc integration"]
  node_node_nuke["Nuke<br/>dcc integration"]
  node_node_spainter["Painter<br/>dcc integration"]
  node_node_sdesigner["Designer<br/>dcc integration"]
end

subgraph group_group_assets["Bundled assets"]
  node_node_resources[("Resources<br/>packaged assets")]
  node_node_launchers["Desktop launchers<br/>os entrypoints"]
  node_node_telemetry_backend[("Telemetry backend<br/>server stack")]
end

node_node_main -->|"starts"| node_node_framework_dispatch
node_node_framework_dispatch -->|"uses"| node_node_framework_interface
node_node_framework_dispatch -->|"invokes"| node_node_framework_launcher
node_node_framework_launcher -->|"reads config"| node_node_env
node_node_framework_dispatch -->|"selects"| node_node_maya
node_node_framework_dispatch -->|"selects"| node_node_houdini
node_node_framework_dispatch -->|"selects"| node_node_blender
node_node_framework_dispatch -->|"selects"| node_node_nuke
node_node_framework_dispatch -->|"selects"| node_node_spainter
node_node_framework_dispatch -->|"selects"| node_node_sdesigner
node_node_maya -->|"uses"| node_node_versioning
node_node_maya -->|"uses"| node_node_playblast
node_node_maya -->|"uses"| node_node_shotgrid
node_node_houdini -->|"uses"| node_node_versioning
node_node_houdini -->|"uses"| node_node_playblast
node_node_houdini -->|"uses"| node_node_shotgrid
node_node_blender -->|"uses"| node_node_versioning
node_node_spainter -->|"uses"| node_node_texture
node_node_spainter -->|"uses"| node_node_versioning
node_node_telemetry -->|"uploads to"| node_node_telemetry_backend
node_node_resources -.->|"supports"| node_node_playblast
node_node_launchers -->|"starts"| node_node_main
node_node_ui -.->|"supports"| node_node_versioning
node_node_asset_model -->|"feeds"| node_node_versioning
node_node_shot_model -->|"feeds"| node_node_versioning
node_node_struct -.->|"supports"| node_node_versioning
node_node_shotgrid -.->|"configured by"| node_node_env

click node_node_main "https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/__main__.py"
click node_node_framework_dispatch "https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/dispatch.py"
click node_node_framework_interface "https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/interface.py"
click node_node_framework_launcher "https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/launcher.py"
click node_node_env "https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/env.py.md"
click node_node_versioning "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/versioning"
click node_node_asset_model "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/asset"
click node_node_shot_model "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/shot"
click node_node_playblast "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/playblast"
click node_node_shotgrid "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/shotgrid"
click node_node_telemetry "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/telemetry"
click node_node_texture "https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/core/texture/converter.py"
click node_node_ui "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/ui"
click node_node_struct "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/struct"
click node_node_maya "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/maya"
click node_node_houdini "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/houdini"
click node_node_blender "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/blender"
click node_node_nuke "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/nuke"
click node_node_spainter "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/substance_painter"
click node_node_sdesigner "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/substance_designer"
click node_node_resources "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/resources"
click node_node_launchers "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/desktop_launchers"
click node_node_telemetry_backend "https://github.com/joseph-wardle/sandwich-pipeline/tree/main/telemetry-backend"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_framework_dispatch,node_node_framework_interface,node_node_framework_launcher,node_node_env toneBlue
class node_node_versioning,node_node_asset_model,node_node_shot_model,node_node_playblast,node_node_shotgrid,node_node_telemetry,node_node_texture,node_node_ui,node_node_struct toneAmber
class node_node_maya,node_node_houdini,node_node_blender,node_node_nuke,node_node_spainter,node_node_sdesigner toneMint
class node_node_resources,node_node_launchers,node_node_telemetry_backend toneRose
```

## Components

### Entry & framework

Process entrypoint, dispatch, and runtime abstraction.

- [Main entry](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/__main__.py): python entrypoint · Top-level process entrypoint for the pipeline tools. · `src/__main__.py`
- [Dispatch](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/dispatch.py): runtime router · Selects the appropriate DCC launcher/runtime path. · `src/framework/dispatch.py`
- [Interface](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/interface.py): launcher contract · Defines the shared launch/runtime abstraction boundary. · `src/framework/interface.py`
- [Launcher](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/framework/launcher.py): startup orchestration · Common launcher helpers used by DCC integrations. · `src/framework/launcher.py`
- [Env config](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/env.py.md): external configuration · Studio/site-specific paths, credentials, and executable settings. · `src/env.py.md`

### Shared pipeline core

Cross-DCC business logic and shared services.

- [Versioning](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/versioning): artifact model · Central model, service, and storage for versioned pipeline artifacts. · `src/core/versioning`
- [Asset model](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/asset): content domain · Asset path conventions and asset version adaptation. · `src/core/asset`
- [Shot model](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/shot): content domain · Shot version adaptation and shot-oriented content rules. · `src/core/shot`
- [Playblast](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/playblast): review pipeline · Shared playblast naming, encoding, temp handling, and review upload flow. · `src/core/playblast`
- [ShotGrid](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/shotgrid): external client · Client boundary for production metadata, entities, caching, and paths. · `src/core/shotgrid`
- [Telemetry](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/telemetry): event pipeline · Event emission, local spool, ingestion, and standalone telemetry runtime. · `src/core/telemetry`
- [Texture tools](https://github.com/joseph-wardle/sandwich-pipeline/blob/main/src/core/texture/converter.py): conversion service · Shared texture conversion utilities used by DCC workflows. · `src/core/texture/converter.py`
- [Shared UI](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/ui): dialogs and views · Common dialogs, progress UI, save/version browser components. · `src/core/ui`
- [Data structs](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/core/struct): serializable models · Reusable serializable structures for timeline, material, and JSON data. · `src/core/struct`

### DCC integrations

Host-specific launch, runtime, and workflows for each DCC.

- [Maya](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/maya): dcc integration · Maya launch/runtime, site customization, and deep workflow modules. · `src/dcc/maya`
- [Houdini](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/houdini): dcc integration · Houdini launch/runtime plus Solaris, publish, playblast, and site assets. · `src/dcc/houdini`
- [Blender](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/blender): dcc integration · Blender launch, asset handling, publish, and addon registration. · `src/dcc/blender`
- [Nuke](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/nuke): dcc integration · Nuke launch plus studio menu, gizmo, and toolset bundle. · `src/dcc/nuke`
- [Painter](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/substance_painter): dcc integration · Substance Painter launch, runtime, startup hooks, and export publish flow. · `src/dcc/substance_painter`
- [Designer](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/src/dcc/substance_designer): dcc integration · Substance Designer launch and packaged project/site configuration. · `src/dcc/substance_designer`

### Bundled assets

Packaged runtime data, desktop launchers, and telemetry backend.

- [Resources](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/resources): packaged assets · First-party runtime assets such as HDRIs, icons, splash screens, and USD kinds. · `resources`
- [Desktop launchers](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/desktop_launchers): os entrypoints · OS-level desktop files and installer for launching the tool suite. · `desktop_launchers`
- [Telemetry backend](https://github.com/joseph-wardle/sandwich-pipeline/tree/main/telemetry-backend): server stack · PostgreSQL schema and Grafana provisioning for telemetry storage and dashboards. · `telemetry-backend`

## Connections

- Main entry → Dispatch: starts · Process entrypoint hands off to shared dispatch.
- Dispatch → Interface: uses · Dispatch routes through the common runtime contract.
- Dispatch → Launcher: invokes · Shared launcher helpers coordinate startup.
- Launcher → Env config: reads config · Executable paths and studio settings come from external env config.
- Dispatch → Maya: selects · Dispatch can enter the Maya integration.
- Dispatch → Houdini: selects · Dispatch can enter the Houdini integration.
- Dispatch → Blender: selects · Dispatch can enter the Blender integration.
- Dispatch → Nuke: selects · Dispatch can enter the Nuke integration.
- Dispatch → Painter: selects · Dispatch can enter Substance Painter.
- Dispatch → Designer: selects · Dispatch can enter Substance Designer.
- Maya → Versioning: uses · Maya workflows rely on shared versioning services.
- Maya → Playblast: uses · Maya playblasts wrap the shared playblast pipeline.
- Maya → ShotGrid: uses · Maya tools consume production metadata from ShotGrid.
- Houdini → Versioning: uses · Houdini workflows rely on shared versioning services.
- Houdini → Playblast: uses · Houdini playblasts wrap the shared playblast pipeline.
- Houdini → ShotGrid: uses · Houdini tools consume production metadata from ShotGrid.
- Blender → Versioning: uses · Blender workflows rely on shared versioning services.
- Painter → Texture tools: uses · Painter export flows depend on texture and material utilities.
- Painter → Versioning: uses · Painter publish flows participate in versioned artifacts.
- Telemetry → Telemetry backend: uploads to · Telemetry events are stored and visualized by the backend stack.
- Resources → Playblast: supports · Packaged fonts and runtime assets support playblast/review output.
- Desktop launchers → Main entry: starts · Desktop entries launch the pipeline entrypoint.
- Shared UI → Versioning: supports · Dialogs and browser UI sit on top of versioned artifacts.
- Asset model → Versioning: feeds · Asset naming and adapters normalize into versioning.
- Shot model → Versioning: feeds · Shot naming and adapters normalize into versioning.
- Data structs → Versioning: supports · Serializable domain structs are shared across services and UI.
- ShotGrid → Env config: configured by · Backend credentials and paths are supplied externally.
