# o-nos/reclip architecture

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

- Interactive diagram: https://gitdiagram.com/o-nos/reclip
- Repository: https://github.com/o-nos/reclip

## Overview

1. **Overall shape**
   - ReClip is a small, self-hosted Flask application with a server-rendered web UI.
   - The architecture is intentionally minimal: one Python backend, one HTML template, a static asset folder, and no database or build pipeline.

2. **Primary entry points**
   - `app.py` is the core application and likely contains all HTTP routes and download orchestration.
   - `reclip.sh` is the local startup wrapper used for running the app outside Docker.
   - `Dockerfile` packages the same app for containerized deployment.

3. **Frontend subsystem**
   - `templates/index.html` provides the entire user interface.
   - `static/` holds browser-served assets such as CSS/JS and any page-specific resources.
   - The UI is vanilla HTML/CSS/JS, so the browser talks directly to the Flask backend without a separate frontend service.

4. **Backend request flow**
   - The user pastes one or more URLs into the web UI.
   - The browser sends those URLs to Flask.
   - The backend uses `yt-dlp` to inspect the links, extract metadata, and determine available formats.
   - The backend returns video/audio info, thumbnails, and quality options to the UI.

5. **Download subsystem**
   - Actual media retrieval is delegated to `yt-dlp`.
   - Audio extraction and video conversion depend on `ffmpeg`, which is an external runtime dependency rather than an in-repo component.
   - Downloads are exposed to the user as MP4 or MP3 outputs, with quality selection for available formats.

6. **Bulk and deduplication behavior**
   - The app supports multiple URLs in one submission.
   - URL deduplication happens in the application layer so repeated links are not processed redundantly.
   - This suggests a request-scoped workflow rather than a persistent job queue or task store.

7. **Data and state boundaries**
   - There is no database, cache layer, or long-lived storage visible in the repo.
   - State appears to be transient: fetched metadata, selected formats, and generated downloads exist only during the request/session flow.
   - The system is therefore stateless at the infrastructure level, aside from temporary download artifacts handled during processing.

8. **External dependencies and services**
   - `yt-dlp` is the main external engine for site compatibility and metadata extraction across 1000+ supported platforms.
   - `ffmpeg` handles media processing/conversion.
   - The app does not depend on any external SaaS APIs; it operates entirely on user-supplied URLs and local tooling.

9. **Deployment model**
   - The app is designed to run locally or in a container on port `8899`.
   - Docker provides a self-contained runtime boundary for shipping Python plus system-level media tooling.
   - The README’s “single Python file backend” indicates the deployment footprint is intentionally small.

10. **Repository structure significance**
   - `assets/` contains preview media for documentation and does not participate in runtime request handling.
   - `LICENSE` and `README.md` are documentation/supporting files.
   - The architecture is centered almost entirely around one application path: browser UI → Flask backend → yt-dlp/ffmpeg → downloadable media response.

11. **What to draw in an architecture diagram**
   - Show a client browser talking to a Flask web app.
   - Show Flask invoking `yt-dlp` for metadata and downloads, and `ffmpeg` for conversion.
   - Show the response path returning thumbnails, format choices, and downloadable MP4/MP3 files.
   - Do not include databases, message queues, or separate frontend services, because this repo does not contain them.

