# lhuthng/synrecordia architecture

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

- Interactive diagram: https://gitdiagram.com/lhuthng/synrecordia
- Repository: https://github.com/lhuthng/synrecordia

## Overview

1. **Overall shape**
   - This is a **client-side React application** built with **Vite**. There is no custom backend in the repo; everything runs in the browser and the app is deployed as static assets.

2. **Primary user-facing subsystems**
   - The app has two main experiences: a **song player** and an **interactive visualizer**. Users can choose songs, control playback, adjust tempo, loop, and switch instrument settings while seeing synchronized note/fingering graphics.

3. **Application shell**
   - `src/main.jsx` mounts the app into `index.html`.
   - `src/App.jsx` is the top-level composition point that ties together the header, directory/navigation, player, visualizer, details panels, and instrument controls.

4. **Playback and timing**
   - `src/components/Player.jsx` is the core orchestration layer for playback.
   - It uses **Tone.js** for audio scheduling and transport-style timing.
   - This component drives play/pause/restart, BPM changes, scrubbing, repeat/loop behavior, and per-track selection.

5. **Visualization pipeline**
   - `src/components/Visualizer.jsx` renders the note timeline and active-note effects.
   - It is backed by **PIXI.js** via `src/hooks/usePixiVisualizer.js`, which likely handles the imperative canvas layer and animation updates.
   - The visualizer consumes playback state and song note data to keep the graphics aligned with audio.

6. **Instrument abstraction layer**
   - `src/components/instruments/` contains the instrument-specific UI and logic.
   - `InstrumentManager.jsx` coordinates instrument instances, while `Piano.jsx` and `Recorder.jsx` represent the supported instruments.
   - `Instrument.jsx` appears to be the shared abstraction for instrument controls such as volume and variant selection.

7. **Sample loading model**
   - Instrument audio is shipped as **static public assets** under `public/samples/<instrument>/<version>/`.
   - Each version directory contains an `index.json` manifest plus the MP3 files for that sample set.
   - The `src/libs/packedSampler/` layer is the bridge between the UI and these manifest-driven sample packs, with instrument-specific loaders in `piano.js` and `recorder.js`.

8. **Song/content model**
   - Musical content is stored as JSON in `public/songs/`.
   - `public/songs/index.json` likely acts as the catalog, while each song file encodes tracks, notes, tempo, and metadata used by the player and visualizer.
   - The UI reads these files directly over HTTP from the static host.

9. **Shared utilities and UI helpers**
   - `src/components/utils/` and `src/libs/utils.js` contain reusable logic for things like geometry, colors, fingering, and constants.
   - `src/assets/references/fingering-chart.json` provides domain reference data used to render or map recorder fingering visuals.

10. **Content and asset boundaries**
   - `public/` is the hard boundary for anything that must be served directly by the host: samples, songs, redirects, robots, and the web manifest.
   - `public/_redirects` suggests Netlify-style static hosting behavior.
   - The app itself does not appear to depend on remote APIs at runtime.

11. **Tooling and build pipeline**
   - `vite.config.js` defines the frontend build/development pipeline.
   - `eslint.config.js` is the main code-quality tool.
   - `package.json` and `package-lock.json` define the browser runtime dependencies, notably **React**, **Tone.js**, and **PIXI.js**.

12. **Repository scripts and asset preparation**
   - The `scripts/` folder contains one-off content-processing tools rather than runtime code.
   - These scripts convert or reshape audio and song assets, generate sitemaps, trim/prepare recorder samples, shift octave data, and organize sample-pack structure.
   - They support the static asset pipeline that the browser app consumes.

13. **Planned extension points**
   - The README calls out future support for **MIDI import/conversion** and **live play mode** via Web MIDI or microphone pitch detection.
   - Architecturally, these would add a new input-ingestion layer feeding the same song/track model used by playback and visualization.

14. **Diagram-friendly summary**
   - Think of the system as: **static song/sample content** in `public/` → **packed sampler loaders** → **Tone.js playback** → **PIXI.js visualizer** → **React UI controls**.
   - The only major runtime boundary is the browser; all media, configuration, and song data are fetched from static files served by the host.

