The Problem

Koel solves self-hosting your music library: instead of renting a streaming service or uploading your collection to a third party, you run a web app on your own server that scans a media folder and serves it to any browser or mobile client. It targets developers who want a modern, good-looking player without the operational weight of something like Navidrome or Funkwhale.

What This Does

Koel is a Vue single-page app (resources/assets/js/app.ts) talking to a Laravel JSON API (app/Http/Controllers/API/). The server scans a configured media directory via app/Console/Commands/ScanCommand.php, extracts metadata and artwork, and exposes songs, albums, artists, playlists, genres, and podcasts through REST endpoints. The frontend handles playback, queueing, visualizers, and a desktop-style UI, with Tailwind for styling.

The repo also ships a plusService (resources/assets/js/services/plusService) for the commercial Koel Plus tier, and a set of WebGL audio visualizers under resources/assets/js/visualizers/ (asteroid, waveform, plane-mesh).

How It Is Wired

Execution starts in the browser at resources/assets/js/app.ts, which boots the Vue app and calls the Laravel API. On the server, app/Http/Controllers/API/FetchInitialDataController.php is the front door that returns the user's library, settings, and queue state. From there, controllers delegate to services and Eloquent models; app/Builders/ holds query builders (SongBuilder.php, AlbumBuilder.php, ArtistBuilder.php) that scope queries per user.

The import graph (373 internal modules, 25 edges, zero circular dependencies) shows the visualizer modules — visualizers/asteroid/scripts/index and visualizers/asteroid/shaders/index — are the most-connected by outbound imports (Ce 5 and 4) but nothing imports them (Ca 0). They're self-contained leaves; changing them costs nothing elsewhere. plusService is a stable leaf (Ca 1, Ce 0). No cycles means no module change ripples unpredictably.

The wiring for deeper request paths (controller → service → DB/network effects) has not been mapped for this repository, so I can't trace a full run's database or filesystem effects beyond the entry points above.

How To Use It

The README defers install details to the official docs (docs.koel.dev), so exact commands aren't in the repo. The evidence present:

  • Setup: composer.json and package.json imply composer install and pnpm install (pnpm is the detected package manager).
  • Configuration: copy .env.example to .env and set database credentials, media path, and app key.
  • Running it: set up the database via Laravel migrations (database/ has 106 files), then run php artisan koel:init (the InitCommand exists at app/Console/Commands/InitCommand.php) and php artisan koel:scan to index music. The exact commands are not documented in the repo, so confirm against the official docs.

Real-World Use

A developer with a NAS or VPS points Koel at a folder of MP3s/FLACs, runs the scan command, and gets a browser player with playlists, favorites, and search. The mobile companion app (koel/player) consumes the same API, so one server covers desktop and phone. The podcast sync command (SyncPodcastsCommand.php) extends the same server to podcast feeds.

Code Health & Issues

Static analysis (not opinion) found 36 issues: 5 high, 31 medium. Three kinds:

  • High – deep nesting — max indentation depth 8 in app/Builders/ArtistBuilder.php, AlbumBuilder.php, SongBuilder.php. Control flow is hard to follow; fix with early returns/guard clauses.
  • High – duplicated code — 80 repeated 6-line blocks across 48 files, including tests/Feature/EpisodeTest.php and app/Http/Controllers/API/FetchFavoriteSongsController.php. Extract shared helpers.
  • Medium – high branching density — 13 branch points over 42 lines in app/Services/SpotifyService.php; decompose with strategy dispatch.

SDLC audit (7 findings, 0 critical):

  • High – GitHub Actions pinned to tags (shivammathur/setup-php@v2, etc.) in .github/workflows; a moved tag can run arbitrary code with your token. Pin to commit SHAs.
  • High – CI never runs the test suite: 461 test files exist, no test command in the 4 workflows read. The green check asserts nothing.
  • Med – no permissions: declaration on any workflow; the token inherits repo defaults.
  • Med – no Dependabot/Renovate configured despite 2 manifests.
  • Med – no dependency vulnerability scan in CI.
  • Med – checkout keeps credentials in .git/config; set persist-credentials: false.
  • Low – no job timeouts; a wedged job runs to the 6-hour default.

Dependencies: 119 packages, 37 behind current major versions (e.g., lint-staged 7 majors behind, cypress 6 majors behind).

The Bottom Line

A mature, well-organized music server with a clean module graph and no circular dependencies. The main risks are operational: CI that doesn't run tests and unpinned actions undermine trust in the green checks. Fix those two before anything else; the codebase itself is solid and worth using for a personal streaming setup.