# ideo/avocado architecture

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

- Interactive diagram: https://gitdiagram.com/ideo/avocado
- Repository: https://github.com/ideo/avocado

## Overview

##### Project type and purpose
- This is an open-source plugin library (Avocado) for Quartz Composer (QC) / Origami.
- It provides a suite of ready-to-use “patch” bundles (.plugin) that extend QC’s interactive prototyping capabilities (interactions, Bluetooth, animations, global values, utilities).
- It ships with example compositions (.qtz) and Arduino sketches to demonstrate usage.

##### Main components
a. Quartz Composer Application (host)
b. Origami Framework (plugin extension layer inside QC)
c. Avocado Plugin Manager (just the directory of bundles, loaded at QC startup)
d. Avocado Plug-Ins (each bundle in “Avocado Plug-Ins/… .plugin”)
– Interactions (Draggable, Carousel, Bistable, Card, Dial, Master-Detail, Rolodex, Hit Grid, iOS Keyboard)
– Bluetooth Integration (Bluetooth Send, Receive, Connection, Aggregate/Disaggregate)
– Animations (Nod, Pulse, Jiggle, Jump)
– Global Value (Save/Retrieve Boolean, Save/Retrieve String)
– Utilities (Keyboard 2, Delay Value, Gate, Invert, Map to Range, Absolute Value, String to Number)
e. Example Compositions (“Examples/… .qtz”) and sample Arduino code (“Examples/Bluetooth/*/*.ino”)
f. External Services
– Core Bluetooth (macOS BLE stack)
– BLE devices / Arduino boards

##### Relationships and data flows
- QC launches → loads Origami → scans “Avocado Plug-Ins” directory → dynamically loads each .plugin bundle
- Each plugin registers one or more patches with the Origami runtime
- Inside a .qtz composition:
- Patches are wired together in QC’s dataflow graph → values/signals propagate from patch outputs → patch inputs
- Bluetooth patches invoke Core Bluetooth APIs → connect to nearby BLE devices or Arduino boards (via BLE)
- Global Value patches read/write to a shared store accessible across compositions
- Examples demonstrate end-to-end usage: patch graph + BLE device or UI animation

##### Architectural patterns / design principles
- Plugin-based architecture: bundles loaded at runtime
- Modular categorization: grouping by functionality (Interactions, Bluetooth, Animations, etc.)
- Dataflow programming model (Quartz Composer graph)
- Separation of concerns: each patch implements a single piece of functionality
- Extensibility: new patches can be dropped into the plugin folder

##### Essential elements
- Annotations calling out major categories (Interactions, Bluetooth, etc.)
- A boundary around QC to indicate the host process

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Layer
    subgraph "Quartz Composer Host" 
        direction TB
        QC["Quartz Composer App"]:::host
        Origami["Origami Framework"]:::host
    end

    QC -->|"loads"| Origami
    Origami -->|"invokes loader"| PluginLoader["Avocado Plugin Manager"]:::manager
    click PluginLoader "https://github.com/ideo/avocado/tree/master/Avocado Plug-Ins/"

    %% Plugin Layer
    subgraph "Avocado Plug-Ins Directory" 
        direction TB
        PluginLoader --> PluginDir["Avocado Plug-Ins"]:::manager

        subgraph "Interactions" 
            direction TB
            Draggable["Draggable.plugin"]:::interactions
            Carousel["Carousel.plugin"]:::interactions
            Bistable["Bistable.plugin"]:::interactions
            Card["Card.plugin"]:::interactions
            Dial["Dial.plugin"]:::interactions
            MasterDetail["Master-Detail.plugin"]:::interactions
            Rolodex["Rolodex.plugin"]:::interactions
            HitGrid["Hit Grid.plugin"]:::interactions
            IOSKeyboard["iOS Keyboard.plugin"]:::interactions
        end

        subgraph "Bluetooth Integration" 
            direction TB
            BTConn["Bluetooth Connection.plugin"]:::bluetooth
            click BTConn "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Bluetooth Connection.plugin"
            BTSend["Bluetooth Send.plugin"]:::bluetooth
            click BTSend "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Bluetooth Send.plugin"
            BTReceive["Bluetooth Receive.plugin"]:::bluetooth
            click BTReceive "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Bluetooth Receive.plugin"
            Disagg["Disaggregate Value.plugin"]:::bluetooth
            click Disagg "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Disaggregate Value.plugin"
        end

        subgraph "Animations" 
            direction TB
            Nod["Nod.plugin"]:::animations
            Pulse["Pulse.plugin"]:::animations
            Jiggle["Jiggle.plugin"]:::animations
            Jump["Jump.plugin"]:::animations
        end

        subgraph "Global Value" 
            direction TB
            SaveStr["Save Global String.plugin"]:::global
            click SaveStr "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Save Global String.plugin"
            RetrieveStr["Retrieve Global String.plugin"]:::global
            click RetrieveStr "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Retrieve Global String.plugin"
        end

        subgraph "Utilities" 
            direction TB
            Keyboard2["Keyboard 2.plugin"]:::utilities
            click Keyboard2 "https://github.com/ideo/avocado/blob/master/Avocado Plug-Ins/Keyboard 2.plugin"
            Delay["Delay Value.plugin"]:::utilities
            Gate["Gate.plugin"]:::utilities
            Invert["Invert.plugin"]:::utilities
            MapRange["Map to Range.plugin"]:::utilities
            Abs["Absolute Value.plugin"]:::utilities
            StrToNum["String to Number.plugin"]:::utilities
        end
    end

    %% Registration flows
    PluginDir -->|"register patches"| Origami
    Draggable -->|"register"| Origami
    BTConn -->|"register"| Origami
    BTSend -->|"register"| Origami
    BTReceive -->|"register"| Origami
    Nod -->|"register"| Origami
    SaveStr -->|"register"| Origami
    Keyboard2 -->|"register"| Origami

    %% Example Layer
    subgraph "Examples" 
        direction TB
        ExamplesDir["Examples"]:::examples
        click ExamplesDir "https://github.com/ideo/avocado/tree/master/Examples/"
        AnimExample["Animations.qtz"]:::examples
        click AnimExample "https://github.com/ideo/avocado/blob/master/Examples/Animations.qtz"
        BLEQtzes["Bluetooth Compositions (*.qtz)"]:::examples
        click BLEQtzes "https://github.com/ideo/avocado/blob/master/Examples/Bluetooth/*.qtz"
        subgraph "Arduino Sketches" 
            direction TB
            Blink["BluetoothBlink.ino"]:::examples
            click Blink "https://github.com/ideo/avocado/blob/master/Examples/Bluetooth/BluetoothBlink/BluetoothBlink.ino"
            Fade["BluetoothFade.ino"]:::examples
            click Fade "https://github.com/ideo/avocado/blob/master/Examples/Bluetooth/BluetoothFade/BluetoothFade.ino"
            SendSketch["BluetoothSend.ino"]:::examples
            click SendSketch "https://github.com/ideo/avocado/blob/master/Examples/Bluetooth/BluetoothSend/BluetoothSend.ino"
            SendRecv["BluetoothSendReceive.ino"]:::examples
            click SendRecv "https://github.com/ideo/avocado/blob/master/Examples/Bluetooth/BluetoothSendReceive/BluetoothSendReceive.ino"
        end
    end

    Origami -->|"loads examples"| ExamplesDir
    ExamplesDir --> AnimExample
    ExamplesDir --> BLEQtzes
    ExamplesDir --> Blink

    %% External Services
    CoreBT["Core Bluetooth Stack"]:::external
    BLEDevices["BLE Devices / Arduino Boards"]:::external
    BTSend -->|"BLE write"| CoreBT
    BTReceive -->|"BLE read"| CoreBT
    CoreBT -->|"radio"| BLEDevices

    %% Other Helpers
    subgraph "Other" 
        direction TB
        UninstallOrigami["Uninstall Origami.zip"]:::other
        click UninstallOrigami "https://github.com/ideo/avocado/blob/master/Other/Uninstall Origami.zip"
        UninstallAll["Uninstall Avocado & Origami.zip"]:::other
        click UninstallAll "https://github.com/ideo/avocado/blob/master/Other/Uninstall Avocado & Origami.zip"
    end

    %% Styles
    classDef host fill:#eeeeee,stroke:#333,stroke-width:1px;
    classDef manager fill:#ddf,stroke:#224,stroke-width:1px;
    classDef interactions fill:#f9f,stroke:#933,stroke-width:1px;
    classDef bluetooth fill:#ffd,stroke:#aa7,stroke-width:1px;
    classDef animations fill:#dff,stroke:#27a,stroke-width:1px;
    classDef global fill:#cfc,stroke:#2a2,stroke-width:1px;
    classDef utilities fill:#fcf,stroke:#a2a,stroke-width:1px;
    classDef examples stroke-dasharray: 5 5, fill:#fff,stroke:#666;
    classDef external fill:#fcf2d1,stroke:#bb7,stroke-width:2px,shape:cylinder;
    classDef other fill:#fdd,stroke:#d33,stroke-width:1px;
```
