# cosmicandrew/v0-music-handpan-dashboard architecture

> Architecture diagram of the GitHub repository cosmicandrew/v0-music-handpan-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cosmicandrew/v0-music-handpan-dashboard
- Repository: https://github.com/cosmicandrew/v0-music-handpan-dashboard

## Overview

1. This is a Next.js App Router frontend, deployed from a Vercel/v0 workflow. The top-level `app/` directory defines the routed shell (`layout.tsx`, `page.tsx`, and a `debug/` route), while most product behavior lives in reusable React components under `components/`.

2. The application is centered on a music/handpan experience rather than a generic dashboard. The main UI pieces are `handpan-player`, `interactive-handpan`, `song-library`, `recently-played`, `devotions`, and `dashboard`, which together suggest a browsing + playback + interaction flow around curated audio content.

3. Playback is isolated in `lib/audio-engine.ts`. That module is the likely boundary for audio state, playback control, timing, and any browser audio APIs. UI components consume that engine rather than implementing audio logic directly, which keeps rendering separate from sound behavior.

4. Content/data for the instrument experience appears to be local and curated. `data/songLibrary.ts` and `lib/handpan-data.ts` likely provide the song catalog, metadata, and handpan-related domain data used by the library, player, and interactive surfaces.

5. The app has a strong offline-first layer. `public/sw.js`, `public/offline.html`, and `public/manifest.json` indicate PWA support, with a service worker handling caching/offline fallback and the manifest enabling installable app behavior. `components/offline-indicator.tsx` shows the UI reflects connectivity state.

6. Caching is handled explicitly in code, not just by the service worker. Both `lib/cache-manager.ts` and `utils/cacheManager.ts` exist, suggesting a cache abstraction used by the app for downloaded assets, recent items, or offline playback data. This is a distinct infrastructure boundary from the main UI and audio engine.

7. Gesture-based interaction is a first-class input path. `hooks/use-gestures.ts`, `hooks/useGestures.ts`, and `hooks/usePullToRefresh.ts` indicate touch/mobile interactions such as swipes, drag gestures, or pull-to-refresh. These hooks likely feed the interactive handpan and mobile-friendly navigation patterns.

8. Theme and personalization are handled as UI state rather than app-wide infrastructure. `hooks/use-theme.ts`, `hooks/useTheme.ts`, and `components/theme-provider.tsx` suggest theme selection persists across sessions and is applied through a provider at the app shell level.

9. The component layer is organized around reusable primitives plus feature modules. `components/ui/` contains the design-system building blocks (`button`, `card`, `input`, `slider`, `badge`), while feature components compose them into domain views like settings, navigation, export progress, and dashboards.

10. There is a clear separation between route shell and feature content. `app/layout.tsx` likely establishes global providers and shared styling, `app/globals.css` and `styles/globals.css` define base CSS, and `components/navigation.tsx` supplies app-wide navigation rather than route-local controls.

11. The `public/` folder contains deploy-time assets that shape runtime behavior. In addition to PWA files, this is where browser-accessible offline and worker scripts live, which means service-worker registration and asset caching are part of the production runtime, not a server-side concern.

12. The `debug/` page and `export-progress` component suggest operational or authoring workflows built into the UI. These pieces are likely used for inspecting playback/export state or validating behavior during development, and they sit alongside end-user features rather than in a separate admin app.

13. Overall, the architecture is a client-heavy, static-deployable Next.js app with three major boundaries: routed UI in `app/`, domain/audio logic in `lib/` and `data/`, and offline/PWA runtime behavior in `public/` plus cache hooks/utilities. The main data flow is: curated song/handpan data and UI state feed the player and interactive components, which in turn drive the audio engine and caching/offline layers.

