# jermsmit/snare architecture

> Architecture diagram of the GitHub repository jermsmit/snare, 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/jermsmit/snare
- Repository: https://github.com/jermsmit/snare

## Overview

Snare is a self-hosted media download manager. A user submits a URL and options through the web dashboard; the jobs API records it, the queue manager dispatches it, and the downloader selects yt-dlp or gallery-dl, reports progress, and saves media for browsing, preview, or download. Cookie profiles and settings support that workflow, while system and archive APIs provide monitoring and file management. The graph follows the documented capabilities and sampled source; UI-to-API links reflect the frontend API calls, while unsampled implementation details are left broad.

Main entry points: [`frontend/static/js/app.js`](https://github.com/jermsmit/snare/blob/main/frontend/static/js/app.js) (Dashboard SPA), [`backend/main.py`](https://github.com/jermsmit/snare/blob/main/backend/main.py) (FastAPI app), [`backend/core/downloader.py`](https://github.com/jermsmit/snare/blob/main/backend/core/downloader.py) (Download runner), [`backend/core/database.py`](https://github.com/jermsmit/snare/blob/main/backend/core/database.py) (SQLite database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Dashboard SPA<br/>[app.js]"]
  node_shell["Page shell<br/>[index.html]"]
end

subgraph group_api["API routes"]
  node_app["FastAPI app<br/>[main.py]"]
  node_jobs_api["Jobs API<br/>[jobs.py]"]
  node_cookies_api["Cookie profiles API<br/>[cookies.py]"]
  node_archive_api["Archive API<br/>[archive.py]"]
  node_system_api["System settings API<br/>[system.py]"]
end

subgraph group_jobs["Download processing"]
  node_queue["Queue manager<br/>[queue_manager.py]"]
  node_downloader["Download runner<br/>[downloader.py]"]
end

subgraph group_state["Persistent state"]
  node_database[("SQLite database<br/>[database.py]")]
  node_media[("Downloaded media")]
end

node_user(("Browser user"))
node_ytdlp["yt-dlp"]
node_gallerydl["gallery-dl"]
node_disk["Server disk"]
node_cookie_editor["Cookie-Editor"]

node_user -->|"uses"| node_frontend
node_app -->|"serves"| node_shell
node_frontend -->|"loads page"| node_app
node_frontend -->|"calls jobs"| node_jobs_api
node_frontend -->|"calls profiles"| node_cookies_api
node_frontend -->|"calls archive"| node_archive_api
node_frontend -->|"calls settings"| node_system_api
node_app -->|"dispatches"| node_jobs_api
node_app -->|"dispatches"| node_cookies_api
node_app -->|"dispatches"| node_archive_api
node_app -->|"dispatches"| node_system_api
node_jobs_api -->|"reads/writes jobs"| node_database
node_jobs_api -->|"cancels job"| node_queue
node_queue -->|"reads/writes queue"| node_database
node_queue -->|"runs download"| node_downloader
node_downloader -->|"reads/writes state"| node_database
node_downloader -->|"runs tool"| node_ytdlp
node_downloader -->|"runs tool"| node_gallerydl
node_downloader -->|"writes files"| node_media
node_cookies_api -->|"reads/writes profiles"| node_database
node_cookie_editor -.->|"provides cookie JSON"| node_frontend
node_system_api -->|"reads/writes settings"| node_database
node_system_api -->|"checks usage"| node_disk
node_archive_api -->|"browses/serves files"| node_media
node_archive_api -->|"deletes files"| node_disk

click node_frontend "https://github.com/jermsmit/snare/blob/main/frontend/static/js/app.js"
click node_shell "https://github.com/jermsmit/snare/blob/main/frontend/templates/index.html"
click node_app "https://github.com/jermsmit/snare/blob/main/backend/main.py"
click node_jobs_api "https://github.com/jermsmit/snare/blob/main/backend/api/routes/jobs.py"
click node_cookies_api "https://github.com/jermsmit/snare/blob/main/backend/api/routes/cookies.py"
click node_archive_api "https://github.com/jermsmit/snare/blob/main/backend/api/routes/archive.py"
click node_system_api "https://github.com/jermsmit/snare/blob/main/backend/api/routes/system.py"
click node_queue "https://github.com/jermsmit/snare/blob/main/backend/core/queue_manager.py"
click node_downloader "https://github.com/jermsmit/snare/blob/main/backend/core/downloader.py"
click node_database "https://github.com/jermsmit/snare/blob/main/backend/core/database.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_frontend,node_shell,node_user toneBlue
class node_app,node_jobs_api,node_cookies_api,node_archive_api,node_system_api toneAmber
class node_queue,node_downloader,node_disk toneMint
class node_database,node_media toneRose
class node_ytdlp,node_gallerydl,node_cookie_editor toneIndigo
```

## Components

### Web interface

- [Dashboard SPA](https://github.com/jermsmit/snare/blob/main/frontend/static/js/app.js): `frontend/static/js/app.js`
- [Page shell](https://github.com/jermsmit/snare/blob/main/frontend/templates/index.html): `frontend/templates/index.html`

### API routes

- [FastAPI app](https://github.com/jermsmit/snare/blob/main/backend/main.py): `backend/main.py`
- [Jobs API](https://github.com/jermsmit/snare/blob/main/backend/api/routes/jobs.py): `backend/api/routes/jobs.py`
- [Cookie profiles API](https://github.com/jermsmit/snare/blob/main/backend/api/routes/cookies.py): `backend/api/routes/cookies.py`
- [Archive API](https://github.com/jermsmit/snare/blob/main/backend/api/routes/archive.py): `backend/api/routes/archive.py`
- [System settings API](https://github.com/jermsmit/snare/blob/main/backend/api/routes/system.py): `backend/api/routes/system.py`

### Download processing

- [Queue manager](https://github.com/jermsmit/snare/blob/main/backend/core/queue_manager.py): `backend/core/queue_manager.py`
- [Download runner](https://github.com/jermsmit/snare/blob/main/backend/core/downloader.py): `backend/core/downloader.py`

### Persistent state

- [SQLite database](https://github.com/jermsmit/snare/blob/main/backend/core/database.py): `backend/core/database.py`
- **Downloaded media**

### Other components

- **Browser user**
- **yt-dlp**
- **gallery-dl**
- **Server disk**
- **Cookie-Editor**

## Connections

- Browser user → Dashboard SPA: uses
- FastAPI app → Page shell: serves
- Dashboard SPA → FastAPI app: loads page
- Dashboard SPA → Jobs API: calls jobs
- Dashboard SPA → Cookie profiles API: calls profiles
- Dashboard SPA → Archive API: calls archive
- Dashboard SPA → System settings API: calls settings
- FastAPI app → Jobs API: dispatches
- FastAPI app → Cookie profiles API: dispatches
- FastAPI app → Archive API: dispatches
- FastAPI app → System settings API: dispatches
- Jobs API → SQLite database: reads/writes jobs
- Jobs API → Queue manager: cancels job
- Queue manager → SQLite database: reads/writes queue
- Queue manager → Download runner: runs download
- Download runner → SQLite database: reads/writes state
- Download runner → yt-dlp: runs tool
- Download runner → gallery-dl: runs tool
- Download runner → Downloaded media: writes files
- Cookie profiles API → SQLite database: reads/writes profiles
- Cookie-Editor → Dashboard SPA: provides cookie JSON
- System settings API → SQLite database: reads/writes settings
- System settings API → Server disk: checks usage
- Archive API → Downloaded media: browses/serves files
- Archive API → Server disk: deletes files