# kucheriavij/vk-music-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/kucheriavij/vk-music-downloader
- Repository: https://github.com/kucheriavij/vk-music-downloader

## Overview

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: [`src/Command/DownloadCommand.php`](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Command/DownloadCommand.php) (Download job), [`src/Kernel.php`](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Kernel.php) (Kernel), [`src/Repository/AudioRepository.php`](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Repository/AudioRepository.php) (Audio repo), [`src/Controller/DefaultController.php`](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Controller/DefaultController.php) (Browser view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_public_index["Front controller<br/>http entrypoint<br/>[index.php]"]
  node_bin_console["Console entry<br/>cli entrypoint"]
end

subgraph group_ingestion["Ingestion"]
  node_download_cmd["Download job<br/>console command"]
  node_abstract_cmd["Command base<br/>shared command"]
  node_params["Params<br/>[Params.php]"]
  node_http_trait["HTTP helper<br/>vk client helper<br/>[Http.php]"]
end

subgraph group_storage["Storage"]
  node_audio_entity[("Audio record<br/>doctrine entity<br/>[Audio.php]")]
  node_audio_repo["Audio repo"]
  node_mp3_store[("MP3 store<br/>filesystem storage")]
  node_database[("Database<br/>persistent store")]
end

subgraph group_web["Web UI"]
  node_default_controller["Browser view<br/>http controller"]
  node_twig_index["Audio list<br/>twig template<br/>[index.html.twig]"]
  node_twig_base["Base layout<br/>twig layout<br/>[base.html.twig]"]
end

subgraph group_frontend["Frontend Assets"]
  node_app_scss["Styles<br/>scss asset<br/>[app.scss]"]
  node_app_js["Script<br/>js asset<br/>[app.js]"]
  node_webpack["Asset build<br/>build pipeline<br/>[webpack.config.js]"]
end

subgraph group_config["Config"]
  node_kernel{{"Kernel<br/>app bootstrap<br/>[Kernel.php]"}}
  node_routes["Routes<br/>routing config<br/>[routes.yaml]"]
  node_services["Services<br/>service config<br/>[services.yaml]"]
  node_env["Env vars<br/>runtime config<br/>[.env.dist]"]
end

node_vk_external(("VK API<br/>external service"))

node_public_index -->|"bootstraps"| node_kernel
node_bin_console -->|"bootstraps"| node_kernel
node_kernel -->|"loads"| node_routes
node_kernel -->|"loads"| node_services
node_kernel -->|"uses"| node_env
node_bin_console -->|"runs"| node_download_cmd
node_download_cmd -->|"extends"| node_abstract_cmd
node_download_cmd -->|"uses"| node_params
node_download_cmd -->|"uses"| node_http_trait
node_http_trait -->|"calls"| node_vk_external
node_params -->|"formats"| node_vk_external
node_download_cmd -->|"creates"| node_audio_entity
node_download_cmd -->|"stores"| node_audio_repo
node_audio_repo -->|"queries"| node_database
node_audio_entity -->|"maps to"| node_database
node_download_cmd -->|"writes"| node_mp3_store
node_public_index -->|"dispatches"| node_default_controller
node_default_controller -->|"reads"| node_audio_repo
node_default_controller -->|"renders"| node_twig_index
node_twig_index -->|"extends"| node_twig_base
node_twig_index -.->|"shows"| node_audio_repo
node_webpack -->|"builds"| node_app_scss
node_webpack -->|"builds"| node_app_js
node_twig_base -.->|"includes"| node_app_scss
node_twig_base -.->|"includes"| node_app_js

click node_public_index "https://github.com/kucheriavij/vk-music-downloader/blob/master/public/index.php"
click node_bin_console "https://github.com/kucheriavij/vk-music-downloader/tree/master/bin/console"
click node_kernel "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Kernel.php"
click node_routes "https://github.com/kucheriavij/vk-music-downloader/blob/master/config/routes.yaml"
click node_services "https://github.com/kucheriavij/vk-music-downloader/blob/master/config/services.yaml"
click node_env "https://github.com/kucheriavij/vk-music-downloader/blob/master/.env.dist"
click node_download_cmd "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Command/DownloadCommand.php"
click node_abstract_cmd "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Command/AbstractCommand.php"
click node_params "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Service/Params.php"
click node_http_trait "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Traits/Http.php"
click node_audio_entity "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Entity/Audio.php"
click node_audio_repo "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Repository/AudioRepository.php"
click node_mp3_store "https://github.com/kucheriavij/vk-music-downloader/tree/master/public/download/mp3"
click node_default_controller "https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Controller/DefaultController.php"
click node_twig_index "https://github.com/kucheriavij/vk-music-downloader/blob/master/templates/default/index.html.twig"
click node_twig_base "https://github.com/kucheriavij/vk-music-downloader/blob/master/templates/base.html.twig"
click node_app_scss "https://github.com/kucheriavij/vk-music-downloader/blob/master/assets/css/app.scss"
click node_app_js "https://github.com/kucheriavij/vk-music-downloader/blob/master/assets/js/app.js"
click node_webpack "https://github.com/kucheriavij/vk-music-downloader/blob/master/webpack.config.js"

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_public_index,node_bin_console toneBlue
class node_download_cmd,node_abstract_cmd,node_params,node_http_trait toneAmber
class node_audio_entity,node_audio_repo,node_mp3_store,node_database toneMint
class node_default_controller,node_twig_index,node_twig_base toneRose
class node_app_scss,node_app_js,node_webpack toneIndigo
class node_kernel,node_routes,node_services,node_env toneTeal
class node_vk_external toneNeutral
```

## Components

### Runtime

CLI and HTTP entrypoints plus Symfony bootstrap.

- [Front controller](https://github.com/kucheriavij/vk-music-downloader/blob/master/public/index.php): http entrypoint · Bootstraps the Symfony app for browser requests. · `public/index.php`
- [Console entry](https://github.com/kucheriavij/vk-music-downloader/tree/master/bin/console): cli entrypoint · Bootstraps the Symfony console application. · `bin/console`

### Ingestion

Console download flow and VK request handling.

- [Download job](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Command/DownloadCommand.php): console command · Main ingestion command for downloading VK audio. · `src/Command/DownloadCommand.php`
- [Command base](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Command/AbstractCommand.php): shared command · Common console command setup and behavior. · `src/Command/AbstractCommand.php`
- [Params](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Service/Params.php): request params · Parameter handling for VK request and command inputs. · `src/Service/Params.php`
- [HTTP helper](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Traits/Http.php): vk client helper · Shared HTTP/auth behavior for VK interaction. · `src/Traits/Http.php`

### Storage

Database and filesystem persistence for downloaded tracks.

- [Audio record](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Entity/Audio.php): doctrine entity · Persisted metadata model for downloaded tracks. · `src/Entity/Audio.php`
- [Audio repo](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Repository/AudioRepository.php): repository · Query access layer for stored audio records. · `src/Repository/AudioRepository.php`
- [MP3 store](https://github.com/kucheriavij/vk-music-downloader/tree/master/public/download/mp3): filesystem storage · Public directory where downloaded MP3 files are written. · `public/download/mp3`
- **Database**: persistent store · Doctrine-backed storage for audio metadata.

### Web UI

HTTP controller and Twig templates for browsing local audio.

- [Browser view](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Controller/DefaultController.php): http controller · Serves the list of downloaded audio in the browser. · `src/Controller/DefaultController.php`
- [Audio list](https://github.com/kucheriavij/vk-music-downloader/blob/master/templates/default/index.html.twig): twig template · Renders the downloaded track list. · `templates/default/index.html.twig`
- [Base layout](https://github.com/kucheriavij/vk-music-downloader/blob/master/templates/base.html.twig): twig layout · Shared page layout for the web UI. · `templates/base.html.twig`

### Frontend Assets

Built styling and client-side assets.

- [Styles](https://github.com/kucheriavij/vk-music-downloader/blob/master/assets/css/app.scss): scss asset · Source stylesheet for the web UI. · `assets/css/app.scss`
- [Script](https://github.com/kucheriavij/vk-music-downloader/blob/master/assets/js/app.js): js asset · Client-side behavior for the web UI. · `assets/js/app.js`
- [Asset build](https://github.com/kucheriavij/vk-music-downloader/blob/master/webpack.config.js): build pipeline · Builds frontend assets from source files. · `webpack.config.js`

### Config

Symfony, environment, and routing/service wiring.

- [Kernel](https://github.com/kucheriavij/vk-music-downloader/blob/master/src/Kernel.php): app bootstrap · Shared Symfony application bootstrap for both runtimes. · `src/Kernel.php`
- [Routes](https://github.com/kucheriavij/vk-music-downloader/blob/master/config/routes.yaml): routing config · HTTP route definitions and route wiring. · `config/routes.yaml`
- [Services](https://github.com/kucheriavij/vk-music-downloader/blob/master/config/services.yaml): service config · Dependency injection configuration and service wiring. · `config/services.yaml`
- [Env vars](https://github.com/kucheriavij/vk-music-downloader/blob/master/.env.dist): runtime config · VK credentials, user ID, and database settings. · `.env.dist`

### Other components

- **VK API**: external service · Upstream VK authentication and audio data source.

## Connections

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