Main entry points: [`app.py`](https://github.com/o-nos/reclip/blob/main/app.py) (Flask App), [`templates/index.html`](https://github.com/o-nos/reclip/blob/main/templates/index.html) (Main UI), [`reclip.sh`](https://github.com/o-nos/reclip/blob/main/reclip.sh) (Startup Script), [`Dockerfile`](https://github.com/o-nos/reclip/tree/main/Dockerfile) (Container Image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_browser(("Browser<br/>client"))
  node_template["Main UI<br/>html template<br/>[index.html]"]
  node_static["Static Assets<br/>browser assets"]
end

subgraph group_backend["Application Core"]
  node_app["Flask App<br/>web backend<br/>[app.py]"]
  node_dedupe{{"URL Dedupe<br/>request logic<br/>[app.py]"}}
  node_inspect{{"Metadata Probe<br/>yt-dlp inspect<br/>[app.py]"}}
  node_select{{"Format Picker<br/>quality logic<br/>[app.py]"}}
  node_download{{"Download Flow<br/>media retrieval<br/>[app.py]"}}
end

subgraph group_runtime["Runtime & Deploy"]
  node_sh["Startup Script<br/>shell wrapper<br/>[reclip.sh]"]
  node_docker["Container Image<br/>deployment"]
end

subgraph group_external["External Tools"]
  node_ytdlp["yt-dlp<br/>external downloader"]
  node_ffmpeg["ffmpeg<br/>media converter"]
end

node_browser -->|"view"| node_template
node_browser -->|"submit URLs"| node_app
node_template -->|"load assets"| node_static
node_app -->|"normalize list"| node_dedupe
node_dedupe -->|"inspect links"| node_inspect
node_inspect -->|"probe"| node_ytdlp
node_inspect -->|"formats"| node_select
node_select -->|"choose output"| node_download
node_download -->|"fetch media"| node_ytdlp
node_download -->|"convert"| node_ffmpeg
node_download -->|"response"| node_app
node_app -->|"results"| node_browser
node_sh -->|"run locally"| node_app
node_docker -->|"package run"| node_app

click node_template "https://github.com/o-nos/reclip/blob/main/templates/index.html"
click node_static "https://github.com/o-nos/reclip/tree/main/static"
click node_app "https://github.com/o-nos/reclip/blob/main/app.py"
click node_dedupe "https://github.com/o-nos/reclip/blob/main/app.py"
click node_inspect "https://github.com/o-nos/reclip/blob/main/app.py"
click node_select "https://github.com/o-nos/reclip/blob/main/app.py"
click node_download "https://github.com/o-nos/reclip/blob/main/app.py"
click node_sh "https://github.com/o-nos/reclip/blob/main/reclip.sh"
click node_docker "https://github.com/o-nos/reclip/tree/main/Dockerfile"

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_browser,node_template,node_static toneBlue
class node_app,node_dedupe,node_inspect,node_select,node_download toneAmber
class node_sh,node_docker toneMint
class node_ytdlp,node_ffmpeg toneRose
```

## Components

### User Interface

Server-rendered browser UI and served static assets.

- **Browser**: client · User submits URLs and receives results in the web UI.
- [Main UI](https://github.com/o-nos/reclip/blob/main/templates/index.html): html template · Server-rendered page for URL entry, results, and download actions. · `templates/index.html`
- [Static Assets](https://github.com/o-nos/reclip/tree/main/static): browser assets · CSS, JS, and other files served directly to the browser. · `static`

### Application Core

Single Flask app that handles requests and download orchestration.

- [Flask App](https://github.com/o-nos/reclip/blob/main/app.py): web backend · Primary application entry point and request handler. · `app.py`
- [URL Dedupe](https://github.com/o-nos/reclip/blob/main/app.py): request logic · Removes repeated URLs within a submission before processing. · `app.py`
- [Metadata Probe](https://github.com/o-nos/reclip/blob/main/app.py): yt-dlp inspect · Extracts video metadata, thumbnails, and format information. · `app.py`
- [Format Picker](https://github.com/o-nos/reclip/blob/main/app.py): quality logic · Chooses available audio/video qualities and output options. · `app.py`
- [Download Flow](https://github.com/o-nos/reclip/blob/main/app.py): media retrieval · Coordinates fetching media and preparing MP4 or MP3 outputs. · `app.py`

### Runtime & Deploy

Local and container launch paths for the app.

- [Startup Script](https://github.com/o-nos/reclip/blob/main/reclip.sh): shell wrapper · Local launch helper for running the app outside Docker. · `reclip.sh`
- [Container Image](https://github.com/o-nos/reclip/tree/main/Dockerfile): deployment · Packages the Python app and system dependencies for containerized runs. · `Dockerfile`

### External Tools

System tools invoked by the app for media extraction and conversion.

- **yt-dlp**: external downloader · External engine for platform compatibility, metadata extraction, and media downloads.
- **ffmpeg**: media converter · External runtime used for audio extraction and video conversion.

## Connections

- Browser → Main UI: view · User loads the main page in a browser.
- Browser → Flask App: submit URLs · Browser sends submitted links and options to the Flask backend.
- Main UI → Static Assets: load assets · The page references browser-served styling and scripting assets.
- Flask App → URL Dedupe: normalize list · Backend removes duplicate URLs before processing.
- URL Dedupe → Metadata Probe: inspect links · Unique URLs are probed for metadata and available formats.
- Metadata Probe → yt-dlp: probe · yt-dlp provides site support and metadata extraction.
- Metadata Probe → Format Picker: formats · Extracted metadata feeds the quality and output selection logic.
- Format Picker → Download Flow: choose output · Selected format determines the download/conversion path.
- Download Flow → yt-dlp: fetch media · yt-dlp performs the actual media retrieval.
- Download Flow → ffmpeg: convert · ffmpeg handles audio extraction and video conversion.
- Download Flow → Flask App: response · Prepared media and result data are returned to the web layer.
- Flask App → Browser: results · Browser receives thumbnails, quality options, and download links/files.
- Startup Script → Flask App: run locally · Shell wrapper starts the Flask application outside containers.
- Container Image → Flask App: package run · Container image ships the app with its runtime dependencies.