How ttndevfullstack/koel works
1. Koel is a two-tier music streaming product: a Laravel backend exposes the API and serves a few Blade shells, while a Vue 3 frontend in resources/assets/js provides the main user experience. Vite builds the frontend, including a separate “remote” UI entrypoint and a service worker for offline/PWA behavior.
2. The backend is organized around Laravel’s standard layers: HTTP controllers, form requests, services, repositories, models, policies, middleware, jobs, and events. Controllers are mostly thin; domain logic lives in app/Services and data access in app/Repositories, with Eloquent models in app/Models representing albums, artists, songs, playlists, podcasts, radio stations, users, themes, favorites, interactions, transcodes, and license/settings state.
3. The core domain is a media library. Songs are scanned from a filesystem-backed media path, metadata is parsed, and the library is denormalized into albums/artists/genres/folders for fast browsing and search. Scan flows run through scanner services, console commands, jobs, and events such as MediaScanCompleted and LibraryChanged.
4. Audio delivery is a dedicated subsystem. Requests to play or stream content flow through streaming services and adapter implementations chosen by storage type: local files, Dropbox, S3-compatible storage, SFTP, podcast streams, or transcoded output. This boundary is central because the system does not assume all media is local.
5. Uploading and transcoding are asynchronous. Upload controllers hand off to upload services and HandleSongUploadJob; delete and cleanup jobs remove song/transcode artifacts; transcoding is abstracted behind strategy/factory classes so storage-specific handling stays isolated from the rest of the app.
6. Playback state is persisted and coordinated on the server. Queue state, recent plays, scrobbling, likes/favorites, and play counts are represented by models and updated through services/controllers/events. The frontend’s playback manager, queue store, and audio service synchronize with backend endpoints like queue state, playback status, and interaction tracking.
7. Playlists, favorites, and collaboration form another major boundary. The backend supports normal playlists, smart playlists with rule serialization/casts, playlist folders, collaborative playlists, and playlist collaboration tokens. Frontend components and composables for playlist management map directly to those backend resources and permissions.
8. Podcasts and radio stations are first-class media types. Podcast feeds are parsed and synced server-side, with episode progress tracked in the client. Radio stations are streamed through dedicated services and controllers, including “now playing” lookups and proxying/protecting stream access.
9. Search and discovery are split between local and external enrichment. Local search uses repository/service-backed indices, while metadata enrichment flows through integrations with MusicBrainz, Wikidata, Wikipedia, iTunes, YouTube, Spotify, Ticketmaster, and IPinfo. These services feed album/artist info, lyrics, artwork, events, and geolocation-based enhancements.
10. Authentication and access control are layered. The app uses Laravel auth/Sanctum-style session/token flows, role/permission tables, policies, and custom middleware for demo mode, HTTPS enforcement, plus-only feature gating, audio auth, and object-storage auth. There is also Google SSO, password reset, invites, and one-time tokens.
11. Koel Plus is an explicit feature boundary. Plus-only capabilities include cloud storage, AI assistant, collaboration, proxy auth, SSO, custom themes, media browser, white-labeling, and Ticketmaster/live-events features. These are enforced across middleware, attributes, services, and frontend gating logic rather than being just UI affordances.
12. The AI assistant is a separate feature slice in both backend and frontend. Backend AI agents/tools resolve user requests into domain actions like play songs, update lyrics, manage playlists, favorites, and radio stations; serializers convert results back into UI-friendly payloads. The frontend has a dedicated assistant screen, chat components, and a useAiChat composable that talks to AiController.
13. Persistence is backed by a relational database with heavy schema evolution. Migrations show long-lived support for user scope, multi-tenancy, favorites, playlist collaboration, radio stations, podcasts, embeds, themes, audits, genres, transcodes, permissions/roles, and ULID/public IDs. Settings, queue state, and licenses are stored centrally and feed application behavior.
14. The frontend is more than a single page shell. It contains reusable UI primitives, composables, Pinia-like stores, service modules for HTTP/audio/cache/socket/offline concerns, and a large screen/component hierarchy for albums, artists, playlists, podcasts, radio, settings, uploads, search, and AI. A separate resources/assets/js/remote app supports a stripped-down remote-control experience.
15. Operationally, the app relies on queues, scheduled/CLI maintenance commands, and webhooks/external APIs. Console commands cover scanning, artwork fetches, podcast sync, storage setup, licensing, cleanup, and installation tasks; jobs and listeners keep background work isolated from request handling. This makes the runtime architecture a mix of synchronous API requests and asynchronous library maintenance.
Main entry points: Services Domain services · Controllers Controllers · vite.config.ts Vite build · stores State & services
Components 23
Laravel backend
API, domain services, persistence, and async orchestration.
- Routes · API, web, console, and broadcast route definitions.
routes - Controllers · Thin request handlers for auth, media, playlists, streaming, uploads, settings, AI, and SSO.
app/Http/Controllers - Form requests · Request validation and authorization objects for API and download flows.
app/Http/Requests - Middleware · Cross-cutting request guards for auth, demo mode, HTTPS, audio, object storage, and plus features.
app/Http/Middleware - Domain services · Core business logic for library, playback, playlists, podcasts, radio, search, AI support, licensing, and integrations.
app/Services - AI assistant · Assistant agents, tools, serializers, and request resolution for chat-driven domain actions.
app/Ai - Media storage · Local, Dropbox, S3-compatible, and SFTP storage adapters plus upload and transcode handling.
app/Services/SongStorages - Streaming · Streaming adapters and proxy/redirect logic for local, cloud, podcast, and transcoded audio.
app/Services/Streamer - Library scanning · Filesystem scanning, folder extraction, cache strategy, and scan result processing.
app/Services/Scanners - Models · Albums, artists, songs, playlists, podcasts, radio stations, users, favorites, queue state, transcodes, themes, and settings.
app/Models - Repositories · Query-focused access to albums, artists, songs, playlists, folders, podcasts, radio, users, themes, transcodes, and settings.
app/Repositories - Events & jobs · Domain events, listeners, queued jobs, and background maintenance tasks.
app/Events - Integrations · MusicBrainz, Wikidata, Wikipedia, iTunes, YouTube, Spotify, Last.fm, Ticketmaster, IPinfo, and licensing connectors.
app/Http/Integrations - Policies · Model-level permission checks for albums, artists, playlists, podcasts, radio stations, songs, users, themes, and licenses.
app/Policies
Vue frontend
Main UI, remote UI, state, and client services.
- Frontend app · Primary Vue 3 application shell and app bootstrap.
resources/assets/js/App.vue - UI shells · Screen hierarchy for albums, artists, playlists, podcasts, radio, settings, uploads, search, queue, profile, and AI assistant.
resources/assets/js/components/screens - State & services · Pinia-like stores, composables, HTTP/audio/offline/socket services, and playback manager.
resources/assets/js/stores - Remote app · Stripped-down remote-control experience with its own app entrypoint and components.
resources/assets/js/remote - UI library · Reusable UI primitives, layout, forms, media cards, playlist widgets, podcast widgets, and visualizers.
resources/assets/js/components/ui - Service worker · PWA/offline support and cache behavior for the frontend.
resources/assets/js/service-worker.ts
Runtime & infra
Build, deployment, database, and background execution.
- Migrations · Database history for media, users, multi-tenancy, favorites, collaborations, podcasts, radio, queues, licenses, permissions, audits, and transcodes.
database/migrations - Vite build · Frontend bundling for the main app, remote UI, and service worker.
vite.config.ts - Runtime · Public entrypoints, Blade shells, and server bootstrap for web execution.
public/index.php
Connections 25
- Routes → Controllers: dispatches · Routes map requests to HTTP controllers.
- Controllers → Form requests: validates · Controllers rely on form requests for validation and authorization.
- Controllers → Middleware: protected by · Request handling passes through middleware gates.
- Controllers → Domain services: orchestrates · Controllers delegate domain work to services.
- Domain services → Repositories: reads/writes · Services use repositories for query and persistence boundaries.
- Domain services → Models: materializes · Services operate on Eloquent domain models and value objects.
- Domain services → Integrations: calls out · Enrichment, licensing, SSO, search, and media discovery use external APIs.
- Domain services → Media storage: stores media · Upload and storage services route files to storage backends.
- Domain services → Streaming: serves audio · Playback services produce stream responses through storage-aware adapters.
- Domain services → Library scanning: maintains library · Library and scan services coordinate filesystem scanning and denormalization.
- Domain services → AI assistant: assistant actions · AI tools resolve requests into domain services and serialized results.
- Library scanning → Events & jobs: emits · Scan completion and library change events trigger background work.
- Events & jobs → Domain services: background work · Jobs and listeners call back into services for cleanup, sync, and notifications.
- Policies → Models: authorize · Policies govern access to domain resources.
- Migrations → Models: evolves schema · Migrations shape the tables behind the domain models.
- Frontend app → UI shells: renders · The main app composes the screen hierarchy.
- Frontend app → State & services: uses · The app depends on stores, composables, and client services.
- UI shells → UI library: composes · Screens are built from reusable UI primitives and widgets.
- State & services → Controllers: API calls · Client services talk to backend endpoints for playback, search, uploads, playlists, and settings.
- State & services → Service worker: offline sync · Offline playback and cache services cooperate with the service worker.
- Remote app → Controllers: remote API · The remote app uses backend endpoints for control and playback state.
- Vite build → Frontend app: bundles · Vite builds the main Vue app entrypoint.
- Vite build → Remote app: bundles · Vite builds the remote app entrypoint.
- Vite build → Service worker: generates · Vite also builds the service worker asset.
- Runtime → Routes: boots · The Laravel runtime loads route definitions.