Main entry points: [`src/App.jsx`](https://github.com/lhuthng/synrecordia/blob/main/src/App.jsx) (App), [`src/components/instruments/InstrumentManager.jsx`](https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/InstrumentManager.jsx) (InstrumentMgr), [`src/components/Player.jsx`](https://github.com/lhuthng/synrecordia/blob/main/src/components/Player.jsx) (Player), [`src/components/Visualizer.jsx`](https://github.com/lhuthng/synrecordia/blob/main/src/components/Visualizer.jsx) (Visualizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["React app"]
  node_src_main["main<br/>entry<br/>[main.jsx]"]
  node_src_app["App<br/>composition<br/>[App.jsx]"]
  node_src_header["Header<br/>ui shell<br/>[Header.jsx]"]
  node_src_directory["Directory<br/>song browser<br/>[Directory.jsx]"]
  node_src_details["Details<br/>song info<br/>[Details.jsx]"]
end

subgraph group_group_audio["Playback and visuals"]
  node_src_player["Player<br/>playback orchestrator<br/>[Player.jsx]"]
  node_src_use_player["usePlayer<br/>player hook<br/>[usePlayer.js]"]
  node_src_visualizer["Visualizer<br/>note timeline<br/>[Visualizer.jsx]"]
  node_src_pixi["Pixi hook<br/>canvas bridge"]
end

subgraph group_group_instruments["Instruments"]
  node_src_instrument_manager["InstrumentMgr<br/>instrument coordinator"]
  node_src_instrument["Instrument<br/>[Instrument.jsx]"]
  node_src_piano["Piano<br/>instrument ui<br/>[Piano.jsx]"]
  node_src_recorder["Recorder<br/>instrument ui<br/>[Recorder.jsx]"]
  node_src_sampler_factory["Sampler factory<br/>sample bridge<br/>[factory.js]"]
  node_src_sampler_piano["piano loader<br/>sample loader<br/>[piano.js]"]
  node_src_sampler_recorder["recorder loader<br/>sample loader<br/>[recorder.js]"]
end

subgraph group_group_content["Static content"]
  node_public_songs["Songs<br/>static catalog<br/>[index.json]"]
  node_public_samples["Samples<br/>static packs<br/>[index.json]"]
  node_fingering_chart["Fingering chart<br/>reference data"]
end

subgraph group_group_scripts["Scripts"]
  node_scripts_assets["Asset scripts<br/>content pipeline<br/>[wav2mp3-folder.mjs]"]
  node_vite_config["Vite config<br/>build config<br/>[vite.config.js]"]
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"includes"| node_src_header
node_src_app -->|"includes"| node_src_directory
node_src_app -->|"includes"| node_src_player
node_src_app -->|"includes"| node_src_visualizer
node_src_app -->|"includes"| node_src_details
node_src_app -->|"includes"| node_src_instrument_manager
node_src_player -->|"uses"| node_src_use_player
node_src_player -->|"loads"| node_public_songs
node_src_player -->|"drives"| node_src_instrument_manager
node_src_visualizer -->|"renders via"| node_src_pixi
node_src_visualizer -->|"syncs to"| node_public_songs
node_src_instrument_manager -->|"coordinates"| node_src_instrument
node_src_instrument_manager -->|"hosts"| node_src_piano
node_src_instrument_manager -->|"hosts"| node_src_recorder
node_src_piano -->|"loads samples via"| node_src_sampler_piano
node_src_recorder -->|"loads samples via"| node_src_sampler_recorder
node_src_sampler_piano -->|"built by"| node_src_sampler_factory
node_src_sampler_recorder -->|"built by"| node_src_sampler_factory
node_src_sampler_factory -->|"reads"| node_public_samples
node_src_recorder -->|"references"| node_fingering_chart
node_scripts_assets -->|"prepares"| node_public_samples
node_scripts_assets -->|"prepares"| node_public_songs
node_vite_config -->|"bundles"| node_src_main

click node_src_main "https://github.com/lhuthng/synrecordia/blob/main/src/main.jsx"
click node_src_app "https://github.com/lhuthng/synrecordia/blob/main/src/App.jsx"
click node_src_header "https://github.com/lhuthng/synrecordia/blob/main/src/components/Header.jsx"
click node_src_directory "https://github.com/lhuthng/synrecordia/blob/main/src/components/Directory.jsx"
click node_src_details "https://github.com/lhuthng/synrecordia/blob/main/src/components/Details.jsx"
click node_src_player "https://github.com/lhuthng/synrecordia/blob/main/src/components/Player.jsx"
click node_src_use_player "https://github.com/lhuthng/synrecordia/blob/main/src/hooks/usePlayer.js"
click node_src_visualizer "https://github.com/lhuthng/synrecordia/blob/main/src/components/Visualizer.jsx"
click node_src_pixi "https://github.com/lhuthng/synrecordia/blob/main/src/hooks/usePixiVisualizer.js"
click node_src_instrument_manager "https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/InstrumentManager.jsx"
click node_src_instrument "https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/Instrument.jsx"
click node_src_piano "https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/Piano.jsx"
click node_src_recorder "https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/Recorder.jsx"
click node_src_sampler_factory "https://github.com/lhuthng/synrecordia/blob/main/src/libs/packedSampler/factory.js"
click node_src_sampler_piano "https://github.com/lhuthng/synrecordia/blob/main/src/libs/packedSampler/piano.js"
click node_src_sampler_recorder "https://github.com/lhuthng/synrecordia/blob/main/src/libs/packedSampler/recorder.js"
click node_public_songs "https://github.com/lhuthng/synrecordia/blob/main/public/songs/index.json"
click node_public_samples "https://github.com/lhuthng/synrecordia/blob/main/public/samples/piano/index.json"
click node_fingering_chart "https://github.com/lhuthng/synrecordia/blob/main/src/assets/references/fingering-chart.json"
click node_scripts_assets "https://github.com/lhuthng/synrecordia/blob/main/scripts/wav2mp3-folder.mjs"
click node_vite_config "https://github.com/lhuthng/synrecordia/blob/main/vite.config.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_src_main,node_src_app,node_src_header,node_src_directory,node_src_details toneBlue
class node_src_player,node_src_use_player,node_src_visualizer,node_src_pixi toneAmber
class node_src_instrument_manager,node_src_instrument,node_src_piano,node_src_recorder,node_src_sampler_factory,node_src_sampler_piano,node_src_sampler_recorder toneMint
class node_public_songs,node_public_samples,node_fingering_chart toneRose
class node_scripts_assets,node_vite_config toneIndigo
```

## Components

### React app

Browser UI composition and runtime shell

- [main](https://github.com/lhuthng/synrecordia/blob/main/src/main.jsx): entry · Bootstraps the React app into the page · `src/main.jsx`
- [App](https://github.com/lhuthng/synrecordia/blob/main/src/App.jsx): composition · Top-level app shell that wires together all major UI areas · `src/App.jsx`
- [Header](https://github.com/lhuthng/synrecordia/blob/main/src/components/Header.jsx): ui shell · Primary top bar and navigation chrome · `src/components/Header.jsx`
- [Directory](https://github.com/lhuthng/synrecordia/blob/main/src/components/Directory.jsx): song browser · Song/library navigation and selection · `src/components/Directory.jsx`
- [Details](https://github.com/lhuthng/synrecordia/blob/main/src/components/Details.jsx): song info · Metadata and contextual details for the current song or track · `src/components/Details.jsx`

### Playback and visuals

Timing, audio scheduling, and canvas visualization

- [Player](https://github.com/lhuthng/synrecordia/blob/main/src/components/Player.jsx): playback orchestrator · Controls transport, tempo, looping, scrubbing, and track selection · `src/components/Player.jsx`
- [usePlayer](https://github.com/lhuthng/synrecordia/blob/main/src/hooks/usePlayer.js): player hook · Shared playback state and control logic · `src/hooks/usePlayer.js`
- [Visualizer](https://github.com/lhuthng/synrecordia/blob/main/src/components/Visualizer.jsx): note timeline · Renders synchronized note and fingering graphics · `src/components/Visualizer.jsx`
- [Pixi hook](https://github.com/lhuthng/synrecordia/blob/main/src/hooks/usePixiVisualizer.js): canvas bridge · Imperative PIXI.js rendering and animation layer · `src/hooks/usePixiVisualizer.js`

### Instruments

Instrument controls and sample-pack integration

- [InstrumentMgr](https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/InstrumentManager.jsx): instrument coordinator · Switches and coordinates active instrument instances · `src/components/instruments/InstrumentManager.jsx`
- [Instrument](https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/Instrument.jsx): instrument base · Shared instrument controls such as volume and variants · `src/components/instruments/Instrument.jsx`
- [Piano](https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/Piano.jsx): instrument ui · Piano instrument controls and behavior · `src/components/instruments/Piano.jsx`
- [Recorder](https://github.com/lhuthng/synrecordia/blob/main/src/components/instruments/Recorder.jsx): instrument ui · Recorder instrument controls and behavior · `src/components/instruments/Recorder.jsx`
- [Sampler factory](https://github.com/lhuthng/synrecordia/blob/main/src/libs/packedSampler/factory.js): sample bridge · Creates packed samplers from static sample-pack manifests · `src/libs/packedSampler/factory.js`
- [piano loader](https://github.com/lhuthng/synrecordia/blob/main/src/libs/packedSampler/piano.js): sample loader · Piano sample-pack loader · `src/libs/packedSampler/piano.js`
- [recorder loader](https://github.com/lhuthng/synrecordia/blob/main/src/libs/packedSampler/recorder.js): sample loader · Recorder sample-pack loader · `src/libs/packedSampler/recorder.js`

### Static content

Songs, samples, and reference assets served by the host

- [Songs](https://github.com/lhuthng/synrecordia/blob/main/public/songs/index.json): static catalog · Song JSON files and library index served as static content · `public/songs/index.json`
- [Samples](https://github.com/lhuthng/synrecordia/blob/main/public/samples/piano/index.json): static packs · Versioned instrument sample packs and manifests · `public/samples/piano/index.json`
- [Fingering chart](https://github.com/lhuthng/synrecordia/blob/main/src/assets/references/fingering-chart.json): reference data · Recorder fingering reference used by the UI · `src/assets/references/fingering-chart.json`

### Scripts

One-off asset preparation and content processing tools

- [Asset scripts](https://github.com/lhuthng/synrecordia/blob/main/scripts/wav2mp3-folder.mjs): content pipeline · One-off scripts that transform audio and song assets · `scripts/wav2mp3-folder.mjs`
- [Vite config](https://github.com/lhuthng/synrecordia/blob/main/vite.config.js): build config · Frontend build and dev server configuration · `vite.config.js`

## Connections

- main → App: mounts · Entry point mounts the top-level app
- App → Header: includes · App shell renders header chrome
- App → Directory: includes · App shell exposes song browsing
- App → Player: includes · App shell embeds playback controls
- App → Visualizer: includes · App shell embeds synchronized visual output
- App → Details: includes · App shell shows song and track details
- App → InstrumentMgr: includes · App shell hosts instrument switching and controls
- Player → usePlayer: uses · Player delegates shared playback state and actions
- Player → Songs: loads · Playback consumes song JSON content
- Player → InstrumentMgr: drives · Playback selects and schedules instrument tracks
- Visualizer → Pixi hook: renders via · Visualizer uses PIXI-backed canvas updates
- Visualizer → Songs: syncs to · Visualizer aligns graphics to song note data
- InstrumentMgr → Instrument: coordinates · Manager wraps shared instrument abstraction
- InstrumentMgr → Piano: hosts · Supports piano instrument variant
- InstrumentMgr → Recorder: hosts · Supports recorder instrument variant
- Piano → piano loader: loads samples via · Piano UI binds to piano sample loader
- Recorder → recorder loader: loads samples via · Recorder UI binds to recorder sample loader
- piano loader → Sampler factory: built by · Instrument loader is created through the packed-sampler bridge
- recorder loader → Sampler factory: built by · Instrument loader is created through the packed-sampler bridge
- Sampler factory → Samples: reads · Sampler bridge consumes manifest-driven sample packs
- Recorder → Fingering chart: references · Recorder UI uses fingering reference data
- Asset scripts → Samples: prepares · Scripts reshape and convert sample assets
- Asset scripts → Songs: prepares · Scripts generate or transform song assets
- Vite config → main: bundles · Build pipeline serves the app entry
