# arminsf/songnotes architecture

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

- Interactive diagram: https://gitdiagram.com/arminsf/songnotes
- Repository: https://github.com/arminsf/songnotes

## Overview

Songnotes is a browser-based song annotation editor. Users open or create a project, optionally import audio, then annotate a measure-based timeline with patterns, chords, and notes while using playback controls to synchronize annotations. The editor separates project data from transient UI state; timeline calculations and music-theory conversions support those editing stages, while JSON serialization and browser file APIs handle project exchange. The graph reflects README capabilities and SOURCE INDEX relationships; several listed components were not excerpted, so their internal behavior is not inferred.

Main entry points: [`src/store/project-store.ts`](https://github.com/arminsf/songnotes/blob/main/src/store/project-store.ts) (Project state), [`src/components/timeline/Timeline.tsx`](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/Timeline.tsx) (Timeline view), [`src/store/editor-store.ts`](https://github.com/arminsf/songnotes/blob/main/src/store/editor-store.ts) (Editor UI state), [`src/components/ribbon/Ribbon.tsx`](https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/Ribbon.tsx) (Ribbon controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_app["App switch<br/>[App.tsx]"]
  node_welcome["Welcome and import<br/>[Welcome.tsx]"]
end

subgraph group_workspace["Editing workspace"]
  node_editor["Editor shell<br/>[Editor.tsx]"]
  node_ribbon["Ribbon controls<br/>[Ribbon.tsx]"]
  node_playcontrols["Playback controls<br/>[RibbonDJ.tsx]"]
  node_seekbar["Audio seek bar<br/>[SeekBar.tsx]"]
  node_tapper["Tempo tapper<br/>[Tapper.tsx]"]
  node_timelineui["Timeline view<br/>[Timeline.tsx]"]
  node_measurerow["Measure rows<br/>[MeasureRow.tsx]"]
  node_measurecard["Measure card<br/>[MeasureCard.tsx]"]
  node_pausebar["Pause marker<br/>[PauseBar.tsx]"]
  node_sectionbar["Section marker<br/>[SectionBar.tsx]"]
  node_inlinebar["Inline timeline control<br/>[InlineBar.tsx]"]
  node_rightpanel["Editor side panel<br/>[RightPanel.tsx]"]
  node_projecteditor["Project settings<br/>[ProjectEditor.tsx]"]
  node_patterneditor["Pattern editor<br/>[PatternEditor.tsx]"]
  node_patternlist["Pattern list<br/>[PatternList.tsx]"]
  node_patterncard["Pattern card<br/>[PatternCard.tsx]"]
end

subgraph group_domain["Project domain"]
  node_projectstore["Project state<br/>[project-store.ts]"]
  node_editorstore["Editor UI state<br/>[editor-store.ts]"]
  node_projectmodel["Project model<br/>[project.ts]"]
  node_timelinecalc["Timeline calculations<br/>[timeline.ts]"]
  node_validation["Project validation<br/>[validation.ts]"]
  node_music["Music theory conversions<br/>[notes.ts]"]
end

subgraph group_services["Playback and files"]
  node_fileio["Project and audio files<br/>[io.ts]"]
  node_serialization["Project serialization<br/>[serialization.ts]"]
  node_playbackhook["Playback hook<br/>[usePlayback.ts]"]
  node_playback["Audio playback engine<br/>[playback.ts]"]
end

node_user(("Song editor user"))
node_browserfiles(("Browser file picker"))
node_audio["Imported audio"]

node_user -->|"uses"| node_app
node_app -->|"reads mode"| node_editorstore
node_app -->|"shows when closed"| node_welcome
node_app -->|"shows when open"| node_editor
node_welcome -->|"imports and exports"| node_fileio
node_welcome -->|"loads project"| node_projectstore
node_welcome -->|"sets editor state"| node_editorstore
node_browserfiles -->|"selects files"| node_fileio
node_fileio -->|"serializes project"| node_serialization
node_fileio -->|"creates audio URL"| node_audio
node_editor -->|"renders"| node_ribbon
node_editor -->|"renders"| node_timelineui
node_editor -->|"renders"| node_rightpanel
node_ribbon -->|"imports project helpers"| node_fileio
node_ribbon -->|"reads project"| node_projectstore
node_ribbon -->|"renders"| node_playcontrols
node_ribbon -->|"renders"| node_tapper
node_playcontrols -->|"controls playback"| node_playbackhook
node_playcontrols -->|"renders"| node_seekbar
node_seekbar -->|"reads and seeks"| node_playbackhook
node_timelineui -->|"reads UI state"| node_editorstore
node_timelineui -->|"reads project state"| node_projectstore
node_timelineui -->|"renders"| node_inlinebar
node_timelineui -->|"renders"| node_measurerow
node_timelineui -->|"renders"| node_pausebar
node_timelineui -->|"renders"| node_sectionbar
node_measurerow -->|"renders"| node_measurecard
node_measurecard -->|"edits measures"| node_projectstore
node_measurecard -->|"reads selection"| node_editorstore
node_measurecard -->|"calculates timing"| node_timelinecalc
node_measurecard -->|"seeks and reads time"| node_playbackhook
node_pausebar -->|"edits pauses"| node_projectstore
node_pausebar -->|"uses playback time"| node_playbackhook
node_pausebar -->|"calculates timing"| node_timelinecalc
node_sectionbar -->|"edits sections"| node_projectstore
node_inlinebar -->|"edits timeline"| node_projectstore
node_rightpanel -->|"renders"| node_projecteditor
node_rightpanel -->|"renders"| node_patterneditor
node_projecteditor -->|"edits project"| node_projectstore
node_projecteditor -->|"reads editor state"| node_editorstore
node_projecteditor -->|"uses note helpers"| node_music
node_projecteditor -->|"uses validation"| node_validation
node_patterneditor -->|"edits patterns"| node_projectstore
node_patterneditor -->|"reads selection"| node_editorstore
node_patterneditor -->|"converts chords"| node_music
node_patterneditor -->|"shows pattern list"| node_patternlist
node_patternlist -->|"renders"| node_patterncard
node_patterncard -->|"edits project patterns"| node_projectstore

click node_app "https://github.com/arminsf/songnotes/blob/main/src/App.tsx"
click node_welcome "https://github.com/arminsf/songnotes/blob/main/src/Welcome.tsx"
click node_editor "https://github.com/arminsf/songnotes/blob/main/src/Editor.tsx"
click node_ribbon "https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/Ribbon.tsx"
click node_playcontrols "https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/RibbonDJ.tsx"
click node_seekbar "https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/SeekBar.tsx"
click node_tapper "https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/Tapper.tsx"
click node_timelineui "https://github.com/arminsf/songnotes/blob/main/src/components/timeline/Timeline.tsx"
click node_measurerow "https://github.com/arminsf/songnotes/blob/main/src/components/timeline/MeasureRow.tsx"
click node_measurecard "https://github.com/arminsf/songnotes/blob/main/src/components/timeline/MeasureCard.tsx"
click node_pausebar "https://github.com/arminsf/songnotes/blob/main/src/components/timeline/PauseBar.tsx"
click node_sectionbar "https://github.com/arminsf/songnotes/blob/main/src/components/timeline/SectionBar.tsx"
click node_inlinebar "https://github.com/arminsf/songnotes/blob/main/src/components/timeline/InlineBar.tsx"
click node_rightpanel "https://github.com/arminsf/songnotes/blob/main/src/components/RightPanel.tsx"
click node_projecteditor "https://github.com/arminsf/songnotes/blob/main/src/components/ProjectEditor.tsx"
click node_patterneditor "https://github.com/arminsf/songnotes/blob/main/src/components/patterneditor/PatternEditor.tsx"
click node_patternlist "https://github.com/arminsf/songnotes/blob/main/src/components/patterneditor/PatternList.tsx"
click node_patterncard "https://github.com/arminsf/songnotes/blob/main/src/components/patterneditor/PatternCard.tsx"
click node_projectstore "https://github.com/arminsf/songnotes/blob/main/src/store/project-store.ts"
click node_editorstore "https://github.com/arminsf/songnotes/blob/main/src/store/editor-store.ts"
click node_projectmodel "https://github.com/arminsf/songnotes/blob/main/src/types/project.ts"
click node_timelinecalc "https://github.com/arminsf/songnotes/blob/main/src/project/timeline.ts"
click node_validation "https://github.com/arminsf/songnotes/blob/main/src/project/validation.ts"
click node_music "https://github.com/arminsf/songnotes/blob/main/src/musictheory/notes.ts"
click node_fileio "https://github.com/arminsf/songnotes/blob/main/src/file/io.ts"
click node_serialization "https://github.com/arminsf/songnotes/blob/main/src/file/serialization.ts"
click node_playbackhook "https://github.com/arminsf/songnotes/blob/main/src/playback/usePlayback.ts"
click node_playback "https://github.com/arminsf/songnotes/blob/main/src/playback/playback.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_welcome,node_user,node_browserfiles toneBlue
class node_editor,node_ribbon,node_playcontrols,node_seekbar,node_tapper,node_timelineui,node_measurerow,node_measurecard,node_pausebar,node_sectionbar,node_inlinebar,node_rightpanel,node_projecteditor,node_patterneditor,node_patternlist,node_patterncard toneAmber
class node_projectstore,node_editorstore,node_projectmodel,node_timelinecalc,node_validation,node_music toneMint
class node_fileio,node_serialization,node_playbackhook,node_playback toneRose
class node_audio toneIndigo
```

## Components

### App entry

- [App switch](https://github.com/arminsf/songnotes/blob/main/src/App.tsx): `src/App.tsx`
- [Welcome and import](https://github.com/arminsf/songnotes/blob/main/src/Welcome.tsx): `src/Welcome.tsx`

### Editing workspace

- [Editor shell](https://github.com/arminsf/songnotes/blob/main/src/Editor.tsx): `src/Editor.tsx`
- [Ribbon controls](https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/Ribbon.tsx): `src/components/ribbon/Ribbon.tsx`
- [Playback controls](https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/RibbonDJ.tsx): `src/components/ribbon/RibbonDJ.tsx`
- [Audio seek bar](https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/SeekBar.tsx): `src/components/ribbon/SeekBar.tsx`
- [Tempo tapper](https://github.com/arminsf/songnotes/blob/main/src/components/ribbon/Tapper.tsx): `src/components/ribbon/Tapper.tsx`
- [Timeline view](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/Timeline.tsx): `src/components/timeline/Timeline.tsx`
- [Measure rows](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/MeasureRow.tsx): `src/components/timeline/MeasureRow.tsx`
- [Measure card](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/MeasureCard.tsx): `src/components/timeline/MeasureCard.tsx`
- [Pause marker](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/PauseBar.tsx): `src/components/timeline/PauseBar.tsx`
- [Section marker](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/SectionBar.tsx): `src/components/timeline/SectionBar.tsx`
- [Inline timeline control](https://github.com/arminsf/songnotes/blob/main/src/components/timeline/InlineBar.tsx): `src/components/timeline/InlineBar.tsx`
- [Editor side panel](https://github.com/arminsf/songnotes/blob/main/src/components/RightPanel.tsx): `src/components/RightPanel.tsx`
- [Project settings](https://github.com/arminsf/songnotes/blob/main/src/components/ProjectEditor.tsx): `src/components/ProjectEditor.tsx`
- [Pattern editor](https://github.com/arminsf/songnotes/blob/main/src/components/patterneditor/PatternEditor.tsx): `src/components/patterneditor/PatternEditor.tsx`
- [Pattern list](https://github.com/arminsf/songnotes/blob/main/src/components/patterneditor/PatternList.tsx): `src/components/patterneditor/PatternList.tsx`
- [Pattern card](https://github.com/arminsf/songnotes/blob/main/src/components/patterneditor/PatternCard.tsx): `src/components/patterneditor/PatternCard.tsx`

### Project domain

- [Project state](https://github.com/arminsf/songnotes/blob/main/src/store/project-store.ts): `src/store/project-store.ts`
- [Editor UI state](https://github.com/arminsf/songnotes/blob/main/src/store/editor-store.ts): `src/store/editor-store.ts`
- [Project model](https://github.com/arminsf/songnotes/blob/main/src/types/project.ts): `src/types/project.ts`
- [Timeline calculations](https://github.com/arminsf/songnotes/blob/main/src/project/timeline.ts): `src/project/timeline.ts`
- [Project validation](https://github.com/arminsf/songnotes/blob/main/src/project/validation.ts): `src/project/validation.ts`
- [Music theory conversions](https://github.com/arminsf/songnotes/blob/main/src/musictheory/notes.ts): `src/musictheory/notes.ts`

### Playback and files

- [Project and audio files](https://github.com/arminsf/songnotes/blob/main/src/file/io.ts): `src/file/io.ts`
- [Project serialization](https://github.com/arminsf/songnotes/blob/main/src/file/serialization.ts): `src/file/serialization.ts`
- [Playback hook](https://github.com/arminsf/songnotes/blob/main/src/playback/usePlayback.ts): `src/playback/usePlayback.ts`
- [Audio playback engine](https://github.com/arminsf/songnotes/blob/main/src/playback/playback.ts): `src/playback/playback.ts`

### Other components

- **Song editor user**
- **Browser file picker**
- **Imported audio**

## Connections

- Song editor user → App switch: uses (evidence: `README.md`)
- App switch → Editor UI state: reads mode (evidence: `src/App.tsx`)
- App switch → Welcome and import: shows when closed (evidence: `src/App.tsx`)
- App switch → Editor shell: shows when open (evidence: `src/App.tsx`)
- Welcome and import → Project and audio files: imports and exports (evidence: `src/Welcome.tsx`)
- Welcome and import → Project state: loads project (evidence: `src/Welcome.tsx`)
- Welcome and import → Editor UI state: sets editor state (evidence: `src/Welcome.tsx`)
- Browser file picker → Project and audio files: selects files (evidence: `src/file/io.ts`)
- Project and audio files → Project serialization: serializes project (evidence: `src/file/io.ts`)
- Project and audio files → Imported audio: creates audio URL (evidence: `src/file/io.ts`)
- Editor shell → Ribbon controls: renders (evidence: `src/Editor.tsx`)
- Editor shell → Timeline view: renders (evidence: `src/Editor.tsx`)
- Editor shell → Editor side panel: renders (evidence: `src/Editor.tsx`)
- Ribbon controls → Project and audio files: imports project helpers (evidence: `src/components/ribbon/Ribbon.tsx`)
- Ribbon controls → Project state: reads project (evidence: `src/components/ribbon/Ribbon.tsx`)
- Ribbon controls → Playback controls: renders (evidence: `src/components/ribbon/Ribbon.tsx`)
- Ribbon controls → Tempo tapper: renders (evidence: `src/components/ribbon/Ribbon.tsx`)
- Playback controls → Playback hook: controls playback (evidence: `src/components/ribbon/RibbonDJ.tsx`)
- Playback controls → Audio seek bar: renders (evidence: `src/components/ribbon/RibbonDJ.tsx`)
- Audio seek bar → Playback hook: reads and seeks (evidence: `src/components/ribbon/SeekBar.tsx`)
- Timeline view → Editor UI state: reads UI state (evidence: `src/components/timeline/Timeline.tsx`)
- Timeline view → Project state: reads project state (evidence: `src/components/timeline/Timeline.tsx`)
- Timeline view → Inline timeline control: renders (evidence: `src/components/timeline/Timeline.tsx`)
- Timeline view → Measure rows: renders (evidence: `src/components/timeline/Timeline.tsx`)
- Timeline view → Pause marker: renders (evidence: `src/components/timeline/Timeline.tsx`)
- Timeline view → Section marker: renders (evidence: `src/components/timeline/Timeline.tsx`)
- Measure rows → Measure card: renders (evidence: `src/components/timeline/MeasureRow.tsx`)
- Measure card → Project state: edits measures (evidence: `src/components/timeline/MeasureCard.tsx`)
- Measure card → Editor UI state: reads selection (evidence: `src/components/timeline/MeasureCard.tsx`)
- Measure card → Timeline calculations: calculates timing (evidence: `src/components/timeline/MeasureCard.tsx`)
- Measure card → Playback hook: seeks and reads time (evidence: `src/components/timeline/MeasureCard.tsx`)
- Pause marker → Project state: edits pauses (evidence: `src/components/timeline/PauseBar.tsx`)
- Pause marker → Playback hook: uses playback time (evidence: `src/components/timeline/PauseBar.tsx`)
- Pause marker → Timeline calculations: calculates timing (evidence: `src/components/timeline/PauseBar.tsx`)
- Section marker → Project state: edits sections (evidence: `src/components/timeline/SectionBar.tsx`)
- Inline timeline control → Project state: edits timeline (evidence: `src/components/timeline/InlineBar.tsx`)
- Editor side panel → Project settings: renders (evidence: `src/components/RightPanel.tsx`)
- Editor side panel → Pattern editor: renders (evidence: `src/components/RightPanel.tsx`)
- Project settings → Project state: edits project (evidence: `src/components/ProjectEditor.tsx`)
- Project settings → Editor UI state: reads editor state (evidence: `src/components/ProjectEditor.tsx`)
- Project settings → Music theory conversions: uses note helpers (evidence: `src/components/ProjectEditor.tsx`)
- Project settings → Project validation: uses validation (evidence: `src/components/ProjectEditor.tsx`)
- Pattern editor → Project state: edits patterns (evidence: `src/components/patterneditor/PatternEditor.tsx`)
- Pattern editor → Editor UI state: reads selection (evidence: `src/components/patterneditor/PatternEditor.tsx`)
- Pattern editor → Music theory conversions: converts chords (evidence: `src/components/patterneditor/PatternEditor.tsx`)
- Pattern editor → Pattern list: shows pattern list (evidence: `src/components/patterneditor/PatternEditor.tsx`)
- Pattern list → Pattern card: renders (evidence: `src/components/patterneditor/PatternList.tsx`)
- Pattern card → Project state: edits project patterns (evidence: `src/components/patterneditor/PatternCard.tsx`)