Main entry points: [`components/dashboard.tsx`](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/dashboard.tsx) (Dashboard), [`app/layout.tsx`](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/layout.tsx) (Layout), [`components/interactive-handpan.tsx`](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/interactive-handpan.tsx) (Interactive Handpan), [`app/page.tsx`](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/page.tsx) (Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Route Shell"]
  node_app_layout["Layout<br/>app shell<br/>[layout.tsx]"]
  node_app_page["Home<br/>route<br/>[page.tsx]"]
  node_app_debug["Debug<br/>route<br/>[page.tsx]"]
  node_app_css["Global CSS<br/>style<br/>[globals.css]"]
  node_styles_css["Globals CSS<br/>style<br/>[globals.css]"]
end

subgraph group_features["Feature UI"]
  node_dashboard["Dashboard<br/>feature view<br/>[dashboard.tsx]"]
  node_player["Handpan Player<br/>playback ui<br/>[handpan-player.tsx]"]
  node_interactive(("Interactive Handpan<br/>gesture ui"))
  node_library["Song Library<br/>browse ui<br/>[song-library.tsx]"]
  node_recent["Recently Played<br/>history ui"]
  node_devotions["Devotions<br/>content ui<br/>[devotions.tsx]"]
  node_settings["Settings<br/>preferences ui<br/>[settings.tsx]"]
  node_export_progress["Export Progress<br/>workflow ui"]
end

subgraph group_domain["Domain Data"]
  node_audio_engine[("Audio Engine<br/>audio core<br/>[audio-engine.ts]")]
  node_handpan_data["Handpan Data<br/>domain model<br/>[handpan-data.ts]"]
  node_song_library_data["Song Library Data<br/>catalog data<br/>[songLibrary.ts]"]
end

subgraph group_runtime["Offline Runtime"]
  node_cache_manager_lib[("Cache Manager<br/>cache core<br/>[cache-manager.ts]")]
  node_cache_manager_util[("Cache Util<br/>cache helper<br/>[cacheManager.ts]")]
  node_use_offline(("Offline Hook<br/>[use-offline.ts]"))
  node_use_gestures(("Gestures Hook<br/>[use-gestures.ts]"))
  node_use_gestures_alt(("Gestures Hook 2<br/>[useGestures.ts]"))
  node_use_pull_refresh(("Pull Refresh<br/>hook"))
  node_use_theme(("Theme Hook<br/>[use-theme.ts]"))
  node_use_theme_alt(("Theme Hook 2<br/>[useTheme.ts]"))
  node_public_sw["Service Worker<br/>pwa asset<br/>[sw.js]"]
  node_public_offline["Offline Page<br/>fallback<br/>[offline.html]"]
  node_public_manifest["Manifest<br/>[manifest.json]"]
end

subgraph group_shared["Shared UI"]
  node_theme_provider["Theme Provider<br/>[theme-provider.tsx]"]
  node_navigation["Navigation<br/>[navigation.tsx]"]
  node_offline_indicator(("Offline State<br/>status ui"))
  node_ui_primitives["UI Primitives<br/>design system<br/>[button.tsx]"]
end

node_app_layout -->|"wraps"| node_theme_provider
node_app_layout -->|"includes"| node_navigation
node_app_layout -->|"loads"| node_app_css
node_app_layout -->|"loads"| node_styles_css
node_app_page -->|"renders"| node_dashboard
node_app_page -->|"renders"| node_player
node_app_page -->|"renders"| node_library
node_app_debug -->|"renders"| node_export_progress
node_dashboard -->|"coordinates"| node_player
node_dashboard -->|"shows"| node_recent
node_dashboard -->|"shows"| node_devotions
node_player -->|"controls"| node_audio_engine
node_interactive -->|"drives"| node_audio_engine
node_interactive -->|"uses"| node_use_gestures
node_interactive -->|"uses"| node_use_gestures_alt
node_interactive -->|"uses"| node_use_pull_refresh
node_library -->|"reads"| node_song_library_data
node_library -->|"starts"| node_audio_engine
node_recent -->|"reads"| node_cache_manager_lib
node_devotions -->|"uses"| node_handpan_data
node_settings -->|"uses"| node_use_theme
node_settings -->|"uses"| node_use_theme_alt
node_offline_indicator -->|"uses"| node_use_offline
node_use_offline -->|"coordinates"| node_cache_manager_lib
node_cache_manager_lib -.->|"shares"| node_cache_manager_util
node_public_sw -->|"falls back to"| node_public_offline
node_public_sw -->|"supports"| node_public_manifest
node_public_sw -->|"caches"| node_cache_manager_lib
node_theme_provider -->|"provides"| node_use_theme
node_navigation -->|"routes to"| node_app_page
node_navigation -->|"routes to"| node_app_debug
node_ui_primitives -->|"supports"| node_dashboard
node_ui_primitives -->|"supports"| node_player
node_ui_primitives -->|"supports"| node_library

click node_app_layout "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/layout.tsx"
click node_app_page "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/page.tsx"
click node_app_debug "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/debug/page.tsx"
click node_app_css "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/globals.css"
click node_styles_css "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/styles/globals.css"
click node_theme_provider "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/theme-provider.tsx"
click node_navigation "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/navigation.tsx"
click node_offline_indicator "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/offline-indicator.tsx"
click node_ui_primitives "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/ui/button.tsx"
click node_dashboard "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/dashboard.tsx"
click node_player "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/handpan-player.tsx"
click node_interactive "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/interactive-handpan.tsx"
click node_library "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/song-library.tsx"
click node_recent "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/recently-played.tsx"
click node_devotions "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/devotions.tsx"
click node_settings "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/settings.tsx"
click node_export_progress "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/export-progress.tsx"
click node_audio_engine "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/lib/audio-engine.ts"
click node_handpan_data "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/lib/handpan-data.ts"
click node_song_library_data "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/data/songLibrary.ts"
click node_cache_manager_lib "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/lib/cache-manager.ts"
click node_cache_manager_util "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/utils/cacheManager.ts"
click node_use_offline "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/use-offline.ts"
click node_use_gestures "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/use-gestures.ts"
click node_use_gestures_alt "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/useGestures.ts"
click node_use_pull_refresh "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/usePullToRefresh.ts"
click node_use_theme "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/use-theme.ts"
click node_use_theme_alt "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/useTheme.ts"
click node_public_sw "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/public/sw.js"
click node_public_offline "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/public/offline.html"
click node_public_manifest "https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/public/manifest.json"

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_layout,node_app_page,node_app_debug,node_app_css,node_styles_css toneBlue
class node_dashboard,node_player,node_interactive,node_library,node_recent,node_devotions,node_settings,node_export_progress toneAmber
class node_audio_engine,node_handpan_data,node_song_library_data toneMint
class node_cache_manager_lib,node_cache_manager_util,node_use_offline,node_use_gestures,node_use_gestures_alt,node_use_pull_refresh,node_use_theme,node_use_theme_alt,node_public_sw,node_public_offline,node_public_manifest toneRose
class node_theme_provider,node_navigation,node_offline_indicator,node_ui_primitives toneIndigo
```

## Components

### Route Shell

Next.js App Router entrypoints and global styling

- [Layout](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/layout.tsx): app shell · Root app shell and global providers · `app/layout.tsx`
- [Home](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/page.tsx): route · Primary landing route · `app/page.tsx`
- [Debug](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/debug/page.tsx): route · Debug/inspection route · `app/debug/page.tsx`
- [Global CSS](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/app/globals.css): style · App-wide styling entrypoint · `app/globals.css`
- [Globals CSS](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/styles/globals.css): style · Shared base styles · `styles/globals.css`

### Feature UI

Reusable domain components for playback, browsing, and interaction

- [Dashboard](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/dashboard.tsx): feature view · Primary overview and entry surface · `components/dashboard.tsx`
- [Handpan Player](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/handpan-player.tsx): playback ui · Main playback controls and current track view · `components/handpan-player.tsx`
- [Interactive Handpan](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/interactive-handpan.tsx): gesture ui · Touch-driven instrument interaction · `components/interactive-handpan.tsx`
- [Song Library](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/song-library.tsx): browse ui · Catalog browsing and selection · `components/song-library.tsx`
- [Recently Played](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/recently-played.tsx): history ui · Recent listening history · `components/recently-played.tsx`
- [Devotions](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/devotions.tsx): content ui · Curated devotional content surface · `components/devotions.tsx`
- [Settings](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/settings.tsx): preferences ui · User preferences and controls · `components/settings.tsx`
- [Export Progress](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/export-progress.tsx): workflow ui · Export and processing status · `components/export-progress.tsx`

### Domain Data

Curated music and handpan data plus playback logic

- [Audio Engine](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/lib/audio-engine.ts): audio core · Playback state, timing, and browser audio boundary · `lib/audio-engine.ts`
- [Handpan Data](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/lib/handpan-data.ts): domain model · Instrument-specific domain data · `lib/handpan-data.ts`
- [Song Library Data](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/data/songLibrary.ts): catalog data · Curated song metadata and library content · `data/songLibrary.ts`

### Offline Runtime

PWA assets, caching, and connectivity behavior

- [Cache Manager](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/lib/cache-manager.ts): cache core · App cache abstraction used by features · `lib/cache-manager.ts`
- [Cache Util](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/utils/cacheManager.ts): cache helper · Secondary cache manager implementation · `utils/cacheManager.ts`
- [Offline Hook](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/use-offline.ts): hook · Connectivity/offline state integration · `hooks/use-offline.ts`
- [Gestures Hook](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/use-gestures.ts): hook · Touch and gesture interaction handling · `hooks/use-gestures.ts`
- [Gestures Hook 2](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/useGestures.ts): hook · Alternate gesture hook entrypoint · `hooks/useGestures.ts`
- [Pull Refresh](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/usePullToRefresh.ts): hook · Pull-to-refresh interaction · `hooks/usePullToRefresh.ts`
- [Theme Hook](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/use-theme.ts): hook · Theme selection and persistence · `hooks/use-theme.ts`
- [Theme Hook 2](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/hooks/useTheme.ts): hook · Alternate theme hook entrypoint · `hooks/useTheme.ts`
- [Service Worker](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/public/sw.js): pwa asset · Offline caching and runtime control · `public/sw.js`
- [Offline Page](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/public/offline.html): fallback · Browser fallback when offline · `public/offline.html`
- [Manifest](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/public/manifest.json): pwa manifest · Installable app metadata · `public/manifest.json`

### Shared UI

Design-system primitives and cross-cutting providers

- [Theme Provider](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/theme-provider.tsx): provider · Persists and applies theme state · `components/theme-provider.tsx`
- [Navigation](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/navigation.tsx): nav · App-wide navigation controls · `components/navigation.tsx`
- [Offline State](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/offline-indicator.tsx): status ui · Connectivity and offline feedback · `components/offline-indicator.tsx`
- [UI Primitives](https://github.com/cosmicandrew/v0-music-handpan-dashboard/blob/main/components/ui/button.tsx): design system · Buttons, cards, inputs, sliders, badges · `components/ui/button.tsx`

## Connections

- Layout → Theme Provider: wraps · Root shell installs theme and global providers
- Layout → Navigation: includes · Shared navigation is part of the app shell
- Layout → Global CSS: loads · Global app styling is applied from the shell
- Layout → Globals CSS: loads · Shared base styles are loaded globally
- Home → Dashboard: renders · Home route composes the main dashboard experience
- Home → Handpan Player: renders · Primary route exposes playback controls
- Home → Song Library: renders · Primary route shows the curated catalog
- Debug → Export Progress: renders · Debug route surfaces operational state
- Dashboard → Handpan Player: coordinates · Dashboard ties browsing to playback
- Dashboard → Recently Played: shows · Dashboard includes listening history
- Dashboard → Devotions: shows · Dashboard includes devotional content
- Handpan Player → Audio Engine: controls · Player delegates playback to the audio boundary
- Interactive Handpan → Audio Engine: drives · Gesture interactions trigger audio behavior
- Interactive Handpan → Gestures Hook: uses · Primary gesture handling hook
- Interactive Handpan → Gestures Hook 2: uses · Secondary gesture hook entrypoint
- Interactive Handpan → Pull Refresh: uses · Supports mobile pull-to-refresh behavior
- Song Library → Song Library Data: reads · Library is powered by curated catalog data
- Song Library → Audio Engine: starts · Selecting a song flows into playback
- Recently Played → Cache Manager: reads · Recent items likely persist via cache abstraction
- Devotions → Handpan Data: uses · Content surface is grounded in handpan domain data
- Settings → Theme Hook: uses · Settings manages theme preference
- Settings → Theme Hook 2: uses · Alternate theme hook entrypoint
- Offline State → Offline Hook: uses · UI reflects offline/connectivity state
- Offline Hook → Cache Manager: coordinates · Offline state interacts with cache behavior
- Cache Manager → Cache Util: shares · Two cache implementations form the cache boundary
- Service Worker → Offline Page: falls back to · Service worker serves the offline page when needed
- Service Worker → Manifest: supports · PWA runtime is paired with install metadata
- Service Worker → Cache Manager: caches · Offline runtime aligns with app cache management
- Theme Provider → Theme Hook: provides · Provider and hook share theme state
- Navigation → Home: routes to · Navigation links connect the shell to content routes
- Navigation → Debug: routes to · Navigation includes debug access
- UI Primitives → Dashboard: supports · Feature views are built from shared primitives
- UI Primitives → Handpan Player: supports · Playback UI uses shared components
- UI Primitives → Song Library: supports · Browse UI uses shared components
