# frenzy8/tt-dl architecture

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

- Interactive diagram: https://gitdiagram.com/frenzy8/tt-dl
- Repository: https://github.com/frenzy8/tt-dl

## Overview

TikTok Downloader is an Express API that extracts TikTok video or photo metadata, exposes search results, and provides a tokenized endpoint for streaming media. The main workflow is a client request to download metadata, extraction from TikTok’s page or item-detail response, and a returned watch link that proxies the media stream. Search and photo-carousel retrieval are separate browser-driven paths. The graph reflects sampled route and service code; the search excerpt is partial, and the README documents capabilities beyond the sampled implementation.

Main entry points: [`routes/search.js`](https://github.com/frenzy8/tt-dl/blob/main/routes/search.js) (Search route), [`routes/download.js`](https://github.com/frenzy8/tt-dl/blob/main/routes/download.js) (Download route), [`routes/watch.js`](https://github.com/frenzy8/tt-dl/blob/main/routes/watch.js) (Watch route), [`index.js`](https://github.com/frenzy8/tt-dl/blob/main/index.js) (Express app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routes"]
  node_app["Express app<br/>[index.js]"]
  node_download["Download route<br/>[download.js]"]
  node_search["Search route<br/>[search.js]"]
end

subgraph group_acquisition["TikTok acquisition"]
  node_photo["Photo extraction<br/>[tiktokPhoto.js]"]
  node_video["Video extraction<br/>[tiktokVideo.js]"]
  node_browser["Browser launcher<br/>[browser.js]"]
end

subgraph group_delivery["Media delivery"]
  node_watch["Watch route<br/>[watch.js]"]
end

subgraph group_internal["Shared internals"]
  node_media["Media helpers<br/>[media.js]"]
  node_crypto["Token crypto<br/>[crypto.js]"]
  node_response["Response helpers<br/>[response.js]"]
end

node_client(("API client"))
node_tiktok["TikTok"]
node_cdn["TikTok media host"]

node_client -->|"requests API"| node_app
node_app -->|"dispatches"| node_download
node_app -->|"dispatches"| node_search
node_app -->|"dispatches"| node_watch
node_download -->|"fetches page"| node_tiktok
node_download -->|"calls for photos"| node_photo
node_download -->|"encodes stream URL"| node_crypto
node_download -->|"formats replies"| node_response
node_photo -->|"creates browser"| node_browser
node_photo -->|"loads item detail"| node_tiktok
node_photo -->|"creates watch link"| node_media
node_browser -->|"browses pages"| node_tiktok
node_search -->|"creates browser"| node_browser
node_search -->|"captures search data"| node_tiktok
node_search -->|"encodes stream URLs"| node_crypto
node_search -->|"creates watch links"| node_watch
node_search -->|"formats replies"| node_response
node_video -->|"fetches page"| node_tiktok
node_video -->|"cleans video item"| node_media
node_media -->|"encodes media URL"| node_crypto
node_watch -->|"decodes token"| node_crypto
node_watch -->|"streams media"| node_cdn
node_watch -->|"formats errors"| node_response

click node_app "https://github.com/frenzy8/tt-dl/blob/main/index.js"
click node_download "https://github.com/frenzy8/tt-dl/blob/main/routes/download.js"
click node_search "https://github.com/frenzy8/tt-dl/blob/main/routes/search.js"
click node_watch "https://github.com/frenzy8/tt-dl/blob/main/routes/watch.js"
click node_photo "https://github.com/frenzy8/tt-dl/blob/main/services/tiktokPhoto.js"
click node_video "https://github.com/frenzy8/tt-dl/blob/main/services/tiktokVideo.js"
click node_browser "https://github.com/frenzy8/tt-dl/blob/main/lib/browser.js"
click node_media "https://github.com/frenzy8/tt-dl/blob/main/lib/media.js"
click node_crypto "https://github.com/frenzy8/tt-dl/blob/main/lib/crypto.js"
click node_response "https://github.com/frenzy8/tt-dl/blob/main/lib/response.js"

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_app,node_download,node_search,node_client toneBlue
class node_photo,node_video,node_browser toneAmber
class node_watch toneMint
class node_media,node_crypto,node_response toneRose
class node_tiktok,node_cdn toneIndigo
```

## Components

### API routes

- [Express app](https://github.com/frenzy8/tt-dl/blob/main/index.js): `index.js`
- [Download route](https://github.com/frenzy8/tt-dl/blob/main/routes/download.js): `routes/download.js`
- [Search route](https://github.com/frenzy8/tt-dl/blob/main/routes/search.js): `routes/search.js`

### TikTok acquisition

- [Photo extraction](https://github.com/frenzy8/tt-dl/blob/main/services/tiktokPhoto.js): `services/tiktokPhoto.js`
- [Video extraction](https://github.com/frenzy8/tt-dl/blob/main/services/tiktokVideo.js): `services/tiktokVideo.js`
- [Browser launcher](https://github.com/frenzy8/tt-dl/blob/main/lib/browser.js): `lib/browser.js`

### Media delivery

- [Watch route](https://github.com/frenzy8/tt-dl/blob/main/routes/watch.js): `routes/watch.js`

### Shared internals

- [Media helpers](https://github.com/frenzy8/tt-dl/blob/main/lib/media.js): `lib/media.js`
- [Token crypto](https://github.com/frenzy8/tt-dl/blob/main/lib/crypto.js): `lib/crypto.js`
- [Response helpers](https://github.com/frenzy8/tt-dl/blob/main/lib/response.js): `lib/response.js`

### Other components

- **API client**
- **TikTok**
- **TikTok media host**

## Connections

- API client → Express app: requests API
- Express app → Download route: dispatches
- Express app → Search route: dispatches
- Express app → Watch route: dispatches
- Download route → TikTok: fetches page
- Download route → Photo extraction: calls for photos
- Download route → Token crypto: encodes stream URL
- Download route → Response helpers: formats replies
- Photo extraction → Browser launcher: creates browser
- Photo extraction → TikTok: loads item detail
- Photo extraction → Media helpers: creates watch link
- Browser launcher → TikTok: browses pages
- Search route → Browser launcher: creates browser
- Search route → TikTok: captures search data
- Search route → Token crypto: encodes stream URLs
- Search route → Watch route: creates watch links
- Search route → Response helpers: formats replies
- Video extraction → TikTok: fetches page
- Video extraction → Media helpers: cleans video item
- Media helpers → Token crypto: encodes media URL
- Watch route → Token crypto: decodes token
- Watch route → TikTok media host: streams media
- Watch route → Response helpers: formats errors