# bishtvineet/pwa_music_app_backend architecture

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

- Interactive diagram: https://gitdiagram.com/bishtvineet/pwa_music_app_backend
- Repository: https://github.com/bishtvineet/pwa_music_app_backend

## Overview

This NestJS backend serves a client-side music archiving workflow: validate a YouTube URL, fetch metadata, then stream transcoded MP3 audio and headers to the client for offline storage. It also supports thumbnail proxying and cookie updates. The graph includes README-documented cover-art muxing, though the sampled audio implementation shows ID3v2.3 tags but not cover-art processing; the JPEG stage is therefore shown as unverified. Relationships reflect sampled calls and explicit README data-flow statements.

Main entry points: [`src/modules/converter/converter.controller.ts`](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts) (Converter API), [`src/modules/youtube/youtube.service.ts`](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/youtube/youtube.service.ts) (Metadata extraction), [`src/app.module.ts`](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/app.module.ts) (Application modules), [`src/modules/audio/audio.service.ts`](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/audio/audio.service.ts) (Audio stream service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and routing"]
  node_converter["Converter API"]
  node_url_pipe["URL validation"]
  node_app_module["Application modules<br/>[app.module.ts]"]
end

subgraph group_youtube["YouTube ingestion"]
  node_metadata["Metadata extraction<br/>[youtube.service.ts]"]
  node_video_info["Video metadata DTO<br/>[video-info.dto.ts]"]
  node_ytdlp["yt-dlp"]
end

subgraph group_audio["Audio processing"]
  node_audio_service["Audio stream service<br/>[audio.service.ts]"]
  node_ffmpeg["FFmpeg transcoder"]
  node_cover_art["JPEG cover-art mux"]
  node_mp3["MP3 stream and tags<br/>[audio.service.ts]"]
end

subgraph group_support["Client support"]
  node_cookie_sync["Cookie update endpoint"]
  node_cookie_files["Runtime cookie files"]
  node_thumbnail_proxy["Thumbnail proxy"]
end

node_pwa(("React PWA"))
node_image_host(("Thumbnail image host"))
node_offline_store[("IndexedDB storage")]

node_pwa -->|"calls API"| node_converter
node_converter -->|"validates URL"| node_url_pipe
node_converter -->|"requests metadata"| node_metadata
node_metadata -->|"extracts metadata"| node_ytdlp
node_metadata -->|"returns metadata"| node_video_info
node_converter -->|"starts download"| node_audio_service
node_audio_service -->|"fetches audio"| node_ytdlp
node_ytdlp -->|"pipes audio"| node_ffmpeg
node_ffmpeg -->|"transcodes audio"| node_mp3
node_mp3 -->|"streams MP3"| node_pwa
node_pwa -->|"stores audio"| node_offline_store
node_converter -->|"accepts cookie updates"| node_cookie_sync
node_cookie_sync -->|"writes cookies"| node_cookie_files
node_thumbnail_proxy -->|"fetches image"| node_image_host
node_pwa -.->|"requests thumbnail"| node_thumbnail_proxy
node_app_module -->|"registers module"| node_converter
node_app_module -->|"registers module"| node_metadata
node_app_module -->|"registers module"| node_audio_service
node_cover_art -.->|"embeds artwork"| node_mp3

click node_converter "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts"
click node_url_pipe "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/common/pipes/youtube-url.pipe.ts"
click node_metadata "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/youtube/youtube.service.ts"
click node_video_info "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/youtube/dto/video-info.dto.ts"
click node_audio_service "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/audio/audio.service.ts"
click node_cover_art "https://github.com/bishtvineet/pwa_music_app_backend/tree/main/src/modules/audio"
click node_mp3 "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/audio/audio.service.ts"
click node_cookie_sync "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts"
click node_thumbnail_proxy "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts"
click node_app_module "https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/app.module.ts"

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_converter,node_url_pipe,node_app_module toneBlue
class node_metadata,node_video_info,node_ytdlp,node_offline_store toneAmber
class node_audio_service,node_ffmpeg,node_cover_art,node_mp3 toneMint
class node_cookie_sync,node_cookie_files,node_thumbnail_proxy toneRose
class node_pwa,node_image_host toneIndigo
```

## Components

### API and routing

- [Converter API](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts): `src/modules/converter/converter.controller.ts`
- [URL validation](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/common/pipes/youtube-url.pipe.ts): `src/common/pipes/youtube-url.pipe.ts`
- [Application modules](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/app.module.ts): `src/app.module.ts`

### YouTube ingestion

- [Metadata extraction](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/youtube/youtube.service.ts): `src/modules/youtube/youtube.service.ts`
- [Video metadata DTO](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/youtube/dto/video-info.dto.ts): `src/modules/youtube/dto/video-info.dto.ts`
- **yt-dlp**

### Audio processing

- [Audio stream service](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/audio/audio.service.ts): `src/modules/audio/audio.service.ts`
- **FFmpeg transcoder**
- [JPEG cover-art mux](https://github.com/bishtvineet/pwa_music_app_backend/tree/main/src/modules/audio): `src/modules/audio`
- [MP3 stream and tags](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/audio/audio.service.ts): `src/modules/audio/audio.service.ts`

### Client support

- [Cookie update endpoint](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts): `src/modules/converter/converter.controller.ts`
- **Runtime cookie files**
- [Thumbnail proxy](https://github.com/bishtvineet/pwa_music_app_backend/blob/main/src/modules/converter/converter.controller.ts): `src/modules/converter/converter.controller.ts`

### Other components

- **React PWA**
- **Thumbnail image host**
- **IndexedDB storage**

## Connections

- React PWA → Converter API: calls API (evidence: `README.md`)
- Converter API → URL validation: validates URL (evidence: `src/modules/converter/converter.controller.ts`)
- Converter API → Metadata extraction: requests metadata (evidence: `src/modules/converter/converter.controller.ts`)
- Metadata extraction → yt-dlp: extracts metadata (evidence: `src/modules/youtube/youtube.service.ts`)
- Metadata extraction → Video metadata DTO: returns metadata (evidence: `src/modules/youtube/youtube.service.ts`)
- Converter API → Audio stream service: starts download (evidence: `src/modules/converter/converter.controller.ts`)
- Audio stream service → yt-dlp: fetches audio (evidence: `src/modules/audio/audio.service.ts`)
- yt-dlp → FFmpeg transcoder: pipes audio
- FFmpeg transcoder → MP3 stream and tags: transcodes audio (evidence: `src/modules/audio/audio.service.ts`)
- MP3 stream and tags → React PWA: streams MP3 (evidence: `README.md`)
- React PWA → IndexedDB storage: stores audio (evidence: `README.md`)
- Converter API → Cookie update endpoint: accepts cookie updates (evidence: `src/modules/converter/converter.controller.ts`)
- Cookie update endpoint → Runtime cookie files: writes cookies (evidence: `src/modules/converter/converter.controller.ts`)
- Thumbnail proxy → Thumbnail image host: fetches image (evidence: `src/modules/converter/converter.controller.ts`)
- React PWA → Thumbnail proxy: requests thumbnail
- Application modules → Converter API: registers module (evidence: `src/app.module.ts`)
- Application modules → Metadata extraction: registers module (evidence: `src/app.module.ts`)
- Application modules → Audio stream service: registers module (evidence: `src/app.module.ts`)
- JPEG cover-art mux → MP3 stream and tags: embeds artwork (evidence: `README.md`)
