# ckeen302/chordcraft architecture

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

- Interactive diagram: https://gitdiagram.com/ckeen302/chordcraft
- Repository: https://github.com/ckeen302/chordcraft

## Overview

ChordCraft is a browser-based progression studio. Users generate or load harmony, edit its note events in the piano roll, then play it through the transport or export MIDI. The graph also preserves the song library, preset finder, analysis, and optional local-AI capability. The README documents these product branches; some implementation details are represented by their exact enclosing paths because their source was not sampled.

Main entry points: [`components/ChordCraftApp.tsx`](https://github.com/ckeen302/chordcraft/blob/main/components/ChordCraftApp.tsx) (Studio composition), [`components/chord-lab/ChordLab.tsx`](https://github.com/ckeen302/chordcraft/blob/main/components/chord-lab/ChordLab.tsx) (Chord lab), [`hooks/useTransport.ts`](https://github.com/ckeen302/chordcraft/blob/main/hooks/useTransport.ts) (Playback scheduler), [`components/songs/PopularSongs.tsx`](https://github.com/ckeen302/chordcraft/blob/main/components/songs/PopularSongs.tsx) (Popular songs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Studio UI"]
  node_app["App shell<br/>[page.tsx]"]
  node_studio["Studio composition<br/>[ChordCraftApp.tsx]"]
  node_lab["Chord lab<br/>[ChordLab.tsx]"]
  node_rollui["Piano roll<br/>[PianoRoll.tsx]"]
  node_transportui["Transport bar<br/>[TransportBar.tsx]"]
  node_settings["Settings<br/>[SettingsPanel.tsx]"]
  node_shortcuts["Shortcut help<br/>[ShortcutsHelp.tsx]"]
end

subgraph group_harmony["Harmony and editing"]
  node_store["Progression state<br/>[useStore.ts]"]
  node_theory["Harmony generation<br/>[harmony.ts]"]
  node_theorylib["Theory operations"]
  node_notemodel["Note conversion<br/>[notes.ts]"]
  node_analysis["Harmonic analysis<br/>[analysis.ts]"]
  node_ai["Local AI analysis<br/>[ollama.ts]"]
end

subgraph group_playback["Playback and export"]
  node_transport["Playback scheduler<br/>[useTransport.ts]"]
  node_audio["Sample audio engine<br/>[engine.ts]"]
  node_metro["Metronome<br/>[metronome.ts]"]
  node_midi["MIDI export<br/>[export.ts]"]
end

subgraph group_libraries["Reference libraries"]
  node_songs["Popular songs<br/>[PopularSongs.tsx]"]
  node_songdata["Song progression data<br/>[popular-songs.ts]"]
  node_presets["Preset finder<br/>[PresetLibrary.tsx]"]
  node_presetdata["Preset catalog<br/>[presets.ts]"]
end

node_user(("Musician"))

node_user -->|"opens studio"| node_app
node_app -->|"renders"| node_studio
node_studio -->|"hosts"| node_lab
node_studio -->|"hosts"| node_rollui
node_studio -->|"hosts"| node_transportui
node_studio -->|"hosts"| node_settings
node_studio -->|"hosts"| node_shortcuts
node_lab -->|"generates harmony"| node_theory
node_lab -->|"parses and voices"| node_theorylib
node_lab -->|"converts chords"| node_notemodel
node_lab -->|"updates progression"| node_store
node_rollui -->|"edits note state"| node_store
node_transportui -->|"controls playback"| node_transport
node_transport -->|"reads transport state"| node_store
node_transport -->|"schedules notes"| node_audio
node_transport -->|"starts and stops"| node_metro
node_audio -->|"plays sound"| node_user
node_lab -->|"analyzes progression"| node_analysis
node_lab -.->|"requests deeper take"| node_ai
node_ai -.->|"queries local Ollama"| node_user
node_lab -->|"exports note events"| node_midi
node_songs -->|"reads catalog"| node_songdata
node_songs -->|"loads song"| node_store
node_songs -->|"exports song"| node_midi
node_studio -->|"shows library"| node_songs
node_studio -->|"shows finder"| node_presets
node_presets -->|"browses catalog"| node_presetdata

click node_app "https://github.com/ckeen302/chordcraft/blob/main/app/page.tsx"
click node_studio "https://github.com/ckeen302/chordcraft/blob/main/components/ChordCraftApp.tsx"
click node_lab "https://github.com/ckeen302/chordcraft/blob/main/components/chord-lab/ChordLab.tsx"
click node_rollui "https://github.com/ckeen302/chordcraft/blob/main/components/piano/PianoRoll.tsx"
click node_transportui "https://github.com/ckeen302/chordcraft/blob/main/components/layout/TransportBar.tsx"
click node_settings "https://github.com/ckeen302/chordcraft/blob/main/components/layout/SettingsPanel.tsx"
click node_shortcuts "https://github.com/ckeen302/chordcraft/blob/main/components/layout/ShortcutsHelp.tsx"
click node_store "https://github.com/ckeen302/chordcraft/blob/main/store/useStore.ts"
click node_theory "https://github.com/ckeen302/chordcraft/blob/main/lib/theory/harmony.ts"
click node_theorylib "https://github.com/ckeen302/chordcraft/tree/main/lib/theory"
click node_notemodel "https://github.com/ckeen302/chordcraft/blob/main/lib/roll/notes.ts"
click node_analysis "https://github.com/ckeen302/chordcraft/blob/main/lib/theory/analysis.ts"
click node_ai "https://github.com/ckeen302/chordcraft/blob/main/lib/ai/ollama.ts"
click node_transport "https://github.com/ckeen302/chordcraft/blob/main/hooks/useTransport.ts"
click node_audio "https://github.com/ckeen302/chordcraft/blob/main/lib/audio/engine.ts"
click node_metro "https://github.com/ckeen302/chordcraft/blob/main/lib/audio/metronome.ts"
click node_midi "https://github.com/ckeen302/chordcraft/blob/main/lib/midi/export.ts"
click node_songs "https://github.com/ckeen302/chordcraft/blob/main/components/songs/PopularSongs.tsx"
click node_songdata "https://github.com/ckeen302/chordcraft/blob/main/lib/data/popular-songs.ts"
click node_presets "https://github.com/ckeen302/chordcraft/blob/main/components/presets/PresetLibrary.tsx"
click node_presetdata "https://github.com/ckeen302/chordcraft/blob/main/lib/data/presets.ts"

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_app,node_studio,node_lab,node_rollui,node_transportui,node_settings,node_shortcuts toneBlue
class node_store,node_theory,node_theorylib,node_notemodel,node_analysis,node_ai toneAmber
class node_transport,node_audio,node_metro,node_midi toneMint
class node_songs,node_songdata,node_presets,node_presetdata toneRose
class node_user toneIndigo
```

## Components

### Studio UI

- [App shell](https://github.com/ckeen302/chordcraft/blob/main/app/page.tsx): `app/page.tsx`
- [Studio composition](https://github.com/ckeen302/chordcraft/blob/main/components/ChordCraftApp.tsx): `components/ChordCraftApp.tsx`
- [Chord lab](https://github.com/ckeen302/chordcraft/blob/main/components/chord-lab/ChordLab.tsx): `components/chord-lab/ChordLab.tsx`
- [Piano roll](https://github.com/ckeen302/chordcraft/blob/main/components/piano/PianoRoll.tsx): `components/piano/PianoRoll.tsx`
- [Transport bar](https://github.com/ckeen302/chordcraft/blob/main/components/layout/TransportBar.tsx): `components/layout/TransportBar.tsx`
- [Settings](https://github.com/ckeen302/chordcraft/blob/main/components/layout/SettingsPanel.tsx): `components/layout/SettingsPanel.tsx`
- [Shortcut help](https://github.com/ckeen302/chordcraft/blob/main/components/layout/ShortcutsHelp.tsx): `components/layout/ShortcutsHelp.tsx`

### Harmony and editing

- [Progression state](https://github.com/ckeen302/chordcraft/blob/main/store/useStore.ts): `store/useStore.ts`
- [Harmony generation](https://github.com/ckeen302/chordcraft/blob/main/lib/theory/harmony.ts): `lib/theory/harmony.ts`
- [Theory operations](https://github.com/ckeen302/chordcraft/tree/main/lib/theory): `lib/theory`
- [Note conversion](https://github.com/ckeen302/chordcraft/blob/main/lib/roll/notes.ts): `lib/roll/notes.ts`
- [Harmonic analysis](https://github.com/ckeen302/chordcraft/blob/main/lib/theory/analysis.ts): `lib/theory/analysis.ts`
- [Local AI analysis](https://github.com/ckeen302/chordcraft/blob/main/lib/ai/ollama.ts): `lib/ai/ollama.ts`

### Playback and export

- [Playback scheduler](https://github.com/ckeen302/chordcraft/blob/main/hooks/useTransport.ts): `hooks/useTransport.ts`
- [Sample audio engine](https://github.com/ckeen302/chordcraft/blob/main/lib/audio/engine.ts): `lib/audio/engine.ts`
- [Metronome](https://github.com/ckeen302/chordcraft/blob/main/lib/audio/metronome.ts): `lib/audio/metronome.ts`
- [MIDI export](https://github.com/ckeen302/chordcraft/blob/main/lib/midi/export.ts): `lib/midi/export.ts`

### Reference libraries

- [Popular songs](https://github.com/ckeen302/chordcraft/blob/main/components/songs/PopularSongs.tsx): `components/songs/PopularSongs.tsx`
- [Song progression data](https://github.com/ckeen302/chordcraft/blob/main/lib/data/popular-songs.ts): `lib/data/popular-songs.ts`
- [Preset finder](https://github.com/ckeen302/chordcraft/blob/main/components/presets/PresetLibrary.tsx): `components/presets/PresetLibrary.tsx`
- [Preset catalog](https://github.com/ckeen302/chordcraft/blob/main/lib/data/presets.ts): `lib/data/presets.ts`

### Other components

- **Musician**

## Connections

- Musician → App shell: opens studio
- App shell → Studio composition: renders
- Studio composition → Chord lab: hosts
- Studio composition → Piano roll: hosts
- Studio composition → Transport bar: hosts
- Studio composition → Settings: hosts
- Studio composition → Shortcut help: hosts
- Chord lab → Harmony generation: generates harmony
- Chord lab → Theory operations: parses and voices
- Chord lab → Note conversion: converts chords
- Chord lab → Progression state: updates progression
- Piano roll → Progression state: edits note state
- Transport bar → Playback scheduler: controls playback
- Playback scheduler → Progression state: reads transport state
- Playback scheduler → Sample audio engine: schedules notes
- Playback scheduler → Metronome: starts and stops
- Sample audio engine → Musician: plays sound
- Chord lab → Harmonic analysis: analyzes progression
- Chord lab → Local AI analysis: requests deeper take
- Local AI analysis → Musician: queries local Ollama
- Chord lab → MIDI export: exports note events
- Popular songs → Song progression data: reads catalog
- Popular songs → Progression state: loads song
- Popular songs → MIDI export: exports song
- Studio composition → Popular songs: shows library
- Studio composition → Preset finder: shows finder
- Preset finder → Preset catalog: browses catalog