# brunovieira003/groov-web architecture

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

- Interactive diagram: https://gitdiagram.com/brunovieira003/groov-web
- Repository: https://github.com/brunovieira003/groov-web

## Overview

Groov Web is a Svelte music-library and playback client for groov-api. Users browse and search songs, artists, albums, and playlists; select music for playback; and manage library tasks through settings. Route server loaders/actions fetch catalog data and submit mutations to the API, while the client exposes playback, lyrics, queue, and task-feedback features. The sampled server routes establish several API connections; playback wiring and most component-to-store relationships were not sampled, so those uncertain links are omitted. README-planned features are not represented as implemented components.

Main entry points: [`src/routes/settings/library/+page.server.ts`](https://github.com/brunovieira003/groov-web/blob/master/src/routes/settings/library/%2Bpage.server.ts) (Library Settings), [`src/routes/playlists/+page.server.ts`](https://github.com/brunovieira003/groov-web/blob/master/src/routes/playlists/%2Bpage.server.ts) (Playlist Catalog), [`src/routes/playlists/[playlistId]/+page.server.ts`](https://github.com/brunovieira003/groov-web/blob/master/src/routes/playlists/%5BplaylistId%5D/%2Bpage.server.ts) (Playlist Detail), [`src/routes/+page.server.ts`](https://github.com/brunovieira003/groov-web/blob/master/src/routes/%2Bpage.server.ts) (Song Browse)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Music Catalog"]
  node_home["Song Browse<br/>[+page.server.ts]"]
  node_search["Search<br/>[+page.server.ts]"]
  node_artists["Artist Catalog<br/>[+page.server.ts]"]
  node_artist["Artist Detail<br/>[+page.server.ts]"]
  node_albums["Album Catalog<br/>[+page.server.ts]"]
  node_album["Album Detail<br/>[+page.server.ts]"]
  node_playlists["Playlist Catalog<br/>[+page.server.ts]"]
  node_playlist["Playlist Detail<br/>[+page.server.ts]"]
end

subgraph group_playback["Playback Experience"]
  node_player["Player Controls"]
  node_fullplayer["Full Player<br/>[full-player.svelte]"]
  node_playing["Playing View<br/>[+page.svelte]"]
  node_lyrics["Lyrics View<br/>[+page.svelte]"]
  node_cassete["Cassette View<br/>[+page.svelte]"]
end

subgraph group_library["Library Management"]
  node_settings["Library Settings<br/>[+page.server.ts]"]
  node_upload["Upload Controls"]
  node_taskview["Task Feedback<br/>[task-list.svelte]"]
end

subgraph group_runtime["Client State"]
  node_playerstate["Player State<br/>[player.ts]"]
  node_queue["Playback Queue<br/>[queue.ts]"]
  node_taskstate["Task Tracking<br/>[runningTasks.ts]"]
  node_proxy["API Proxy<br/>[+server.ts]"]
end

node_listener(("Listener"))
node_api["groov-api"]
node_tasks["Task Event API"]

node_listener -->|"browses"| node_home
node_listener -->|"searches"| node_search
node_listener -->|"browses"| node_artists
node_listener -->|"browses"| node_albums
node_listener -->|"browses"| node_playlists
node_listener -->|"opens"| node_playing
node_listener -->|"opens"| node_lyrics
node_listener -->|"opens"| node_cassete
node_listener -->|"manages library"| node_settings
node_home -->|"fetches songs"| node_api
node_search -->|"queries"| node_api
node_artists -->|"fetches artists"| node_api
node_artist -->|"fetches artist"| node_api
node_albums -->|"fetches albums"| node_api
node_album -->|"fetches album"| node_api
node_playlists -->|"fetches playlists"| node_api
node_playlists -->|"creates playlist"| node_api
node_playlist -->|"fetches playlist"| node_api
node_playlist -->|"updates cover"| node_api
node_settings -->|"uploads and scans"| node_api
node_settings -->|"prunes library"| node_api
node_upload -->|"submits upload"| node_settings
node_taskstate -->|"subscribes events"| node_tasks
node_listener -->|"sends API request"| node_proxy
node_proxy -->|"forwards request"| node_api

click node_home "https://github.com/brunovieira003/groov-web/blob/master/src/routes/%2Bpage.server.ts"
click node_search "https://github.com/brunovieira003/groov-web/blob/master/src/routes/search/%2Bpage.server.ts"
click node_artists "https://github.com/brunovieira003/groov-web/blob/master/src/routes/artists/%2Bpage.server.ts"
click node_artist "https://github.com/brunovieira003/groov-web/blob/master/src/routes/artists/%5BartistId%5D/%2Bpage.server.ts"
click node_albums "https://github.com/brunovieira003/groov-web/blob/master/src/routes/albums/%2Bpage.server.ts"
click node_album "https://github.com/brunovieira003/groov-web/blob/master/src/routes/albums/%5BalbumId%5D/%2Bpage.server.ts"
click node_playlists "https://github.com/brunovieira003/groov-web/blob/master/src/routes/playlists/%2Bpage.server.ts"
click node_playlist "https://github.com/brunovieira003/groov-web/blob/master/src/routes/playlists/%5BplaylistId%5D/%2Bpage.server.ts"
click node_player "https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/player/default-player.svelte"
click node_fullplayer "https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/player/full-player.svelte"
click node_playing "https://github.com/brunovieira003/groov-web/blob/master/src/routes/playing/%2Bpage.svelte"
click node_lyrics "https://github.com/brunovieira003/groov-web/blob/master/src/routes/lyrics/%2Bpage.svelte"
click node_cassete "https://github.com/brunovieira003/groov-web/blob/master/src/routes/cassete/%2Bpage.svelte"
click node_playerstate "https://github.com/brunovieira003/groov-web/blob/master/src/lib/stores/player.ts"
click node_queue "https://github.com/brunovieira003/groov-web/blob/master/src/lib/stores/queue.ts"
click node_settings "https://github.com/brunovieira003/groov-web/blob/master/src/routes/settings/library/%2Bpage.server.ts"
click node_upload "https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/forms/upload-button.svelte"
click node_taskview "https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/task-list.svelte"
click node_taskstate "https://github.com/brunovieira003/groov-web/blob/master/src/lib/stores/runningTasks.ts"
click node_proxy "https://github.com/brunovieira003/groov-web/blob/master/src/routes/api/%5B...path%5D/%2Bserver.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_home,node_search,node_artists,node_artist,node_albums,node_album,node_playlists,node_playlist toneBlue
class node_player,node_fullplayer,node_playing,node_lyrics,node_cassete toneAmber
class node_settings,node_upload,node_taskview,node_api toneMint
class node_playerstate,node_queue,node_taskstate,node_proxy,node_tasks toneRose
class node_listener toneIndigo
```

## Components

### Music Catalog

- [Song Browse](https://github.com/brunovieira003/groov-web/blob/master/src/routes/%2Bpage.server.ts): `src/routes/+page.server.ts`
- [Search](https://github.com/brunovieira003/groov-web/blob/master/src/routes/search/%2Bpage.server.ts): `src/routes/search/+page.server.ts`
- [Artist Catalog](https://github.com/brunovieira003/groov-web/blob/master/src/routes/artists/%2Bpage.server.ts): `src/routes/artists/+page.server.ts`
- [Artist Detail](https://github.com/brunovieira003/groov-web/blob/master/src/routes/artists/%5BartistId%5D/%2Bpage.server.ts): `src/routes/artists/[artistId]/+page.server.ts`
- [Album Catalog](https://github.com/brunovieira003/groov-web/blob/master/src/routes/albums/%2Bpage.server.ts): `src/routes/albums/+page.server.ts`
- [Album Detail](https://github.com/brunovieira003/groov-web/blob/master/src/routes/albums/%5BalbumId%5D/%2Bpage.server.ts): `src/routes/albums/[albumId]/+page.server.ts`
- [Playlist Catalog](https://github.com/brunovieira003/groov-web/blob/master/src/routes/playlists/%2Bpage.server.ts): `src/routes/playlists/+page.server.ts`
- [Playlist Detail](https://github.com/brunovieira003/groov-web/blob/master/src/routes/playlists/%5BplaylistId%5D/%2Bpage.server.ts): `src/routes/playlists/[playlistId]/+page.server.ts`

### Playback Experience

- [Player Controls](https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/player/default-player.svelte): `src/lib/components/player/default-player.svelte`
- [Full Player](https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/player/full-player.svelte): `src/lib/components/player/full-player.svelte`
- [Playing View](https://github.com/brunovieira003/groov-web/blob/master/src/routes/playing/%2Bpage.svelte): `src/routes/playing/+page.svelte`
- [Lyrics View](https://github.com/brunovieira003/groov-web/blob/master/src/routes/lyrics/%2Bpage.svelte): `src/routes/lyrics/+page.svelte`
- [Cassette View](https://github.com/brunovieira003/groov-web/blob/master/src/routes/cassete/%2Bpage.svelte): `src/routes/cassete/+page.svelte`

### Library Management

- [Library Settings](https://github.com/brunovieira003/groov-web/blob/master/src/routes/settings/library/%2Bpage.server.ts): `src/routes/settings/library/+page.server.ts`
- [Upload Controls](https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/forms/upload-button.svelte): `src/lib/components/forms/upload-button.svelte`
- [Task Feedback](https://github.com/brunovieira003/groov-web/blob/master/src/lib/components/task-list.svelte): `src/lib/components/task-list.svelte`

### Client State

- [Player State](https://github.com/brunovieira003/groov-web/blob/master/src/lib/stores/player.ts): `src/lib/stores/player.ts`
- [Playback Queue](https://github.com/brunovieira003/groov-web/blob/master/src/lib/stores/queue.ts): `src/lib/stores/queue.ts`
- [Task Tracking](https://github.com/brunovieira003/groov-web/blob/master/src/lib/stores/runningTasks.ts): `src/lib/stores/runningTasks.ts`
- [API Proxy](https://github.com/brunovieira003/groov-web/blob/master/src/routes/api/%5B...path%5D/%2Bserver.ts): `src/routes/api/[...path]/+server.ts`

### Other components

- **Listener**
- **groov-api**
- **Task Event API**

## Connections

- Listener → Song Browse: browses
- Listener → Search: searches
- Listener → Artist Catalog: browses
- Listener → Album Catalog: browses
- Listener → Playlist Catalog: browses
- Listener → Playing View: opens
- Listener → Lyrics View: opens
- Listener → Cassette View: opens
- Listener → Library Settings: manages library
- Song Browse → groov-api: fetches songs
- Search → groov-api: queries
- Artist Catalog → groov-api: fetches artists
- Artist Detail → groov-api: fetches artist
- Album Catalog → groov-api: fetches albums
- Album Detail → groov-api: fetches album
- Playlist Catalog → groov-api: fetches playlists
- Playlist Catalog → groov-api: creates playlist
- Playlist Detail → groov-api: fetches playlist
- Playlist Detail → groov-api: updates cover
- Library Settings → groov-api: uploads and scans
- Library Settings → groov-api: prunes library
- Upload Controls → Library Settings: submits upload
- Task Tracking → Task Event API: subscribes events
- Listener → API Proxy: sends API request
- API Proxy → groov-api: forwards request