# airiharuki/harmonic-studio-v2 architecture

> Architecture diagram of the GitHub repository airiharuki/harmonic-studio-v2, 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/airiharuki/harmonic-studio-v2
- Repository: https://github.com/airiharuki/harmonic-studio-v2

## Overview

VibeCoded Music Lab is a browser-based music theory and audio-workflow app. Users can calculate pitch shifts and explore key relationships, generate and play chord loops, or load a track for download, analysis, and stem separation. The React app coordinates these workflows; a server provides track and audio endpoints, while browser-side analysis and audio components handle playback and results. The README documents capabilities whose implementation was not sampled, so those branches are represented at the documented subsystem level; server internals beyond the shown security helper remain unverified.

Main entry points: [`src/App.tsx`](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/App.tsx) (Studio App), [`server.ts`](https://github.com/airiharuki/harmonic-studio-v2/blob/main/server.ts) (Audio API), [`src/lib/instantAnalysis.ts`](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/lib/instantAnalysis.ts) (Track Analysis), [`src/components/RecentTracks.tsx`](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/RecentTracks.tsx) (Recent Tracks UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_theory["Music Theory"]
  node_pitch["Pitch Calculator<br/>[PitchShifter.tsx]"]
  node_fifths["Circle of Fifths<br/>[CircleOfFifths.tsx]"]
end

subgraph group_loops["Loop Studio"]
  node_progressions["Progression Generator"]
  node_piano["Piano Roll<br/>[PianoRoll.tsx]"]
  node_lyrics["Lyrics Display<br/>[lyrics.txt]"]
end

subgraph group_analyzer["Track Analyzer"]
  node_analyzer["Track Analysis<br/>[instantAnalysis.ts]"]
  node_stem["Stem Separation<br/>[server.ts]"]
end

subgraph group_audio["Audio Playback"]
  node_waveform["Waveform Player<br/>[WaveformPlayer.tsx]"]
  node_mixer["Stem Mixer<br/>[StemMixer.tsx]"]
end

subgraph group_platform["App Services"]
  node_app["Studio App<br/>[App.tsx]"]
  node_server["Audio API<br/>[server.ts]"]
  node_security["Path Protection<br/>[security.ts]"]
  node_recent["Recent Tracks UI<br/>[RecentTracks.tsx]"]
  node_trackstore["Recent Track Store<br/>[recentTracks.ts]"]
end

node_user(("Musician"))
node_external(("Track Sources"))
node_essentia["Essentia.js"]
node_demucs["Separation Models"]
node_soundfont["Electric Piano SoundFont<br/>[epiano.sf2]"]

node_user -->|"uses"| node_app
node_app -->|"shows"| node_pitch
node_app -->|"shows"| node_fifths
node_app -->|"generates with"| node_progressions
node_app -->|"renders"| node_piano
node_app -->|"loads"| node_lyrics
node_app -->|"runs"| node_analyzer
node_app -->|"requests track info"| node_server
node_external -->|"provides audio"| node_server
node_server -.->|"dispatches separation"| node_stem
node_stem -->|"uses models"| node_demucs
node_stem -.->|"provides stems"| node_mixer
node_app -->|"analyzes audio"| node_essentia
node_analyzer -->|"estimates BPM and key"| node_essentia
node_app -->|"renders"| node_waveform
node_app -->|"renders"| node_mixer
node_app -->|"plays loops"| node_soundfont
node_app -->|"shows history"| node_recent
node_recent -->|"reads and updates"| node_trackstore
node_server -->|"uses safeguards"| node_security

click node_app "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/App.tsx"
click node_pitch "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/PitchShifter.tsx"
click node_fifths "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/CircleOfFifths.tsx"
click node_progressions "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/chordProgressions.ts"
click node_piano "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/PianoRoll.tsx"
click node_lyrics "https://github.com/airiharuki/harmonic-studio-v2/blob/main/public/lyrics.txt"
click node_analyzer "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/lib/instantAnalysis.ts"
click node_stem "https://github.com/airiharuki/harmonic-studio-v2/blob/main/server.ts"
click node_server "https://github.com/airiharuki/harmonic-studio-v2/blob/main/server.ts"
click node_security "https://github.com/airiharuki/harmonic-studio-v2/blob/main/server/security.ts"
click node_recent "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/RecentTracks.tsx"
click node_trackstore "https://github.com/airiharuki/harmonic-studio-v2/blob/main/lib/recentTracks.ts"
click node_waveform "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/WaveformPlayer.tsx"
click node_mixer "https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/StemMixer.tsx"
click node_soundfont "https://github.com/airiharuki/harmonic-studio-v2/blob/main/public/epiano.sf2"

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_pitch,node_fifths toneBlue
class node_progressions,node_piano,node_lyrics toneAmber
class node_analyzer,node_stem toneMint
class node_waveform,node_mixer toneRose
class node_app,node_server,node_security,node_recent,node_trackstore,node_user,node_external,node_essentia,node_demucs toneIndigo
class node_soundfont toneTeal
```

## Components

### Music Theory

- [Pitch Calculator](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/PitchShifter.tsx): `src/PitchShifter.tsx`
- [Circle of Fifths](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/CircleOfFifths.tsx): `src/CircleOfFifths.tsx`

### Loop Studio

- [Progression Generator](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/chordProgressions.ts): `src/chordProgressions.ts`
- [Piano Roll](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/PianoRoll.tsx): `src/components/PianoRoll.tsx`
- [Lyrics Display](https://github.com/airiharuki/harmonic-studio-v2/blob/main/public/lyrics.txt): `public/lyrics.txt`

### Track Analyzer

- [Track Analysis](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/lib/instantAnalysis.ts): `src/lib/instantAnalysis.ts`
- [Stem Separation](https://github.com/airiharuki/harmonic-studio-v2/blob/main/server.ts): `server.ts`

### Audio Playback

- [Waveform Player](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/WaveformPlayer.tsx): `src/components/WaveformPlayer.tsx`
- [Stem Mixer](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/StemMixer.tsx): `src/components/StemMixer.tsx`

### App Services

- [Studio App](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/App.tsx): `src/App.tsx`
- [Audio API](https://github.com/airiharuki/harmonic-studio-v2/blob/main/server.ts): `server.ts`
- [Path Protection](https://github.com/airiharuki/harmonic-studio-v2/blob/main/server/security.ts): `server/security.ts`
- [Recent Tracks UI](https://github.com/airiharuki/harmonic-studio-v2/blob/main/src/components/RecentTracks.tsx): `src/components/RecentTracks.tsx`
- [Recent Track Store](https://github.com/airiharuki/harmonic-studio-v2/blob/main/lib/recentTracks.ts): `lib/recentTracks.ts`

### Other components

- **Musician**
- **Track Sources**
- **Essentia.js**
- **Separation Models**
- [Electric Piano SoundFont](https://github.com/airiharuki/harmonic-studio-v2/blob/main/public/epiano.sf2): `public/epiano.sf2`

## Connections

- Musician → Studio App: uses (evidence: `README.md`)
- Studio App → Pitch Calculator: shows (evidence: `src/App.tsx`)
- Studio App → Circle of Fifths: shows (evidence: `src/App.tsx`)
- Studio App → Progression Generator: generates with (evidence: `README.md`)
- Studio App → Piano Roll: renders (evidence: `src/App.tsx`)
- Studio App → Lyrics Display: loads (evidence: `README.md`)
- Studio App → Track Analysis: runs (evidence: `src/App.tsx`)
- Studio App → Audio API: requests track info (evidence: `src/App.tsx`)
- Track Sources → Audio API: provides audio (evidence: `README.md`)
- Audio API → Stem Separation: dispatches separation (evidence: `server.ts`)
- Stem Separation → Separation Models: uses models (evidence: `README.md`)
- Stem Separation → Stem Mixer: provides stems
- Studio App → Essentia.js: analyzes audio (evidence: `README.md`)
- Track Analysis → Essentia.js: estimates BPM and key (evidence: `src/lib/instantAnalysis.ts`)
- Studio App → Waveform Player: renders (evidence: `src/App.tsx`)
- Studio App → Stem Mixer: renders (evidence: `src/App.tsx`)
- Studio App → Electric Piano SoundFont: plays loops (evidence: `src/App.tsx`)
- Studio App → Recent Tracks UI: shows history (evidence: `src/App.tsx`)
- Recent Tracks UI → Recent Track Store: reads and updates (evidence: `src/components/RecentTracks.tsx`)
- Audio API → Path Protection: uses safeguards (evidence: `server.ts`)
