# vyk2rr/projectresonance architecture

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

- Interactive diagram: https://gitdiagram.com/vyk2rr/projectresonance
- Repository: https://github.com/vyk2rr/projectresonance

## Overview

This is a learning-focused browser music app for exploring piano sounds, chords, melodies, and ukulele chords. The main evidenced entry flow is the home route rendering a welcome page with playable piano variants; the shared piano component handles key playback and sequence playback. Separate pages provide ukulele strumming and fretboard diagrams. Chord palettes support chord selection and inversion, while sequence creation and AI-assisted jamming are distinct capabilities. The graph follows imports and calls shown in the supplied excerpts or source index; unsampled route wiring and feature internals are not inferred.

Main entry points: [`app/PianoBase/PianoBase.tsx`](https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.tsx) (Piano engine), [`app/ChordPalette/ChordPalette.tsx`](https://github.com/vyk2rr/projectresonance/blob/main/app/ChordPalette/ChordPalette.tsx) (Chord palette), [`app/pianos`](https://github.com/vyk2rr/projectresonance/tree/main/app/pianos) (Piano sound variants), [`app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx`](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx) (Sequence creator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Pages and entry"]
  node_home["Home route<br/>[Home.tsx]"]
  node_welcome["Piano welcome<br/>[welcome.tsx]"]
  node_ukulelepage["Ukulele page<br/>[UkulelePage.tsx]"]
  node_chordspage["Ukulele chords page"]
end

subgraph group_piano["Piano playback"]
  node_pianobase["Piano engine<br/>[PianoBase.tsx]"]
  node_pianotypes["Music types<br/>[PianoBase.types.ts]"]
  node_pianoutils["Piano utilities<br/>[PianoBase.utils.ts]"]
  node_observer["Piano observer<br/>[PianoObserver.ts]"]
  node_dispatcher["Sequence dispatcher<br/>[ChordDispatcher.ts]"]
  node_soundvariants["Piano sound variants"]
  node_minidashboard["Mini dashboard"]
end

subgraph group_composition["Chord and composition tools"]
  node_palette["Chord palette<br/>[ChordPalette.tsx]"]
  node_chordutils["Chord generation"]
  node_sequence["Sequence creator"]
  node_melody["Melody player<br/>[PianoMelody.tsx]"]
  node_cheatsheet["Chord cheatsheet"]
  node_zap["Piano zap<br/>[PianoZap.tsx]"]
end

subgraph group_ukulele["Ukulele tools"]
  node_ukulele["Ukulele strumming<br/>[ukulele.tsx]"]
  node_ukulelepiano["Ukulele piano<br/>[PianoUkulele.tsx]"]
  node_fretboard["Ukulele fretboard"]
  node_chordlist["Ukulele chord list"]
end

subgraph group_integration["AI integration"]
  node_ai_jam["AI jamming"]
  node_ai_service["AI melody service"]
  node_ai_api{{"AI generation API"}}
end

node_user(("Visitor"))

node_user -->|"opens"| node_home
node_home -->|"renders"| node_welcome
node_welcome -->|"renders"| node_pianobase
node_welcome -->|"renders"| node_soundvariants
node_pianobase -->|"uses"| node_pianoutils
node_pianobase -->|"uses types"| node_pianotypes
node_pianobase -->|"notifies"| node_observer
node_pianobase -->|"uses events"| node_dispatcher
node_soundvariants -->|"wraps"| node_pianobase
node_minidashboard -->|"uses"| node_pianobase
node_minidashboard -->|"subscribes"| node_observer
node_palette -->|"generates chords"| node_chordutils
node_palette -->|"uses types"| node_pianotypes
node_sequence -->|"uses"| node_pianobase
node_sequence -->|"renders"| node_palette
node_sequence -->|"uses variants"| node_soundvariants
node_melody -->|"uses"| node_pianobase
node_melody -->|"uses events"| node_dispatcher
node_cheatsheet -->|"uses"| node_pianobase
node_cheatsheet -->|"renders"| node_palette
node_zap -->|"uses variant"| node_soundvariants
node_ai_jam -->|"uses"| node_pianobase
node_ai_jam -->|"uses events"| node_dispatcher
node_ai_jam -->|"requests melody"| node_ai_service
node_ai_service -->|"posts prompt"| node_ai_api
node_user -->|"opens"| node_ukulelepage
node_ukulelepage -->|"renders"| node_ukulele
node_ukulele -->|"renders"| node_ukulelepiano
node_ukulele -->|"renders"| node_fretboard
node_user -->|"opens"| node_chordspage
node_chordspage -->|"renders"| node_chordlist
node_chordlist -->|"renders"| node_fretboard

click node_home "https://github.com/vyk2rr/projectresonance/blob/main/app/routes/Home.tsx"
click node_welcome "https://github.com/vyk2rr/projectresonance/blob/main/app/welcome/welcome.tsx"
click node_ukulelepage "https://github.com/vyk2rr/projectresonance/blob/main/app/routes/UkulelePage.tsx"
click node_chordspage "https://github.com/vyk2rr/projectresonance/blob/main/app/routes/UkuleleChordsHomePage.tsx"
click node_pianobase "https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.tsx"
click node_pianotypes "https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.types.ts"
click node_pianoutils "https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.utils.ts"
click node_observer "https://github.com/vyk2rr/projectresonance/blob/main/app/PianoObserver/PianoObserver.ts"
click node_dispatcher "https://github.com/vyk2rr/projectresonance/blob/main/app/ChordDispatcher/ChordDispatcher.ts"
click node_soundvariants "https://github.com/vyk2rr/projectresonance/tree/main/app/pianos"
click node_minidashboard "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoMiniDashboard/PianoMiniDashboard.tsx"
click node_palette "https://github.com/vyk2rr/projectresonance/blob/main/app/ChordPalette/ChordPalette.tsx"
click node_chordutils "https://github.com/vyk2rr/projectresonance/blob/main/app/ChordPalette/ChordPalette.utils.tsx"
click node_sequence "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx"
click node_melody "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoMelody/PianoMelody.tsx"
click node_cheatsheet "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoWithChordsCheatsheet/PianoWithChordsCheatsheet.tsx"
click node_zap "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoZap/PianoZap.tsx"
click node_ai_jam "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.tsx"
click node_ai_service "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.ai.service.ts"
click node_ukulele "https://github.com/vyk2rr/projectresonance/blob/main/app/ukulele/ukulele.tsx"
click node_ukulelepiano "https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoUkulele.tsx"
click node_fretboard "https://github.com/vyk2rr/projectresonance/blob/main/app/UkuleleFretboard/UkuleleFretboard.tsx"
click node_chordlist "https://github.com/vyk2rr/projectresonance/blob/main/app/UkuleleChordsList/UkuleleChordsList.tsx"

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_home,node_welcome,node_ukulelepage,node_chordspage toneBlue
class node_pianobase,node_pianotypes,node_pianoutils,node_observer,node_dispatcher,node_soundvariants,node_minidashboard toneAmber
class node_palette,node_chordutils,node_sequence,node_melody,node_cheatsheet,node_zap toneMint
class node_ukulele,node_ukulelepiano,node_fretboard,node_chordlist toneRose
class node_ai_jam,node_ai_service,node_ai_api,node_user toneIndigo
```

## Components

### Pages and entry

- [Home route](https://github.com/vyk2rr/projectresonance/blob/main/app/routes/Home.tsx): `app/routes/Home.tsx`
- [Piano welcome](https://github.com/vyk2rr/projectresonance/blob/main/app/welcome/welcome.tsx): `app/welcome/welcome.tsx`
- [Ukulele page](https://github.com/vyk2rr/projectresonance/blob/main/app/routes/UkulelePage.tsx): `app/routes/UkulelePage.tsx`
- [Ukulele chords page](https://github.com/vyk2rr/projectresonance/blob/main/app/routes/UkuleleChordsHomePage.tsx): `app/routes/UkuleleChordsHomePage.tsx`

### Piano playback

- [Piano engine](https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.tsx): `app/PianoBase/PianoBase.tsx`
- [Music types](https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.types.ts): `app/PianoBase/PianoBase.types.ts`
- [Piano utilities](https://github.com/vyk2rr/projectresonance/blob/main/app/PianoBase/PianoBase.utils.ts): `app/PianoBase/PianoBase.utils.ts`
- [Piano observer](https://github.com/vyk2rr/projectresonance/blob/main/app/PianoObserver/PianoObserver.ts): `app/PianoObserver/PianoObserver.ts`
- [Sequence dispatcher](https://github.com/vyk2rr/projectresonance/blob/main/app/ChordDispatcher/ChordDispatcher.ts): `app/ChordDispatcher/ChordDispatcher.ts`
- [Piano sound variants](https://github.com/vyk2rr/projectresonance/tree/main/app/pianos): `app/pianos`
- [Mini dashboard](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoMiniDashboard/PianoMiniDashboard.tsx): `app/pianos/PianoMiniDashboard/PianoMiniDashboard.tsx`

### Chord and composition tools

- [Chord palette](https://github.com/vyk2rr/projectresonance/blob/main/app/ChordPalette/ChordPalette.tsx): `app/ChordPalette/ChordPalette.tsx`
- [Chord generation](https://github.com/vyk2rr/projectresonance/blob/main/app/ChordPalette/ChordPalette.utils.tsx): `app/ChordPalette/ChordPalette.utils.tsx`
- [Sequence creator](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx): `app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx`
- [Melody player](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoMelody/PianoMelody.tsx): `app/pianos/PianoMelody/PianoMelody.tsx`
- [Chord cheatsheet](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoWithChordsCheatsheet/PianoWithChordsCheatsheet.tsx): `app/pianos/PianoWithChordsCheatsheet/PianoWithChordsCheatsheet.tsx`
- [Piano zap](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoZap/PianoZap.tsx): `app/pianos/PianoZap/PianoZap.tsx`

### Ukulele tools

- [Ukulele strumming](https://github.com/vyk2rr/projectresonance/blob/main/app/ukulele/ukulele.tsx): `app/ukulele/ukulele.tsx`
- [Ukulele piano](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoUkulele.tsx): `app/pianos/PianoUkulele.tsx`
- [Ukulele fretboard](https://github.com/vyk2rr/projectresonance/blob/main/app/UkuleleFretboard/UkuleleFretboard.tsx): `app/UkuleleFretboard/UkuleleFretboard.tsx`
- [Ukulele chord list](https://github.com/vyk2rr/projectresonance/blob/main/app/UkuleleChordsList/UkuleleChordsList.tsx): `app/UkuleleChordsList/UkuleleChordsList.tsx`

### AI integration

- [AI jamming](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.tsx): `app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.tsx`
- [AI melody service](https://github.com/vyk2rr/projectresonance/blob/main/app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.ai.service.ts): `app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.ai.service.ts`
- **AI generation API**

### Other components

- **Visitor**

## Connections

- Visitor → Home route: opens (evidence: `app/routes/Home.tsx`)
- Home route → Piano welcome: renders (evidence: `app/routes/Home.tsx`)
- Piano welcome → Piano engine: renders (evidence: `app/welcome/welcome.tsx`)
- Piano welcome → Piano sound variants: renders (evidence: `app/welcome/welcome.tsx`)
- Piano engine → Piano utilities: uses (evidence: `app/PianoBase/PianoBase.tsx`)
- Piano engine → Music types: uses types (evidence: `app/PianoBase/PianoBase.tsx`)
- Piano engine → Piano observer: notifies (evidence: `app/PianoBase/PianoBase.tsx`)
- Piano engine → Sequence dispatcher: uses events (evidence: `app/PianoBase/PianoBase.tsx`)
- Piano sound variants → Piano engine: wraps (evidence: `app/pianos/PianoDryLeaf.tsx`)
- Mini dashboard → Piano engine: uses (evidence: `app/pianos/PianoMiniDashboard/PianoMiniDashboard.tsx`)
- Mini dashboard → Piano observer: subscribes (evidence: `app/pianos/PianoMiniDashboard/PianoMiniDashboard.tsx`)
- Chord palette → Chord generation: generates chords (evidence: `app/ChordPalette/ChordPalette.tsx`)
- Chord palette → Music types: uses types (evidence: `app/ChordPalette/ChordPalette.tsx`)
- Sequence creator → Piano engine: uses (evidence: `app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx`)
- Sequence creator → Chord palette: renders (evidence: `app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx`)
- Sequence creator → Piano sound variants: uses variants (evidence: `app/pianos/PianoSequenceCreator/PianoSequenceCreator.tsx`)
- Melody player → Piano engine: uses (evidence: `app/pianos/PianoMelody/PianoMelody.tsx`)
- Melody player → Sequence dispatcher: uses events (evidence: `app/pianos/PianoMelody/PianoMelody.tsx`)
- Chord cheatsheet → Piano engine: uses (evidence: `app/pianos/PianoWithChordsCheatsheet/PianoWithChordsCheatsheet.tsx`)
- Chord cheatsheet → Chord palette: renders (evidence: `app/pianos/PianoWithChordsCheatsheet/PianoWithChordsCheatsheet.tsx`)
- Piano zap → Piano sound variants: uses variant (evidence: `app/pianos/PianoZap/PianoZap.tsx`)
- AI jamming → Piano engine: uses (evidence: `app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.tsx`)
- AI jamming → Sequence dispatcher: uses events (evidence: `app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.tsx`)
- AI jamming → AI melody service: requests melody (evidence: `app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.tsx`)
- AI melody service → AI generation API: posts prompt (evidence: `app/pianos/PianoJammingWithTheAI/PianoJammingWithTheAI.ai.service.ts`)
- Visitor → Ukulele page: opens (evidence: `app/routes/UkulelePage.tsx`)
- Ukulele page → Ukulele strumming: renders (evidence: `app/routes/UkulelePage.tsx`)
- Ukulele strumming → Ukulele piano: renders (evidence: `app/ukulele/ukulele.tsx`)
- Ukulele strumming → Ukulele fretboard: renders (evidence: `app/ukulele/ukulele.tsx`)
- Visitor → Ukulele chords page: opens (evidence: `app/routes/UkuleleChordsHomePage.tsx`)
- Ukulele chords page → Ukulele chord list: renders (evidence: `app/routes/UkuleleChordsHomePage.tsx`)
- Ukulele chord list → Ukulele fretboard: renders (evidence: `app/UkuleleChordsList/UkuleleChordsList.tsx`)