# ravish-ranjan/carvaan-desktop architecture

> Architecture diagram of the GitHub repository ravish-ranjan/carvaan-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravish-ranjan/carvaan-desktop
- Repository: https://github.com/ravish-ranjan/carvaan-desktop

## Overview

Sync Songs App is a hybrid desktop music-library manager: users import audio, review library size and settings, and prepare collections for Android-device synchronization. The React interface runs in a GTK/WebKit host and communicates with C++ features through a JSON protocol; SQLite repositories persist library and settings data. Playback is a separate UI capability. Device discovery and end-to-end synchronization remain in-progress, so their links to runtime actions are not asserted. Some subsystem relationships are documented or indexed but their implementation excerpts were not provided.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/App.tsx) (App shell), [`src/main.cpp`](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/main.cpp) (Application startup), [`src/webview/WebViewApp.cpp`](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/webview/WebViewApp.cpp) (WebKit host and protocol), [`src/core/Database.cpp`](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/Database.cpp) (SQLite database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_appui["App shell<br/>[App.tsx]"]
  node_libraryui["Library section<br/>[Library.tsx]"]
  node_deviceui["Devices and sync<br/>[Devices.tsx]"]
  node_settingsui["Settings section<br/>[Settings.tsx]"]
  node_playerui["Player section<br/>[Player.tsx]"]
  node_libbridge["Library bridge<br/>[libraryBridge.ts]"]
  node_configbridge["Configure bridge<br/>[configureBridge.ts]"]
  node_playerbridge["Player bridge<br/>[playerBridge.ts]"]
  node_stores["Frontend stores"]
end

subgraph group_backend["Desktop backend"]
  node_webview["WebKit host and protocol<br/>[WebViewApp.cpp]"]
  node_configurefeatures["Settings operations"]
  node_settingsrepo["Settings repository"]
  node_launcher["Application startup<br/>[main.cpp]"]
end

subgraph group_library["Library and storage"]
  node_libraryfeatures["Library operations"]
  node_manager["Library manager<br/>[LibraryManager.cpp]"]
  node_songrepo["Song repository<br/>[SongRepository.cpp]"]
  node_database[("SQLite database<br/>[Database.cpp]")]
end

subgraph group_device["Device sync"]
  node_adb["ADB operations<br/>[AdbManager.cpp]"]
  node_devicerepo["Device repository"]
end

subgraph group_playback["Playback"]
  node_audio["Audio engine<br/>[audioEngine.ts]"]
  node_playerfeatures["Playback operations<br/>[PlayerFeatures.cpp]"]
end

node_user(("Desktop user"))
node_picard["MusicBrainz Picard"]
node_android(("Android device"))

node_user -->|"uses"| node_appui
node_appui -->|"renders"| node_libraryui
node_appui -->|"renders"| node_deviceui
node_appui -->|"renders"| node_settingsui
node_appui -->|"renders"| node_playerui
node_appui -->|"initializes and requests"| node_libbridge
node_appui -->|"initializes and requests"| node_configbridge
node_appui -->|"initializes"| node_playerbridge
node_appui -->|"reads navigation"| node_stores
node_playerui -.->|"uses playback"| node_audio
node_launcher -->|"opens and initializes"| node_database
node_launcher -->|"constructs"| node_songrepo
node_launcher -->|"constructs"| node_settingsrepo
node_launcher -->|"constructs"| node_manager
node_launcher -->|"runs"| node_webview
node_manager -->|"reads and writes"| node_songrepo
node_songrepo -->|"persists records"| node_database
node_settingsrepo -->|"persists settings"| node_database
node_webview -.->|"dispatches messages"| node_libraryfeatures
node_webview -.->|"dispatches messages"| node_configurefeatures
node_webview -.->|"dispatches messages"| node_playerfeatures
node_libraryfeatures -.->|"uses library"| node_manager
node_libraryfeatures -.->|"opens new tracks"| node_picard
node_webview -.->|"may dispatch device actions"| node_adb
node_adb -.->|"manages device"| node_android
node_devicerepo -->|"stores device records"| node_database

click node_appui "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/App.tsx"
click node_libraryui "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Library.tsx"
click node_deviceui "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Devices.tsx"
click node_settingsui "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Settings.tsx"
click node_playerui "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Player.tsx"
click node_libbridge "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/libraryBridge.ts"
click node_configbridge "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/configureBridge.ts"
click node_playerbridge "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/playerBridge.ts"
click node_stores "https://github.com/ravish-ranjan/carvaan-desktop/tree/main/frontend/src/stores"
click node_audio "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/audioEngine.ts"
click node_webview "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/webview/WebViewApp.cpp"
click node_libraryfeatures "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/library/LibraryFeatures.cpp"
click node_configurefeatures "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/configure/ConfigureFeatures.cpp"
click node_playerfeatures "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/player/PlayerFeatures.cpp"
click node_adb "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/adb/AdbManager.cpp"
click node_manager "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/LibraryManager.cpp"
click node_songrepo "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/SongRepository.cpp"
click node_settingsrepo "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/SettingsRepository.cpp"
click node_devicerepo "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/AdbDeviceRepository.cpp"
click node_database "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/Database.cpp"
click node_launcher "https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/main.cpp"

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_appui,node_libraryui,node_deviceui,node_settingsui,node_playerui,node_libbridge,node_configbridge,node_playerbridge,node_stores,node_user toneBlue
class node_webview,node_configurefeatures,node_settingsrepo,node_launcher toneAmber
class node_libraryfeatures,node_manager,node_songrepo,node_database toneMint
class node_adb,node_devicerepo toneRose
class node_audio,node_playerfeatures,node_picard,node_android toneIndigo
```

## Components

### Frontend

- [App shell](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Library section](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Library.tsx): `frontend/src/components/sections/Library.tsx`
- [Devices and sync](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Devices.tsx): `frontend/src/components/sections/Devices.tsx`
- [Settings section](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Settings.tsx): `frontend/src/components/sections/Settings.tsx`
- [Player section](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/components/sections/Player.tsx): `frontend/src/components/sections/Player.tsx`
- [Library bridge](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/libraryBridge.ts): `frontend/src/lib/libraryBridge.ts`
- [Configure bridge](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/configureBridge.ts): `frontend/src/lib/configureBridge.ts`
- [Player bridge](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/playerBridge.ts): `frontend/src/lib/playerBridge.ts`
- [Frontend stores](https://github.com/ravish-ranjan/carvaan-desktop/tree/main/frontend/src/stores): `frontend/src/stores`

### Desktop backend

- [WebKit host and protocol](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/webview/WebViewApp.cpp): `src/webview/WebViewApp.cpp`
- [Settings operations](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/configure/ConfigureFeatures.cpp): `src/features/configure/ConfigureFeatures.cpp`
- [Settings repository](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/SettingsRepository.cpp): `src/core/SettingsRepository.cpp`
- [Application startup](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/main.cpp): `src/main.cpp`

### Library and storage

- [Library operations](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/library/LibraryFeatures.cpp): `src/features/library/LibraryFeatures.cpp`
- [Library manager](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/LibraryManager.cpp): `src/core/LibraryManager.cpp`
- [Song repository](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/SongRepository.cpp): `src/core/SongRepository.cpp`
- [SQLite database](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/Database.cpp): `src/core/Database.cpp`

### Device sync

- [ADB operations](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/adb/AdbManager.cpp): `src/features/adb/AdbManager.cpp`
- [Device repository](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/core/AdbDeviceRepository.cpp): `src/core/AdbDeviceRepository.cpp`

### Playback

- [Audio engine](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/frontend/src/lib/audioEngine.ts): `frontend/src/lib/audioEngine.ts`
- [Playback operations](https://github.com/ravish-ranjan/carvaan-desktop/blob/main/src/features/player/PlayerFeatures.cpp): `src/features/player/PlayerFeatures.cpp`

### Other components

- **Desktop user**
- **MusicBrainz Picard**
- **Android device**

## Connections

- Desktop user → App shell: uses (evidence: `README.md`)
- App shell → Library section: renders (evidence: `frontend/src/App.tsx`)
- App shell → Devices and sync: renders (evidence: `frontend/src/App.tsx`)
- App shell → Settings section: renders (evidence: `frontend/src/App.tsx`)
- App shell → Player section: renders (evidence: `frontend/src/App.tsx`)
- App shell → Library bridge: initializes and requests (evidence: `frontend/src/App.tsx`)
- App shell → Configure bridge: initializes and requests (evidence: `frontend/src/App.tsx`)
- App shell → Player bridge: initializes (evidence: `frontend/src/App.tsx`)
- App shell → Frontend stores: reads navigation (evidence: `frontend/src/App.tsx`)
- Player section → Audio engine: uses playback
- Application startup → SQLite database: opens and initializes (evidence: `src/main.cpp`)
- Application startup → Song repository: constructs (evidence: `src/main.cpp`)
- Application startup → Settings repository: constructs (evidence: `src/main.cpp`)
- Application startup → Library manager: constructs (evidence: `src/main.cpp`)
- Application startup → WebKit host and protocol: runs (evidence: `src/main.cpp`)
- Library manager → Song repository: reads and writes (evidence: `src/core/LibraryManager.cpp`)
- Song repository → SQLite database: persists records (evidence: `src/core/SongRepository.cpp`)
- Settings repository → SQLite database: persists settings
- WebKit host and protocol → Library operations: dispatches messages
- WebKit host and protocol → Settings operations: dispatches messages
- WebKit host and protocol → Playback operations: dispatches messages
- Library operations → Library manager: uses library
- Library operations → MusicBrainz Picard: opens new tracks (evidence: `README.md`)
- WebKit host and protocol → ADB operations: may dispatch device actions
- ADB operations → Android device: manages device (evidence: `README.md`)
- Device repository → SQLite database: stores device records
