# cknishan/muvesic architecture

> Architecture diagram of the GitHub repository cknishan/muvesic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cknishan/muvesic
- Repository: https://github.com/cknishan/muvesic

## Overview

Muvesic is a browser-based, on-device musical instrument. The main workflow starts a camera or camera-free input session, maps fingertip or pointer movement to musical notes and dynamics, and plays them through a browser synthesizer. Settings, rendering, lifecycle controls, recovery messages, and optional WebMCP tools round out the product. The README and tree establish these capabilities; sampled source did not include the application modules, so uncertain internal call links are omitted.

Main entry points: [`dist/tracking/hand-tracker.js`](https://github.com/cknishan/muvesic/blob/main/dist/tracking/hand-tracker.js) (Hand tracker), [`dist/music/motion-mapper.js`](https://github.com/cknishan/muvesic/blob/main/dist/music/motion-mapper.js) (Motion mapping), [`dist/app/session.js`](https://github.com/cknishan/muvesic/blob/main/dist/app/session.js) (Session lifecycle), [`dist/app/controls.js`](https://github.com/cknishan/muvesic/blob/main/dist/app/controls.js) (Control bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Session and controls"]
  node_entry["App composition<br/>[app.js]"]
  node_session["Session lifecycle<br/>[session.js]"]
  node_controls["Control bindings<br/>[controls.js]"]
  node_settings["Validated settings<br/>[settings.js]"]
  node_webmcp["WebMCP tools<br/>[webmcp.js]"]
end

subgraph group_input["Input and tracking"]
  node_pointer["Pointer and keys"]
  node_tracker["Hand tracker<br/>[hand-tracker.js]"]
  node_trackingconfig["Tracking config<br/>[config.js]"]
  node_trackingerrors["Recovery messages<br/>[errors.js]"]
end

subgraph group_music["Musical mapping"]
  node_mapper["Motion mapping<br/>[motion-mapper.js]"]
  node_notes["Notes and tuning<br/>[notes.js]"]
  node_scales["Scales<br/>[scales.js]"]
end

subgraph group_presentation["Audio and presentation"]
  node_audio["Synthesizer<br/>[synthesizer.js]"]
  node_voice["Instrument voices<br/>[voice.js]"]
  node_instrument["Instrument view<br/>[instrument-view.js]"]
  node_stage["Stage renderer<br/>[stage-renderer.js]"]
end

node_player(("Player"))
node_mediapipe["MediaPipe runtime and model"]
node_browser["Browser camera and audio"]

node_player -->|"opens instrument"| node_entry
node_entry -->|"composes"| node_session
node_player -->|"uses controls"| node_controls
node_controls -->|"controls session"| node_session
node_controls -->|"changes settings"| node_settings
node_session -->|"starts and stops"| node_tracker
node_session -->|"manages camera and audio"| node_browser
node_tracker -->|"runs inference"| node_mediapipe
node_mediapipe -->|"returns landmarks"| node_tracker
node_tracker -->|"uses configuration"| node_trackingconfig
node_tracker -->|"reports recovery"| node_trackingerrors
node_tracker -->|"supplies fingertip motion"| node_mapper
node_player -->|"uses mouse or keys"| node_pointer
node_pointer -->|"supplies pointer motion"| node_mapper
node_mapper -->|"selects pitches"| node_notes
node_mapper -->|"maps to scale"| node_scales
node_mapper -->|"sends note and dynamics"| node_audio
node_audio -->|"plays instrument voice"| node_voice
node_audio -->|"uses audio context"| node_browser
node_player -->|"views instrument"| node_instrument
node_instrument -->|"renders stage"| node_stage
node_player -.->|"optional tool requests"| node_webmcp
node_webmcp -.->|"reads or configures"| node_settings
node_webmcp -.->|"stops session"| node_session

click node_entry "https://github.com/cknishan/muvesic/blob/main/dist/app.js"
click node_session "https://github.com/cknishan/muvesic/blob/main/dist/app/session.js"
click node_controls "https://github.com/cknishan/muvesic/blob/main/dist/app/controls.js"
click node_settings "https://github.com/cknishan/muvesic/blob/main/dist/app/settings.js"
click node_pointer "https://github.com/cknishan/muvesic/blob/main/dist/input/pointer-keyboard.js"
click node_tracker "https://github.com/cknishan/muvesic/blob/main/dist/tracking/hand-tracker.js"
click node_trackingconfig "https://github.com/cknishan/muvesic/blob/main/dist/tracking/config.js"
click node_trackingerrors "https://github.com/cknishan/muvesic/blob/main/dist/tracking/errors.js"
click node_mapper "https://github.com/cknishan/muvesic/blob/main/dist/music/motion-mapper.js"
click node_notes "https://github.com/cknishan/muvesic/blob/main/dist/music/notes.js"
click node_scales "https://github.com/cknishan/muvesic/blob/main/dist/music/scales.js"
click node_audio "https://github.com/cknishan/muvesic/blob/main/dist/audio/synthesizer.js"
click node_voice "https://github.com/cknishan/muvesic/blob/main/dist/audio/voice.js"
click node_instrument "https://github.com/cknishan/muvesic/blob/main/dist/ui/instrument-view.js"
click node_stage "https://github.com/cknishan/muvesic/blob/main/dist/ui/stage-renderer.js"
click node_webmcp "https://github.com/cknishan/muvesic/blob/main/dist/integrations/webmcp.js"

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_entry,node_session,node_controls,node_settings,node_webmcp,node_browser toneBlue
class node_pointer,node_tracker,node_trackingconfig,node_trackingerrors toneAmber
class node_mapper,node_notes,node_scales,node_mediapipe toneMint
class node_audio,node_voice,node_instrument,node_stage toneRose
class node_player toneIndigo
```

## Components

### Session and controls

- [App composition](https://github.com/cknishan/muvesic/blob/main/dist/app.js): `dist/app.js`
- [Session lifecycle](https://github.com/cknishan/muvesic/blob/main/dist/app/session.js): `dist/app/session.js`
- [Control bindings](https://github.com/cknishan/muvesic/blob/main/dist/app/controls.js): `dist/app/controls.js`
- [Validated settings](https://github.com/cknishan/muvesic/blob/main/dist/app/settings.js): `dist/app/settings.js`
- [WebMCP tools](https://github.com/cknishan/muvesic/blob/main/dist/integrations/webmcp.js): `dist/integrations/webmcp.js`

### Input and tracking

- [Pointer and keys](https://github.com/cknishan/muvesic/blob/main/dist/input/pointer-keyboard.js): `dist/input/pointer-keyboard.js`
- [Hand tracker](https://github.com/cknishan/muvesic/blob/main/dist/tracking/hand-tracker.js): `dist/tracking/hand-tracker.js`
- [Tracking config](https://github.com/cknishan/muvesic/blob/main/dist/tracking/config.js): `dist/tracking/config.js`
- [Recovery messages](https://github.com/cknishan/muvesic/blob/main/dist/tracking/errors.js): `dist/tracking/errors.js`

### Musical mapping

- [Motion mapping](https://github.com/cknishan/muvesic/blob/main/dist/music/motion-mapper.js): `dist/music/motion-mapper.js`
- [Notes and tuning](https://github.com/cknishan/muvesic/blob/main/dist/music/notes.js): `dist/music/notes.js`
- [Scales](https://github.com/cknishan/muvesic/blob/main/dist/music/scales.js): `dist/music/scales.js`

### Audio and presentation

- [Synthesizer](https://github.com/cknishan/muvesic/blob/main/dist/audio/synthesizer.js): `dist/audio/synthesizer.js`
- [Instrument voices](https://github.com/cknishan/muvesic/blob/main/dist/audio/voice.js): `dist/audio/voice.js`
- [Instrument view](https://github.com/cknishan/muvesic/blob/main/dist/ui/instrument-view.js): `dist/ui/instrument-view.js`
- [Stage renderer](https://github.com/cknishan/muvesic/blob/main/dist/ui/stage-renderer.js): `dist/ui/stage-renderer.js`

### Other components

- **Player**
- **MediaPipe runtime and model**
- **Browser camera and audio**

## Connections

- Player → App composition: opens instrument
- App composition → Session lifecycle: composes
- Player → Control bindings: uses controls
- Control bindings → Session lifecycle: controls session
- Control bindings → Validated settings: changes settings
- Session lifecycle → Hand tracker: starts and stops
- Session lifecycle → Browser camera and audio: manages camera and audio
- Hand tracker → MediaPipe runtime and model: runs inference
- MediaPipe runtime and model → Hand tracker: returns landmarks
- Hand tracker → Tracking config: uses configuration
- Hand tracker → Recovery messages: reports recovery
- Hand tracker → Motion mapping: supplies fingertip motion
- Player → Pointer and keys: uses mouse or keys
- Pointer and keys → Motion mapping: supplies pointer motion
- Motion mapping → Notes and tuning: selects pitches
- Motion mapping → Scales: maps to scale
- Motion mapping → Synthesizer: sends note and dynamics
- Synthesizer → Instrument voices: plays instrument voice
- Synthesizer → Browser camera and audio: uses audio context
- Player → Instrument view: views instrument
- Instrument view → Stage renderer: renders stage
- Player → WebMCP tools: optional tool requests
- WebMCP tools → Validated settings: reads or configures
- WebMCP tools → Session lifecycle: stops session