# brunovieira003/groov-api architecture

> Architecture diagram of the GitHub repository brunovieira003/groov-api, 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-api
- Repository: https://github.com/brunovieira003/groov-api

## Overview

Groov API is a backend for a music player. Its principal workflow accepts uploaded audio or a folder-scan request, queues file processing, and exposes the resulting music library through song, artist, album, playlist, and search endpoints. Other major capabilities include streaming audio and cover art, lyrics, playlist editing, and maintenance tasks. The sampled controllers and services support the request-to-service links shown; worker internals and several service implementations were not sampled, so uncertain processing links are omitted.

Main entry points: [`src/index.ts`](https://github.com/brunovieira003/groov-api/blob/master/src/index.ts) (HTTP application), [`src/resources/tools/controller.ts`](https://github.com/brunovieira003/groov-api/blob/master/src/resources/tools/controller.ts) (Search routes), [`src/resources/song/service.ts`](https://github.com/brunovieira003/groov-api/blob/master/src/resources/song/service.ts) (Song service), [`src/database/index.ts`](https://github.com/brunovieira003/groov-api/blob/master/src/database/index.ts) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["HTTP application<br/>[index.ts]"]
  node_songs_api["Song routes<br/>[controller.ts]"]
  node_artists_api["Artist routes<br/>[controller.ts]"]
  node_albums_api["Album routes<br/>[controller.ts]"]
  node_playlists_api["Playlist routes<br/>[controller.ts]"]
  node_tasks_api["Task routes<br/>[controller.ts]"]
  node_tools_api["Search routes<br/>[controller.ts]"]
end

subgraph group_library["Music library"]
  node_songs["Song service<br/>[service.ts]"]
  node_artists["Artist service<br/>[service.ts]"]
  node_albums["Album service<br/>[service.ts]"]
  node_playlists["Playlist service<br/>[service.ts]"]
end

subgraph group_tasks["Ingestion and tasks"]
  node_tasks["Task service<br/>[service.ts]"]
  node_scan_cli["Scan command<br/>[scan.ts]"]
  node_read_queue["File read queue<br/>[read-file.ts]"]
  node_prune_queues["Prune queues"]
end

subgraph group_data["Persistence and files"]
  node_db_client["Database access<br/>[index.ts]"]
  node_db_schema["Music schema<br/>[schema.ts]"]
  node_media_files[("Audio and images<br/>[constants.ts]")]
end

node_client(("Player client"))

node_client -->|"sends requests"| node_app
node_app -->|"dispatches"| node_songs_api
node_app -->|"dispatches"| node_artists_api
node_app -->|"dispatches"| node_albums_api
node_app -->|"dispatches"| node_playlists_api
node_app -->|"dispatches"| node_tasks_api
node_app -->|"dispatches"| node_tools_api
node_songs_api -->|"calls"| node_songs
node_artists_api -->|"calls"| node_artists
node_albums_api -->|"calls"| node_albums
node_playlists_api -->|"calls"| node_playlists
node_tasks_api -->|"calls"| node_tasks
node_tools_api -->|"searches"| node_songs
node_tools_api -->|"searches"| node_artists
node_tools_api -->|"searches"| node_albums
node_tools_api -->|"searches"| node_playlists
node_songs_api -->|"enqueues file"| node_read_queue
node_tasks -->|"enqueues scan"| node_read_queue
node_tasks -->|"enqueues pruning"| node_prune_queues
node_songs -->|"queries"| node_db_client
node_artists -->|"queries"| node_db_client
node_albums -->|"queries"| node_db_client
node_playlists -->|"queries"| node_db_client
node_db_client -->|"uses schema"| node_db_schema
node_songs -->|"reads audio and lyrics"| node_media_files
node_songs -->|"reads covers"| node_media_files
node_playlists -->|"reads and writes covers"| node_media_files
node_artists -->|"reads covers"| node_media_files
node_albums -->|"reads covers"| node_media_files

click node_app "https://github.com/brunovieira003/groov-api/blob/master/src/index.ts"
click node_songs_api "https://github.com/brunovieira003/groov-api/blob/master/src/resources/song/controller.ts"
click node_artists_api "https://github.com/brunovieira003/groov-api/blob/master/src/resources/artists/controller.ts"
click node_albums_api "https://github.com/brunovieira003/groov-api/blob/master/src/resources/albums/controller.ts"
click node_playlists_api "https://github.com/brunovieira003/groov-api/blob/master/src/resources/playlists/controller.ts"
click node_tasks_api "https://github.com/brunovieira003/groov-api/blob/master/src/resources/tasks/controller.ts"
click node_tools_api "https://github.com/brunovieira003/groov-api/blob/master/src/resources/tools/controller.ts"
click node_songs "https://github.com/brunovieira003/groov-api/blob/master/src/resources/song/service.ts"
click node_artists "https://github.com/brunovieira003/groov-api/blob/master/src/resources/artists/service.ts"
click node_albums "https://github.com/brunovieira003/groov-api/blob/master/src/resources/albums/service.ts"
click node_playlists "https://github.com/brunovieira003/groov-api/blob/master/src/resources/playlists/service.ts"
click node_tasks "https://github.com/brunovieira003/groov-api/blob/master/src/resources/tasks/service.ts"
click node_scan_cli "https://github.com/brunovieira003/groov-api/blob/master/src/bin/scan.ts"
click node_read_queue "https://github.com/brunovieira003/groov-api/blob/master/src/lib/queues/read-file.ts"
click node_prune_queues "https://github.com/brunovieira003/groov-api/tree/master/src/lib/queues"
click node_db_client "https://github.com/brunovieira003/groov-api/blob/master/src/database/index.ts"
click node_db_schema "https://github.com/brunovieira003/groov-api/blob/master/src/database/schema.ts"
click node_media_files "https://github.com/brunovieira003/groov-api/blob/master/src/lib/constants.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_songs_api,node_artists_api,node_albums_api,node_playlists_api,node_tasks_api,node_tools_api,node_client toneBlue
class node_songs,node_artists,node_albums,node_playlists toneAmber
class node_tasks,node_scan_cli,node_read_queue,node_prune_queues toneMint
class node_db_client,node_db_schema,node_media_files toneRose
```

## Components

### API entry

- [HTTP application](https://github.com/brunovieira003/groov-api/blob/master/src/index.ts): `src/index.ts`
- [Song routes](https://github.com/brunovieira003/groov-api/blob/master/src/resources/song/controller.ts): `src/resources/song/controller.ts`
- [Artist routes](https://github.com/brunovieira003/groov-api/blob/master/src/resources/artists/controller.ts): `src/resources/artists/controller.ts`
- [Album routes](https://github.com/brunovieira003/groov-api/blob/master/src/resources/albums/controller.ts): `src/resources/albums/controller.ts`
- [Playlist routes](https://github.com/brunovieira003/groov-api/blob/master/src/resources/playlists/controller.ts): `src/resources/playlists/controller.ts`
- [Task routes](https://github.com/brunovieira003/groov-api/blob/master/src/resources/tasks/controller.ts): `src/resources/tasks/controller.ts`
- [Search routes](https://github.com/brunovieira003/groov-api/blob/master/src/resources/tools/controller.ts): `src/resources/tools/controller.ts`

### Music library

- [Song service](https://github.com/brunovieira003/groov-api/blob/master/src/resources/song/service.ts): `src/resources/song/service.ts`
- [Artist service](https://github.com/brunovieira003/groov-api/blob/master/src/resources/artists/service.ts): `src/resources/artists/service.ts`
- [Album service](https://github.com/brunovieira003/groov-api/blob/master/src/resources/albums/service.ts): `src/resources/albums/service.ts`
- [Playlist service](https://github.com/brunovieira003/groov-api/blob/master/src/resources/playlists/service.ts): `src/resources/playlists/service.ts`

### Ingestion and tasks

- [Task service](https://github.com/brunovieira003/groov-api/blob/master/src/resources/tasks/service.ts): `src/resources/tasks/service.ts`
- [Scan command](https://github.com/brunovieira003/groov-api/blob/master/src/bin/scan.ts): `src/bin/scan.ts`
- [File read queue](https://github.com/brunovieira003/groov-api/blob/master/src/lib/queues/read-file.ts): `src/lib/queues/read-file.ts`
- [Prune queues](https://github.com/brunovieira003/groov-api/tree/master/src/lib/queues): `src/lib/queues`

### Persistence and files

- [Database access](https://github.com/brunovieira003/groov-api/blob/master/src/database/index.ts): `src/database/index.ts`
- [Music schema](https://github.com/brunovieira003/groov-api/blob/master/src/database/schema.ts): `src/database/schema.ts`
- [Audio and images](https://github.com/brunovieira003/groov-api/blob/master/src/lib/constants.ts): `src/lib/constants.ts`

### Other components

- **Player client**

## Connections

- Player client → HTTP application: sends requests
- HTTP application → Song routes: dispatches
- HTTP application → Artist routes: dispatches
- HTTP application → Album routes: dispatches
- HTTP application → Playlist routes: dispatches
- HTTP application → Task routes: dispatches
- HTTP application → Search routes: dispatches
- Song routes → Song service: calls
- Artist routes → Artist service: calls
- Album routes → Album service: calls
- Playlist routes → Playlist service: calls
- Task routes → Task service: calls
- Search routes → Song service: searches
- Search routes → Artist service: searches
- Search routes → Album service: searches
- Search routes → Playlist service: searches
- Song routes → File read queue: enqueues file
- Task service → File read queue: enqueues scan
- Task service → Prune queues: enqueues pruning
- Song service → Database access: queries
- Artist service → Database access: queries
- Album service → Database access: queries
- Playlist service → Database access: queries
- Database access → Music schema: uses schema
- Song service → Audio and images: reads audio and lyrics
- Song service → Audio and images: reads covers
- Playlist service → Audio and images: reads and writes covers
- Artist service → Audio and images: reads covers
- Album service → Audio and images: reads covers