# promethiuml/tonalpalette architecture

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

- Interactive diagram: https://gitdiagram.com/promethiuml/tonalpalette
- Repository: https://github.com/promethiuml/tonalpalette

## Overview

##### Project type and purpose
- This is a front-end, single‐page web application (no backend services) that visualizes incoming MIDI data in real time.
- It uses P5.js for rendering and WebMIDI.js (and the browser’s WebMIDI API) for MIDI input.

##### File structure
- Top level:
- index.html, public/style.css – the host page and global styles
- src/… – TypeScript source modules:
– midiMonitor.ts – wraps WebMIDI.js and listens for MIDI events
– tonalEstimator.ts – converts raw MIDI into tonal/harmonic information
– particle.ts, sceneObject.ts – data structures for visual objects
– scene.ts – overall scene manager (updates & draws objects)
– constants.ts, types.ts – shared definitions
- libraries/webmidi.js – third-party wrapper for WebMIDI API
- vite.config.js, tsconfig.json – build & development configuration
- dist/… – production bundle output

##### Extract insights from the README
- Real-time MIDI visualizer for harmony exploration
- Keyboard shortcuts: toggle UI (`H`), clear (`C`)
- Demo URL provided

##### Main components & their relationships
a. Browser Environment
– Hosts the application, loads index.html, runs JavaScript/Vite dev server in development.
b. External Libraries
– WebMIDI.js: abstracts the browser’s WebMIDI API.
– P5.js: rendering engine for 2D canvas animations.
c. MIDI Input Layer (midiMonitor.ts)
– Subscribes to MIDI device messages via WebMIDI.js.
– Emits events to tonalEstimator.
d. Processing Layer
– tonalEstimator.ts: transforms MIDI note on/off into tonal/harmony data (pitch class, chord, scale).
e. Visualization Layer
– scene.ts: orchestrates object lifecycles (spawn, update, remove).
– particle.ts & sceneObject.ts: implement individual visual entities.
f. UI & Controls
– DOM overlay/style.css: show/hide settings panel, clear command via keystrokes.

##### Architectural patterns & design principles
- Modular separation: Input → Processing → Rendering
- Event-driven data flow: MIDI events trigger processing and visualization updates
- Single responsibility modules: each .ts file handles one concern
- Build pipeline (Vite + ESBuild): TS → ESNext bundle → dist

– Browser / Host Page
– WebMIDI.js (External Library)
– midiMonitor
– tonalEstimator
– palette
– scene Manager
– Particle / SceneObject modules
– P5.js Renderer
– UI Controls (settings panel)
– index.html → loads → main.ts / sketch.ts
– midiMonitor → emits → tonalEstimator → passes tonal data → palette
– scene Manager → uses → P5.js API → draws → canvas
– Keyboard input → UI Controls → toggles → scene or settings overlay
– Blue rectangles: source modules (TS files)
– Green rectangle: External libraries (WebMIDI.js, P5.js)
– Orange rectangles: UI/Controls
d. Annotations:
– Group all src/… modules in a “Frontend Application” container
– Indicate build step: Vite → bundle → dist/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser and UI
    subgraph "Browser Environment"
        B1["Browser / Host Page"]:::external
        B2["Global Styles (UI Controls)"]:::ui
    end

    %% External libraries
    subgraph "External Libraries"
        E1["WebMIDI.js"]:::external
        E2["P5.js Renderer"]:::external
    end

    %% Frontend application modules
    subgraph "Frontend Application"
        subgraph "Input Layer"
            MMonitor["midiMonitor.ts"]:::code
        end
        subgraph "Processing Layer"
            TE["tonalEstimator.ts"]:::code
            Palette["palette.ts"]:::code
        end
        subgraph "Visualization Layer"
            SceneMgr["scene.ts"]:::code
            Part["particle.ts"]:::code
            SceneObj["sceneObject.ts"]:::code
            Sketch["sketch.ts"]:::code
        end
        Main["main.ts"]:::code
        Const["constants.ts"]:::code
        Types["types.ts"]:::code
    end

    %% Build and output
    subgraph "Build Pipeline"
        Vite["vite.config.js"]:::pipeline
        TSCfg["tsconfig.json"]:::pipeline
        Dist["dist/TonalPalette"]:::pipeline
    end

    %% Data and control flows
    B1 -->|"loads"| Main
    Main -->|"initializes"| Sketch
    Main -->|"wires events"| MMonitor
    B1 -->|"keyboard shortcuts"| B2
    B2 -->|"toggles/clears"| SceneMgr

    E1 -->|"raw MIDI"| MMonitor
    MMonitor -.events.-> TE
    TE -->|"tonal info"| Palette
    Palette -->|"color values"| SceneMgr
    SceneMgr -->|"spawn/update/remove"| Part
    SceneMgr -->|"spawn/update/remove"| SceneObj
    Sketch -->|"draw loop"| SceneMgr
    SceneMgr -->|"draw commands"| E2

    Vite -->|"bundles"| Dist
    TSCfg --> Vite

    %% Click events
    click B1 "https://github.com/promethiuml/tonalpalette/blob/main/index.html"
    click B2 "https://github.com/promethiuml/tonalpalette/blob/main/public/style.css"
    click E1 "https://github.com/promethiuml/tonalpalette/blob/main/libraries/webmidi.js"
    click MMonitor "https://github.com/promethiuml/tonalpalette/blob/main/src/midiMonitor.ts"
    click TE "https://github.com/promethiuml/tonalpalette/blob/main/src/tonalEstimator.ts"
    click Palette "https://github.com/promethiuml/tonalpalette/blob/main/src/palette.ts"
    click SceneMgr "https://github.com/promethiuml/tonalpalette/blob/main/src/scene.ts"
    click Part "https://github.com/promethiuml/tonalpalette/blob/main/src/particle.ts"
    click SceneObj "https://github.com/promethiuml/tonalpalette/blob/main/src/sceneObject.ts"
    click Sketch "https://github.com/promethiuml/tonalpalette/blob/main/src/sketch.ts"
    click Main "https://github.com/promethiuml/tonalpalette/blob/main/src/main.ts"
    click Const "https://github.com/promethiuml/tonalpalette/blob/main/src/constants.ts"
    click Types "https://github.com/promethiuml/tonalpalette/blob/main/src/types.ts"
    click Vite "https://github.com/promethiuml/tonalpalette/blob/main/vite.config.js"
    click TSCfg "https://github.com/promethiuml/tonalpalette/blob/main/tsconfig.json"
    click Dist "https://github.com/promethiuml/tonalpalette/tree/main/dist/TonalPalette"

    %% Styles
    classDef code fill:#add8e6,stroke:#000;
    classDef external fill:#90ee90,stroke:#000;
    classDef ui fill:#ffa500,stroke:#000;
    classDef pipeline fill:#f5f5f5,stroke:#000;
```
