# franciscorsantos/dtube architecture

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

- Interactive diagram: https://gitdiagram.com/franciscorsantos/dtube
- Repository: https://github.com/franciscorsantos/dtube
- Video tour (about a minute): https://gitdiagram.com/franciscorsantos/dtube/video

## Overview

dTube lets a user enter a YouTube URL, inspect video metadata and available formats, then request an MP4 video or MP3 audio download and save the streamed file locally with progress feedback. The browser UI calls a FastAPI backend: routes validate and shape requests, while the YouTube service uses yt-dlp for extraction and temporary-file downloads; the response schedules cleanup after delivery. The README also documents adjustable API configuration, cookies, and FFmpeg support. Frontend request and streaming behavior and backend service wiring are source-backed; broader UI details are based on README claims.

Main entry points: [`backend/app/api/routes.py`](https://github.com/franciscorsantos/dtube/blob/main/backend/app/api/routes.py) (API endpoints), [`frontend/app.js`](https://github.com/franciscorsantos/dtube/blob/main/frontend/app.js) (UI controller), [`backend/app/services/youtube_service.py`](https://github.com/franciscorsantos/dtube/blob/main/backend/app/services/youtube_service.py) (YouTube service), [`frontend/index.html`](https://github.com/franciscorsantos/dtube/blob/main/frontend/index.html) (Downloader UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser interface"]
  node_ui["Downloader UI<br/>[index.html]"]
  node_controller["UI controller<br/>[app.js]"]
  node_config["API configuration<br/>[config.js]"]
  node_browser_files["Local save target"]
end

subgraph group_api["REST API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_routes["API endpoints<br/>[routes.py]"]
  node_schemas["Request and response models<br/>[schemas.py]"]
end

subgraph group_media["Media processing"]
  node_service["YouTube service<br/>[youtube_service.py]"]
  node_helpers["Validation and cleanup<br/>[helpers.py]"]
  node_temp["Temporary media files<br/>[youtube_service.py]"]
end

node_user(("User"))
node_ytdlp["yt-dlp"]
node_youtube(("YouTube"))
node_ffmpeg["FFmpeg"]

node_user -->|"uses"| node_ui
node_ui -->|"drives"| node_controller
node_controller -->|"reads settings"| node_config
node_controller -->|"requests metadata or download"| node_routes
node_routes -->|"validates and shapes"| node_schemas
node_routes -->|"requests processing"| node_service
node_service -->|"validates URLs and formats duration"| node_helpers
node_service -->|"extracts or downloads"| node_ytdlp
node_ytdlp -->|"fetches media data"| node_youtube
node_service -->|"writes download"| node_temp
node_service -.->|"converts audio"| node_ffmpeg
node_routes -->|"serves file"| node_temp
node_routes -->|"schedules cleanup"| node_helpers
node_routes -->|"returns metadata or streams file"| node_controller
node_controller -->|"updates details and progress"| node_ui
node_controller -->|"writes downloaded file"| node_browser_files
node_user -->|"chooses save destination"| node_browser_files
node_helpers -->|"removes after delivery"| node_temp

click node_ui "https://github.com/franciscorsantos/dtube/blob/main/frontend/index.html"
click node_controller "https://github.com/franciscorsantos/dtube/blob/main/frontend/app.js"
click node_config "https://github.com/franciscorsantos/dtube/blob/main/frontend/config.js"
click node_fastapi "https://github.com/franciscorsantos/dtube/blob/main/backend/app/main.py"
click node_routes "https://github.com/franciscorsantos/dtube/blob/main/backend/app/api/routes.py"
click node_schemas "https://github.com/franciscorsantos/dtube/blob/main/backend/app/api/schemas.py"
click node_service "https://github.com/franciscorsantos/dtube/blob/main/backend/app/services/youtube_service.py"
click node_helpers "https://github.com/franciscorsantos/dtube/blob/main/backend/app/utils/helpers.py"
click node_temp "https://github.com/franciscorsantos/dtube/blob/main/backend/app/services/youtube_service.py"

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_ui,node_controller,node_config,node_browser_files,node_user toneBlue
class node_fastapi,node_routes,node_schemas toneAmber
class node_service,node_helpers,node_temp toneMint
class node_ytdlp,node_youtube,node_ffmpeg toneIndigo
```

## Components

### Browser interface

- [Downloader UI](https://github.com/franciscorsantos/dtube/blob/main/frontend/index.html): `frontend/index.html`
- [UI controller](https://github.com/franciscorsantos/dtube/blob/main/frontend/app.js): `frontend/app.js`
- [API configuration](https://github.com/franciscorsantos/dtube/blob/main/frontend/config.js): `frontend/config.js`
- **Local save target**

### REST API

- [FastAPI app](https://github.com/franciscorsantos/dtube/blob/main/backend/app/main.py): `backend/app/main.py`
- [API endpoints](https://github.com/franciscorsantos/dtube/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Request and response models](https://github.com/franciscorsantos/dtube/blob/main/backend/app/api/schemas.py): `backend/app/api/schemas.py`

### Media processing

- [YouTube service](https://github.com/franciscorsantos/dtube/blob/main/backend/app/services/youtube_service.py): `backend/app/services/youtube_service.py`
- [Validation and cleanup](https://github.com/franciscorsantos/dtube/blob/main/backend/app/utils/helpers.py): `backend/app/utils/helpers.py`
- [Temporary media files](https://github.com/franciscorsantos/dtube/blob/main/backend/app/services/youtube_service.py): `backend/app/services/youtube_service.py`

### Other components

- **User**
- **yt-dlp**
- **YouTube**
- **FFmpeg**

## Connections

- User → Downloader UI: uses
- Downloader UI → UI controller: drives
- UI controller → API configuration: reads settings
- UI controller → API endpoints: requests metadata or download
- API endpoints → Request and response models: validates and shapes
- API endpoints → YouTube service: requests processing
- YouTube service → Validation and cleanup: validates URLs and formats duration
- YouTube service → yt-dlp: extracts or downloads
- yt-dlp → YouTube: fetches media data
- YouTube service → Temporary media files: writes download
- YouTube service → FFmpeg: converts audio
- API endpoints → Temporary media files: serves file
- API endpoints → Validation and cleanup: schedules cleanup
- API endpoints → UI controller: returns metadata or streams file
- UI controller → Downloader UI: updates details and progress
- UI controller → Local save target: writes downloaded file
- User → Local save target: chooses save destination
- Validation and cleanup → Temporary media files: removes after delivery