How kucheriavij/vk-music-downloader works
1. Project shape
- This is a small Symfony/PHP monolith built around one main use case: download VK audio tracks, store them locally, and show the downloaded list in a browser.
- There are two entry paths: a console ingestion path and a web presentation path.
2. External dependency boundary: VK
- The app depends on VK credentials and user ID from .env:
- VK_LOGIN
- VK_PASSWORD
- VK_UID
- The src/Traits/Http.php and src/Service/Params.php files likely support the VK request/auth flow and parameter handling.
- The README makes it clear that VK rate limiting is a practical constraint, especially when using --offset.
3. Ingestion subsystem
- The primary backend job is the vk:download console command in src/Command/DownloadCommand.php.
- src/Command/AbstractCommand.php suggests shared command setup/common behavior for console jobs.
- The command accepts --limit, --offset, and --uid, so the download pipeline is parameterized and can fetch a subset of tracks.
4. Persistence subsystem
- Downloaded audio metadata is modeled by the Doctrine entity src/Entity/Audio.php.
- src/Repository/AudioRepository.php is the access layer for querying stored audio records.
- The README shows standard Doctrine setup: create database and update schema, so the database is the main persistent store for downloaded track records.
5. File storage boundary
- There is a dedicated public/download/mp3 directory, which strongly indicates downloaded audio files are written to the filesystem there.
- Because it lives under public/, those files are directly web-accessible once saved.
- This is separate from the database: the DB stores track metadata, while the filesystem stores the actual MP3 artifacts.
6. Web presentation subsystem
- src/Controller/DefaultController.php is the main HTTP controller.
- templates/default/index.html.twig and templates/base.html.twig indicate a Twig-based UI that renders the list of downloaded audio.
- So the browser-facing portion is likely a simple read-only interface over the stored audio records.
7. Runtime and request flow
- public/index.php is the HTTP front controller, and bin/console is the CLI entrypoint.
- This makes the architecture split cleanly into:
- HTTP request handling for browsing
- CLI command execution for downloading
- src/Kernel.php is the Symfony application bootstrap tying both entry points to the same container/configuration.
8. Configuration and environment
- Framework wiring lives under config/, including routes, services, Twig, and environment-specific settings.
- .env.dist and the README indicate that runtime behavior is controlled through environment variables, especially VK and DB settings.
- The DB is described as using mysqli by default, which affects deployment/runtime configuration more than code structure.
9. Frontend asset pipeline
- assets/css/app.scss and assets/js/app.js are the source assets.
- webpack.config.js and package.json show that frontend assets are built separately from the PHP app.
- This is a lightweight asset pipeline for styling and client-side behavior, not a separate frontend application.
10. Overall data flow
- VK API/service → console command → Doctrine entity/database + MP3 files on disk → web controller/Twig UI
- The database and filesystem together form the local copy of the downloaded music library.
- The browser never talks to VK directly; it only reads the locally stored result.
11. Important architectural constraint
- The project is intentionally simple and synchronous: there is no queue, worker farm, or external storage service in the repository.
- That means the download command is the critical integration point and also the main operational bottleneck, especially under VK request limits.
Main entry points: DownloadCommand.php Download job · Kernel.php Kernel · AudioRepository.php Audio repo · DefaultController.php Browser view
Components 21
Runtime
CLI and HTTP entrypoints plus Symfony bootstrap.
- Front controller · Bootstraps the Symfony app for browser requests.
public/index.php - Console entry · Bootstraps the Symfony console application.
bin/console
Ingestion
Console download flow and VK request handling.
- Download job · Main ingestion command for downloading VK audio.
src/Command/DownloadCommand.php - Command base · Common console command setup and behavior.
src/Command/AbstractCommand.php - Params · Parameter handling for VK request and command inputs.
src/Service/Params.php - HTTP helper · Shared HTTP/auth behavior for VK interaction.
src/Traits/Http.php
Storage
Database and filesystem persistence for downloaded tracks.
- Audio record · Persisted metadata model for downloaded tracks.
src/Entity/Audio.php - Audio repo · Query access layer for stored audio records.
src/Repository/AudioRepository.php - MP3 store · Public directory where downloaded MP3 files are written.
public/download/mp3 - Database · Doctrine-backed storage for audio metadata.
Web UI
HTTP controller and Twig templates for browsing local audio.
- Browser view · Serves the list of downloaded audio in the browser.
src/Controller/DefaultController.php - Audio list · Renders the downloaded track list.
templates/default/index.html.twig - Base layout · Shared page layout for the web UI.
templates/base.html.twig
Frontend Assets
Built styling and client-side assets.
- Styles · Source stylesheet for the web UI.
assets/css/app.scss - Script · Client-side behavior for the web UI.
assets/js/app.js - Asset build · Builds frontend assets from source files.
webpack.config.js
Config
Symfony, environment, and routing/service wiring.
- Kernel · Shared Symfony application bootstrap for both runtimes.
src/Kernel.php - Routes · HTTP route definitions and route wiring.
config/routes.yaml - Services · Dependency injection configuration and service wiring.
config/services.yaml - Env vars · VK credentials, user ID, and database settings.
.env.dist
Other components
- VK API · Upstream VK authentication and audio data source.
Connections 25
- Front controller → Kernel: bootstraps · HTTP entrypoint loads the Symfony kernel.
- Console entry → Kernel: bootstraps · Console entrypoint loads the same kernel.
- Kernel → Routes: loads · Kernel reads routing configuration.
- Kernel → Services: loads · Kernel loads service wiring.
- Kernel → Env vars: uses · Runtime configuration comes from environment variables.
- Console entry → Download job: runs · Console entry executes the VK download command.
- Download job → Command base: extends · Download command inherits shared command behavior.
- Download job → Params: uses · Command parameterizes VK fetches and limits.
- Download job → HTTP helper: uses · Command relies on shared VK HTTP/auth behavior.
- HTTP helper → VK API: calls · Helper communicates with VK.
- Params → VK API: formats · Request parameters target VK API expectations.
- Download job → Audio record: creates · Downloaded tracks are modeled as audio entities.
- Download job → Audio repo: stores · Command persists or updates audio records through the repository.
- Audio repo → Database: queries · Repository reads and writes Doctrine-managed data.
- Audio record → Database: maps to · Entity is the persisted track metadata model.
- Download job → MP3 store: writes · Actual MP3 files are saved under the public download directory.
- Front controller → Browser view: dispatches · HTTP requests are routed to the main controller.
- Browser view → Audio repo: reads · Controller loads stored audio records for display.
- Browser view → Audio list: renders · Controller renders the audio list template.
- Audio list → Base layout: extends · List view uses the shared base layout.
- Audio list → Audio repo: shows · Rendered list reflects repository-backed data.
- Asset build → Styles: builds · Webpack compiles the stylesheet source.
- Asset build → Script: builds · Webpack bundles the client script source.
- Base layout → Styles: includes · UI layout is styled by the built assets.
- Base layout → Script: includes · UI layout loads the built script bundle.