# kanishkkar2817/circular-music-palyer architecture

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

- Interactive diagram: https://gitdiagram.com/kanishkkar2817/circular-music-palyer
- Repository: https://github.com/kanishkkar2817/circular-music-palyer

## Overview

This is a browser-based music player and data-structures learning demo. Users add or search songs, enqueue normal or play-next tracks, and control playback; the app coordinates queue selection, synthesized audio, and saved preferences. Separate views visualize circular-queue operations, priority ordering, stack history, and hash lookup, with guide, complexity, and operation-log panels. The excerpts establish the app’s calls into core services and structures; wiring for several UI components is documented only by the App import index, so uncertain component-to-component links are omitted.

Main entry points: [`src/App.tsx`](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/App.tsx) (Player coordinator), [`src/components/MusicPlayer.tsx`](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/MusicPlayer.tsx) (Playback controls), [`src/components/PriorityQueuePanel.tsx`](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/PriorityQueuePanel.tsx) (Priority panel), [`src/components/StackPanel.tsx`](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/StackPanel.tsx) (Stack panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App coordination"]
  node_app["Player coordinator<br/>[App.tsx]"]
  node_songs["Sample catalog<br/>[sampleSongs.ts]"]
  node_storage[("Browser storage<br/>[StorageService.ts]")]
  node_add["Add song modal<br/>[AddSongModal.tsx]"]
  node_playlist["Playlist view<br/>[Playlist.tsx]"]
  node_navbar["Navigation<br/>[Navbar.tsx]"]
  node_sidebar["Sidebar<br/>[Sidebar.tsx]"]
  node_toast["Toast notifications<br/>[ToastContainer.tsx]"]
end

subgraph group_playback["Music playback"]
  node_audio["Synth audio service<br/>[AudioService.ts]"]
  node_musicui["Playback controls<br/>[MusicPlayer.tsx]"]
end

subgraph group_structures["Data structures"]
  node_queue["Circular queue<br/>[CircularQueue.ts]"]
  node_priority["Priority queue<br/>[PriorityQueue.ts]"]
  node_stack["Recent history stack<br/>[Stack.ts]"]
  node_hash["Song hash map<br/>[SongHashMap.ts]"]
end

subgraph group_learning["Learning interface"]
  node_queueviz["Queue visualizer"]
  node_dsamode["DSA mode panel<br/>[DSAModePanel.tsx]"]
  node_priorityui["Priority panel"]
  node_stackui["Stack panel<br/>[StackPanel.tsx]"]
  node_hashui["Hash search panel"]
  node_guide["How-it-works guide"]
  node_complexity["Complexity panel"]
  node_oplog["Operation log<br/>[OperationLog.tsx]"]
  node_presentation["Presentation mode"]
end

node_listener(("Listener"))

node_listener -->|"uses player"| node_app
node_app -->|"loads catalog"| node_songs
node_app -->|"loads and saves"| node_storage
node_app -->|"manages playback queue"| node_queue
node_app -->|"enqueues priority"| node_priority
node_app -->|"indexes songs"| node_hash
node_app -.->|"maintains history"| node_stack
node_app -->|"controls audio"| node_audio
node_app -->|"renders controls"| node_musicui
node_musicui -->|"reads playback data"| node_audio
node_app -->|"renders modal"| node_add
node_app -->|"renders view"| node_playlist
node_app -->|"renders navigation"| node_navbar
node_app -->|"renders sidebar"| node_sidebar
node_app -->|"renders visualizer"| node_queueviz
node_app -->|"renders DSA panel"| node_dsamode
node_app -->|"renders panel"| node_priorityui
node_app -->|"renders panel"| node_stackui
node_app -.->|"renders search panel"| node_hashui
node_app -->|"renders guide"| node_guide
node_app -->|"renders panel"| node_complexity
node_app -->|"renders log"| node_oplog
node_app -.->|"renders modal"| node_presentation
node_app -.->|"renders notifications"| node_toast
node_priorityui -->|"reads queue"| node_priority
node_stackui -->|"reads history"| node_stack

click node_app "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/App.tsx"
click node_songs "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/data/sampleSongs.ts"
click node_storage "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/services/StorageService.ts"
click node_audio "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/services/AudioService.ts"
click node_musicui "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/MusicPlayer.tsx"
click node_queue "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/CircularQueue.ts"
click node_priority "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/PriorityQueue.ts"
click node_stack "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/Stack.ts"
click node_hash "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/SongHashMap.ts"
click node_add "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/AddSongModal.tsx"
click node_playlist "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/Playlist.tsx"
click node_navbar "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/Navbar.tsx"
click node_sidebar "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/Sidebar.tsx"
click node_queueviz "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/CircularQueueVisualizer.tsx"
click node_dsamode "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/DSAModePanel.tsx"
click node_priorityui "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/PriorityQueuePanel.tsx"
click node_stackui "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/StackPanel.tsx"
click node_hashui "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/HashMapSearchPanel.tsx"
click node_guide "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/HowItWorksGuide.tsx"
click node_complexity "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/ComplexityPanel.tsx"
click node_oplog "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/OperationLog.tsx"
click node_presentation "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/PresentationModeModal.tsx"
click node_toast "https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/ToastContainer.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_app,node_songs,node_storage,node_add,node_playlist,node_navbar,node_sidebar,node_toast toneBlue
class node_audio,node_musicui toneAmber
class node_queue,node_priority,node_stack,node_hash toneMint
class node_queueviz,node_dsamode,node_priorityui,node_stackui,node_hashui,node_guide,node_complexity,node_oplog,node_presentation toneRose
class node_listener toneIndigo
```

## Components

### App coordination

- [Player coordinator](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/App.tsx): `src/App.tsx`
- [Sample catalog](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/data/sampleSongs.ts): `src/data/sampleSongs.ts`
- [Browser storage](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/services/StorageService.ts): `src/services/StorageService.ts`
- [Add song modal](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/AddSongModal.tsx): `src/components/AddSongModal.tsx`
- [Playlist view](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/Playlist.tsx): `src/components/Playlist.tsx`
- [Navigation](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/Navbar.tsx): `src/components/Navbar.tsx`
- [Sidebar](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/Sidebar.tsx): `src/components/Sidebar.tsx`
- [Toast notifications](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/ToastContainer.tsx): `src/components/ToastContainer.tsx`

### Music playback

- [Synth audio service](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/services/AudioService.ts): `src/services/AudioService.ts`
- [Playback controls](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/MusicPlayer.tsx): `src/components/MusicPlayer.tsx`

### Data structures

- [Circular queue](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/CircularQueue.ts): `src/dataStructures/CircularQueue.ts`
- [Priority queue](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/PriorityQueue.ts): `src/dataStructures/PriorityQueue.ts`
- [Recent history stack](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/Stack.ts): `src/dataStructures/Stack.ts`
- [Song hash map](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/dataStructures/SongHashMap.ts): `src/dataStructures/SongHashMap.ts`

### Learning interface

- [Queue visualizer](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/CircularQueueVisualizer.tsx): `src/components/CircularQueueVisualizer.tsx`
- [DSA mode panel](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/DSAModePanel.tsx): `src/components/DSAModePanel.tsx`
- [Priority panel](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/PriorityQueuePanel.tsx): `src/components/PriorityQueuePanel.tsx`
- [Stack panel](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/StackPanel.tsx): `src/components/StackPanel.tsx`
- [Hash search panel](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/HashMapSearchPanel.tsx): `src/components/HashMapSearchPanel.tsx`
- [How-it-works guide](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/HowItWorksGuide.tsx): `src/components/HowItWorksGuide.tsx`
- [Complexity panel](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/ComplexityPanel.tsx): `src/components/ComplexityPanel.tsx`
- [Operation log](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/OperationLog.tsx): `src/components/OperationLog.tsx`
- [Presentation mode](https://github.com/kanishkkar2817/circular-music-palyer/blob/main/src/components/PresentationModeModal.tsx): `src/components/PresentationModeModal.tsx`

### Other components

- **Listener**

## Connections

- Listener → Player coordinator: uses player
- Player coordinator → Sample catalog: loads catalog (evidence: `src/App.tsx`)
- Player coordinator → Browser storage: loads and saves (evidence: `src/App.tsx`)
- Player coordinator → Circular queue: manages playback queue (evidence: `src/App.tsx`)
- Player coordinator → Priority queue: enqueues priority (evidence: `src/App.tsx`)
- Player coordinator → Song hash map: indexes songs (evidence: `src/App.tsx`)
- Player coordinator → Recent history stack: maintains history (evidence: `src/App.tsx`)
- Player coordinator → Synth audio service: controls audio (evidence: `src/App.tsx`)
- Player coordinator → Playback controls: renders controls (evidence: `src/App.tsx`)
- Playback controls → Synth audio service: reads playback data (evidence: `src/components/MusicPlayer.tsx`)
- Player coordinator → Add song modal: renders modal (evidence: `src/App.tsx`)
- Player coordinator → Playlist view: renders view (evidence: `src/App.tsx`)
- Player coordinator → Navigation: renders navigation (evidence: `src/App.tsx`)
- Player coordinator → Sidebar: renders sidebar (evidence: `src/App.tsx`)
- Player coordinator → Queue visualizer: renders visualizer (evidence: `src/App.tsx`)
- Player coordinator → DSA mode panel: renders DSA panel (evidence: `src/App.tsx`)
- Player coordinator → Priority panel: renders panel (evidence: `src/App.tsx`)
- Player coordinator → Stack panel: renders panel (evidence: `src/App.tsx`)
- Player coordinator → Hash search panel: renders search panel (evidence: `src/App.tsx`)
- Player coordinator → How-it-works guide: renders guide (evidence: `src/App.tsx`)
- Player coordinator → Complexity panel: renders panel (evidence: `src/App.tsx`)
- Player coordinator → Operation log: renders log (evidence: `src/App.tsx`)
- Player coordinator → Presentation mode: renders modal (evidence: `src/App.tsx`)
- Player coordinator → Toast notifications: renders notifications (evidence: `src/App.tsx`)
- Priority panel → Priority queue: reads queue (evidence: `src/components/PriorityQueuePanel.tsx`)
- Stack panel → Recent history stack: reads history (evidence: `src/components/StackPanel.tsx`)
