# shadowmoose/redditdownloader architecture

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

- Interactive diagram: https://gitdiagram.com/shadowmoose/redditdownloader
- Repository: https://github.com/shadowmoose/redditdownloader

## Overview

Reddit Media Downloader scans configured Reddit and direct-input sources, filters their posts, extracts linked media, and saves downloads and processing state locally. Its principal run path is exposed through a terminal or web interface and coordinated by RMDController. The README also documents duplicate-image detection, resume behavior, and a web-based configuration and browsing UI. Some subsystems are represented by their exact enclosing directories because their implementation was not sampled; those connections are limited to documented capabilities or explicit sampled calls.

Main entry points: [`redditdownloader/processing/controller.py`](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/controller.py) (Run Controller), [`redditdownloader/processing/downloader.py`](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/downloader.py) (Downloader), [`redditdownloader/sources`](https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources) (Source Adapters), [`redditdownloader/processing/redditloader.py`](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/redditloader.py) (Reddit Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_terminal["Terminal UI<br/>[terminal.py]"]
  node_webui["Web UI<br/>[eelwrapper.py]"]
  node_webapp["Web App<br/>[App.js]"]
  node_settings["Settings<br/>[settings.py]"]
end

subgraph group_discovery["Source Discovery"]
  node_sources["Source Adapters"]
  node_reddit["Reddit Sources"]
  node_pushshift["Pushshift Search"]
  node_direct["Direct Inputs"]
  node_filters["Post Filters<br/>[filter.py]"]
end

subgraph group_work["Download Processing"]
  node_controller["Run Controller<br/>[controller.py]"]
  node_loader["Reddit Loader<br/>[redditloader.py]"]
  node_queue["Work Queue<br/>[queue_reader.py]"]
  node_downloader["Downloader<br/>[downloader.py]"]
  node_handlers["Media Handlers"]
  node_http["HTTP Downloader<br/>[http_downloader.py]"]
  node_dedupe["Image Deduplicator<br/>[post_processing.py]"]
end

subgraph group_state["Persistence"]
  node_database[("Manifest Database")]
  node_filesystem["Local Files<br/>[filesystem.py]"]
end

subgraph group_integrations["External Services"]
  node_redditapi["Reddit API"]
  node_pushshiftapi["Pushshift API"]
  node_media["Media Sites"]
end

node_user(("User"))

node_user -->|"runs"| node_terminal
node_user -->|"configures"| node_webapp
node_webapp -->|"calls API"| node_webui
node_terminal -->|"starts run"| node_controller
node_webui -->|"starts run"| node_controller
node_webui -->|"reads and saves"| node_settings
node_controller -->|"loads config"| node_settings
node_settings -->|"loads configured"| node_sources
node_controller -->|"creates"| node_loader
node_loader -->|"reads posts"| node_sources
node_sources -->|"includes"| node_reddit
node_sources -->|"includes"| node_pushshift
node_sources -->|"includes"| node_direct
node_reddit -.->|"fetches posts"| node_redditapi
node_pushshift -.->|"searches"| node_pushshiftapi
node_reddit -->|"checks posts"| node_filters
node_pushshift -->|"checks posts"| node_filters
node_loader -->|"enqueues work"| node_queue
node_controller -->|"creates workers"| node_downloader
node_downloader -->|"reads tasks"| node_queue
node_downloader -->|"dispatches links"| node_handlers
node_handlers -->|"downloads files"| node_http
node_http -->|"fetches media"| node_media
node_controller -->|"starts optionally"| node_dedupe
node_loader -->|"records posts"| node_database
node_downloader -->|"records results"| node_database
node_downloader -->|"saves downloads"| node_filesystem
node_dedupe -->|"checks duplicates"| node_database
node_dedupe -->|"compares files"| node_filesystem

click node_terminal "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/interfaces/terminal.py"
click node_webui "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/interfaces/eelwrapper.py"
click node_webapp "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/web/js/App.js"
click node_controller "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/controller.py"
click node_settings "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/static/settings.py"
click node_sources "https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources"
click node_reddit "https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources"
click node_pushshift "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/sources/pushshift_search_source.py"
click node_direct "https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources"
click node_filters "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/filters/filter.py"
click node_loader "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/redditloader.py"
click node_queue "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/wrappers/queue_reader.py"
click node_downloader "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/downloader.py"
click node_handlers "https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/processing/handlers"
click node_http "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/wrappers/http_downloader.py"
click node_dedupe "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/post_processing.py"
click node_database "https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sql"
click node_filesystem "https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/static/filesystem.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_terminal,node_webui,node_webapp,node_settings,node_user toneBlue
class node_sources,node_reddit,node_pushshift,node_direct,node_filters toneAmber
class node_controller,node_loader,node_queue,node_downloader,node_handlers,node_http,node_dedupe toneMint
class node_database,node_filesystem toneRose
class node_redditapi,node_pushshiftapi,node_media toneIndigo
```

## Components

### Interfaces

- [Terminal UI](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/interfaces/terminal.py): `redditdownloader/interfaces/terminal.py`
- [Web UI](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/interfaces/eelwrapper.py): `redditdownloader/interfaces/eelwrapper.py`
- [Web App](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/web/js/App.js): `redditdownloader/web/js/App.js`
- [Settings](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/static/settings.py): `redditdownloader/static/settings.py`

### Source Discovery

- [Source Adapters](https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources): `redditdownloader/sources`
- [Reddit Sources](https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources): `redditdownloader/sources`
- [Pushshift Search](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/sources/pushshift_search_source.py): `redditdownloader/sources/pushshift_search_source.py`
- [Direct Inputs](https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sources): `redditdownloader/sources`
- [Post Filters](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/filters/filter.py): `redditdownloader/filters/filter.py`

### Download Processing

- [Run Controller](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/controller.py): `redditdownloader/processing/controller.py`
- [Reddit Loader](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/redditloader.py): `redditdownloader/processing/redditloader.py`
- [Work Queue](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/wrappers/queue_reader.py): `redditdownloader/processing/wrappers/queue_reader.py`
- [Downloader](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/downloader.py): `redditdownloader/processing/downloader.py`
- [Media Handlers](https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/processing/handlers): `redditdownloader/processing/handlers`
- [HTTP Downloader](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/wrappers/http_downloader.py): `redditdownloader/processing/wrappers/http_downloader.py`
- [Image Deduplicator](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/processing/post_processing.py): `redditdownloader/processing/post_processing.py`

### Persistence

- [Manifest Database](https://github.com/shadowmoose/redditdownloader/tree/master/redditdownloader/sql): `redditdownloader/sql`
- [Local Files](https://github.com/shadowmoose/redditdownloader/blob/master/redditdownloader/static/filesystem.py): `redditdownloader/static/filesystem.py`

### External Services

- **Reddit API**
- **Pushshift API**
- **Media Sites**

### Other components

- **User**

## Connections

- User → Terminal UI: runs
- User → Web App: configures
- Web App → Web UI: calls API
- Terminal UI → Run Controller: starts run
- Web UI → Run Controller: starts run
- Web UI → Settings: reads and saves
- Run Controller → Settings: loads config
- Settings → Source Adapters: loads configured
- Run Controller → Reddit Loader: creates
- Reddit Loader → Source Adapters: reads posts
- Source Adapters → Reddit Sources: includes
- Source Adapters → Pushshift Search: includes
- Source Adapters → Direct Inputs: includes
- Reddit Sources → Reddit API: fetches posts
- Pushshift Search → Pushshift API: searches
- Reddit Sources → Post Filters: checks posts
- Pushshift Search → Post Filters: checks posts
- Reddit Loader → Work Queue: enqueues work
- Run Controller → Downloader: creates workers
- Downloader → Work Queue: reads tasks
- Downloader → Media Handlers: dispatches links
- Media Handlers → HTTP Downloader: downloads files
- HTTP Downloader → Media Sites: fetches media
- Run Controller → Image Deduplicator: starts optionally
- Reddit Loader → Manifest Database: records posts
- Downloader → Manifest Database: records results
- Downloader → Local Files: saves downloads
- Image Deduplicator → Manifest Database: checks duplicates
- Image Deduplicator → Local Files: compares files