# shdwofm/vk-album-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/shdwofm/vk-album-downloader
- Repository: https://github.com/shdwofm/vk-album-downloader

## Overview

VK Album Downloader is a local web app that accepts a VK access token and album link, downloads the album’s photos, and offers them as a ZIP. The main flow runs from the browser through job creation and background processing to ZIP download; status requests expose progress. Internal stages include URL parsing, VK photo listing, image retrieval, and in-memory ZIP assembly. The implementation is concentrated in app.py; index.html is identified by the tree and its role in serving the browser UI is documented, but its contents were not sampled.

Main entry points: [`app.py`](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py) (Download worker), [`index.html`](https://github.com/shdwofm/vk-album-downloader/blob/main/index.html) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_browser["Browser UI<br/>[index.html]"]
end

subgraph group_jobs["Job handling"]
  node_routes["API routes<br/>[app.py]"]
  node_start["Start job<br/>[app.py]"]
  node_parser["Album URL parser<br/>[app.py]"]
  node_jobstore["In-memory jobs<br/>[app.py]"]
  node_status["Job status<br/>[app.py]"]
  node_downloadroute["ZIP download<br/>[app.py]"]
end

subgraph group_download["Album download"]
  node_worker["Download worker<br/>[app.py]"]
  node_vkapi["VK API"]
  node_photos["Photo URLs<br/>[app.py]"]
  node_images["Image hosting"]
  node_zip["ZIP archive<br/>[app.py]"]
end

node_user(("User"))

node_user -->|"provides inputs"| node_browser
node_browser -->|"starts download"| node_start
node_browser -->|"checks progress"| node_status
node_browser -->|"saves ZIP"| node_downloadroute
node_start -->|"parses link"| node_parser
node_start -->|"creates job"| node_jobstore
node_start -->|"starts thread"| node_worker
node_worker -->|"requests photos"| node_vkapi
node_worker -->|"collects URLs"| node_photos
node_worker -->|"fetches images"| node_images
node_worker -->|"assembles archive"| node_zip
node_worker -->|"updates progress"| node_jobstore
node_status -->|"reads progress"| node_jobstore
node_downloadroute -->|"reads completed job"| node_jobstore
node_downloadroute -->|"serves archive"| node_zip

click node_browser "https://github.com/shdwofm/vk-album-downloader/blob/main/index.html"
click node_routes "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_start "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_parser "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_jobstore "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_worker "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_photos "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_zip "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_status "https://github.com/shdwofm/vk-album-downloader/blob/main/app.py"
click node_downloadroute "https://github.com/shdwofm/vk-album-downloader/blob/main/app.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_browser,node_user toneBlue
class node_routes,node_start,node_parser,node_jobstore,node_status,node_downloadroute toneAmber
class node_worker,node_vkapi,node_photos,node_images,node_zip toneMint
```

## Components

### Web interface

- [Browser UI](https://github.com/shdwofm/vk-album-downloader/blob/main/index.html): `index.html`

### Job handling

- [API routes](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- [Start job](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- [Album URL parser](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- [In-memory jobs](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- [Job status](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- [ZIP download](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`

### Album download

- [Download worker](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- **VK API**
- [Photo URLs](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`
- **Image hosting**
- [ZIP archive](https://github.com/shdwofm/vk-album-downloader/blob/main/app.py): `app.py`

### Other components

- **User**

## Connections

- User → Browser UI: provides inputs (evidence: `README.md`)
- Browser UI → Start job: starts download (evidence: `README.md`)
- Browser UI → Job status: checks progress (evidence: `README.md`)
- Browser UI → ZIP download: saves ZIP (evidence: `README.md`)
- Start job → Album URL parser: parses link (evidence: `app.py`)
- Start job → In-memory jobs: creates job (evidence: `app.py`)
- Start job → Download worker: starts thread (evidence: `app.py`)
- Download worker → VK API: requests photos (evidence: `app.py`)
- Download worker → Photo URLs: collects URLs (evidence: `app.py`)
- Download worker → Image hosting: fetches images (evidence: `app.py`)
- Download worker → ZIP archive: assembles archive (evidence: `app.py`)
- Download worker → In-memory jobs: updates progress (evidence: `app.py`)
- Job status → In-memory jobs: reads progress (evidence: `app.py`)
- ZIP download → In-memory jobs: reads completed job (evidence: `app.py`)
- ZIP download → ZIP archive: serves archive (evidence: `app.py`)
