# ttndevfullstack/koel architecture

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

- Interactive diagram: https://gitdiagram.com/ttndevfullstack/koel
- Repository: https://github.com/ttndevfullstack/koel

## Overview

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: [`app/Services`](https://github.com/ttndevfullstack/koel/tree/master/app/Services) (Domain services), [`app/Http/Controllers`](https://github.com/ttndevfullstack/koel/tree/master/app/Http/Controllers) (Controllers), [`vite.config.ts`](https://github.com/ttndevfullstack/koel/blob/master/vite.config.ts) (Vite build), [`resources/assets/js/stores`](https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/stores) (State & services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Laravel backend"]
  node_routes["Routes<br/>HTTP entrypoints"]
  node_controllers["Controllers"]
  node_requests["Form requests<br/>validation layer"]
  node_middleware["Middleware<br/>access gates"]
  node_services["Domain services<br/>application services"]
  node_ai["AI assistant<br/>plus feature slice"]
  node_storage["Media storage<br/>song storage"]
  node_streaming["Streaming<br/>audio delivery"]
  node_scanning["Library scanning<br/>scan pipeline"]
  node_models[("Models<br/>Eloquent domain")]
  node_repositories["Repositories<br/>data access"]
  node_events_jobs["Events & jobs<br/>async orchestration"]
  node_integrations["Integrations<br/>external APIs"]
  node_policies["Policies<br/>authorization rules"]
end

subgraph group_frontend["Vue frontend"]
  node_frontend_app["Frontend app<br/>Vue SPA<br/>[App.vue]"]
  node_frontend_shells["UI shells<br/>screen views"]
  node_frontend_state["State & services<br/>client orchestration"]
  node_frontend_remote["Remote app<br/>secondary Vue app"]
  node_frontend_ui["UI library<br/>shared components"]
  node_frontend_sw(("Service worker<br/>offline runtime<br/>[service-worker.ts]"))
end

subgraph group_ops["Runtime & infra"]
  node_migrations["Migrations<br/>schema evolution"]
  node_build["Vite build<br/>asset pipeline<br/>[vite.config.ts]"]
  node_runtime["Runtime<br/>[index.php]"]
end

node_routes -->|"dispatches"| node_controllers
node_controllers -->|"validates"| node_requests
node_controllers -->|"protected by"| node_middleware
node_controllers -->|"orchestrates"| node_services
node_services -->|"reads/writes"| node_repositories
node_services -->|"materializes"| node_models
node_services -->|"calls out"| node_integrations
node_services -->|"stores media"| node_storage
node_services -->|"serves audio"| node_streaming
node_services -->|"maintains library"| node_scanning
node_services -->|"assistant actions"| node_ai
node_scanning -->|"emits"| node_events_jobs
node_events_jobs -->|"background work"| node_services
node_policies -->|"authorize"| node_models
node_migrations -->|"evolves schema"| node_models
node_frontend_app -->|"renders"| node_frontend_shells
node_frontend_app -->|"uses"| node_frontend_state
node_frontend_shells -->|"composes"| node_frontend_ui
node_frontend_state -->|"API calls"| node_controllers
node_frontend_state -->|"offline sync"| node_frontend_sw
node_frontend_remote -->|"remote API"| node_controllers
node_build -->|"bundles"| node_frontend_app
node_build -->|"bundles"| node_frontend_remote
node_build -->|"generates"| node_frontend_sw
node_runtime -->|"boots"| node_routes

click node_routes "https://github.com/ttndevfullstack/koel/tree/master/routes"
click node_controllers "https://github.com/ttndevfullstack/koel/tree/master/app/Http/Controllers"
click node_requests "https://github.com/ttndevfullstack/koel/tree/master/app/Http/Requests"
click node_middleware "https://github.com/ttndevfullstack/koel/tree/master/app/Http/Middleware"
click node_services "https://github.com/ttndevfullstack/koel/tree/master/app/Services"
click node_ai "https://github.com/ttndevfullstack/koel/tree/master/app/Ai"
click node_storage "https://github.com/ttndevfullstack/koel/tree/master/app/Services/SongStorages"
click node_streaming "https://github.com/ttndevfullstack/koel/tree/master/app/Services/Streamer"
click node_scanning "https://github.com/ttndevfullstack/koel/tree/master/app/Services/Scanners"
click node_models "https://github.com/ttndevfullstack/koel/tree/master/app/Models"
click node_repositories "https://github.com/ttndevfullstack/koel/tree/master/app/Repositories"
click node_events_jobs "https://github.com/ttndevfullstack/koel/tree/master/app/Events"
click node_integrations "https://github.com/ttndevfullstack/koel/tree/master/app/Http/Integrations"
click node_policies "https://github.com/ttndevfullstack/koel/tree/master/app/Policies"
click node_migrations "https://github.com/ttndevfullstack/koel/tree/master/database/migrations"
click node_frontend_app "https://github.com/ttndevfullstack/koel/blob/master/resources/assets/js/App.vue"
click node_frontend_shells "https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/components/screens"
click node_frontend_state "https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/stores"
click node_frontend_remote "https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/remote"
click node_frontend_ui "https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/components/ui"
click node_frontend_sw "https://github.com/ttndevfullstack/koel/blob/master/resources/assets/js/service-worker.ts"
click node_build "https://github.com/ttndevfullstack/koel/blob/master/vite.config.ts"
click node_runtime "https://github.com/ttndevfullstack/koel/blob/master/public/index.php"

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_routes,node_controllers,node_requests,node_middleware,node_services,node_ai,node_storage,node_streaming,node_scanning,node_models,node_repositories,node_events_jobs,node_integrations,node_policies toneBlue
class node_frontend_app,node_frontend_shells,node_frontend_state,node_frontend_remote,node_frontend_ui,node_frontend_sw toneAmber
class node_migrations,node_build,node_runtime toneMint
```

## Components

### Laravel backend

API, domain services, persistence, and async orchestration.

- [Routes](https://github.com/ttndevfullstack/koel/tree/master/routes): HTTP entrypoints · API, web, console, and broadcast route definitions. · `routes`
- [Controllers](https://github.com/ttndevfullstack/koel/tree/master/app/Http/Controllers): API/web controllers · Thin request handlers for auth, media, playlists, streaming, uploads, settings, AI, and SSO. · `app/Http/Controllers`
- [Form requests](https://github.com/ttndevfullstack/koel/tree/master/app/Http/Requests): validation layer · Request validation and authorization objects for API and download flows. · `app/Http/Requests`
- [Middleware](https://github.com/ttndevfullstack/koel/tree/master/app/Http/Middleware): access gates · Cross-cutting request guards for auth, demo mode, HTTPS, audio, object storage, and plus features. · `app/Http/Middleware`
- [Domain services](https://github.com/ttndevfullstack/koel/tree/master/app/Services): application services · Core business logic for library, playback, playlists, podcasts, radio, search, AI support, licensing, and integrations. · `app/Services`
- [AI assistant](https://github.com/ttndevfullstack/koel/tree/master/app/Ai): plus feature slice · Assistant agents, tools, serializers, and request resolution for chat-driven domain actions. · `app/Ai`
- [Media storage](https://github.com/ttndevfullstack/koel/tree/master/app/Services/SongStorages): song storage · Local, Dropbox, S3-compatible, and SFTP storage adapters plus upload and transcode handling. · `app/Services/SongStorages`
- [Streaming](https://github.com/ttndevfullstack/koel/tree/master/app/Services/Streamer): audio delivery · Streaming adapters and proxy/redirect logic for local, cloud, podcast, and transcoded audio. · `app/Services/Streamer`
- [Library scanning](https://github.com/ttndevfullstack/koel/tree/master/app/Services/Scanners): scan pipeline · Filesystem scanning, folder extraction, cache strategy, and scan result processing. · `app/Services/Scanners`
- [Models](https://github.com/ttndevfullstack/koel/tree/master/app/Models): Eloquent domain · Albums, artists, songs, playlists, podcasts, radio stations, users, favorites, queue state, transcodes, themes, and settings. · `app/Models`
- [Repositories](https://github.com/ttndevfullstack/koel/tree/master/app/Repositories): data access · Query-focused access to albums, artists, songs, playlists, folders, podcasts, radio, users, themes, transcodes, and settings. · `app/Repositories`
- [Events & jobs](https://github.com/ttndevfullstack/koel/tree/master/app/Events): async orchestration · Domain events, listeners, queued jobs, and background maintenance tasks. · `app/Events`
- [Integrations](https://github.com/ttndevfullstack/koel/tree/master/app/Http/Integrations): external APIs · MusicBrainz, Wikidata, Wikipedia, iTunes, YouTube, Spotify, Last.fm, Ticketmaster, IPinfo, and licensing connectors. · `app/Http/Integrations`
- [Policies](https://github.com/ttndevfullstack/koel/tree/master/app/Policies): authorization rules · 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](https://github.com/ttndevfullstack/koel/blob/master/resources/assets/js/App.vue): Vue SPA · Primary Vue 3 application shell and app bootstrap. · `resources/assets/js/App.vue`
- [UI shells](https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/components/screens): screen views · Screen hierarchy for albums, artists, playlists, podcasts, radio, settings, uploads, search, queue, profile, and AI assistant. · `resources/assets/js/components/screens`
- [State & services](https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/stores): client orchestration · Pinia-like stores, composables, HTTP/audio/offline/socket services, and playback manager. · `resources/assets/js/stores`
- [Remote app](https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/remote): secondary Vue app · Stripped-down remote-control experience with its own app entrypoint and components. · `resources/assets/js/remote`
- [UI library](https://github.com/ttndevfullstack/koel/tree/master/resources/assets/js/components/ui): shared components · Reusable UI primitives, layout, forms, media cards, playlist widgets, podcast widgets, and visualizers. · `resources/assets/js/components/ui`
- [Service worker](https://github.com/ttndevfullstack/koel/blob/master/resources/assets/js/service-worker.ts): offline runtime · PWA/offline support and cache behavior for the frontend. · `resources/assets/js/service-worker.ts`

### Runtime & infra

Build, deployment, database, and background execution.

- [Migrations](https://github.com/ttndevfullstack/koel/tree/master/database/migrations): schema evolution · Database history for media, users, multi-tenancy, favorites, collaborations, podcasts, radio, queues, licenses, permissions, audits, and transcodes. · `database/migrations`
- [Vite build](https://github.com/ttndevfullstack/koel/blob/master/vite.config.ts): asset pipeline · Frontend bundling for the main app, remote UI, and service worker. · `vite.config.ts`
- [Runtime](https://github.com/ttndevfullstack/koel/blob/master/public/index.php): Laravel runtime · Public entrypoints, Blade shells, and server bootstrap for web execution. · `public/index.php`

## Connections

- 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.
