# theryston/trailers-api architecture

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

- Interactive diagram: https://gitdiagram.com/theryston/trailers-api
- Repository: https://github.com/theryston/trailers-api

## Overview

Trailers API accepts title- or trailer-page-based requests, searches supported streaming catalogs, downloads language-aware trailer media, and stores downloadable results and process status. Its web application exposes request and process views, while the API also documents process lookup, a completed-trailers feed, service listing, Swagger, and webhook support. The sampled backend shows request handling, worker execution, provider implementations, and SQLite persistence; connections for unsampled web and webhook behavior are left unasserted.

Main entry points: [`src/worker.js`](https://github.com/theryston/trailers-api/blob/main/src/worker.js) (Download worker), [`src/index.js`](https://github.com/theryston/trailers-api/blob/main/src/index.js) (HTTP API), [`src/services/index.js`](https://github.com/theryston/trailers-api/blob/main/src/services/index.js) (Provider registry), [`src/services/netflix/index.js`](https://github.com/theryston/trailers-api/blob/main/src/services/netflix/index.js) (Netflix provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and process control"]
  node_api["HTTP API<br/>[index.js]"]
  node_queue["Worker queue<br/>[index.js]"]
  node_worker["Download worker<br/>[worker.js]"]
  node_recovery["Process recovery"]
  node_checker["Startup checker<br/>[check-process.js]"]
  node_webhook["Webhook callbacks<br/>[index.js]"]
end

subgraph group_providers["Trailer providers"]
  node_registry["Provider registry<br/>[index.js]"]
  node_apple["Apple TV provider<br/>[index.js]"]
  node_netflix["Netflix provider<br/>[index.js]"]
  node_prime["Prime Video provider<br/>[index.js]"]
  node_imdb["IMDb provider<br/>[index.js]"]
end

subgraph group_media["Media processing"]
  node_hls["HLS downloader<br/>[download-hls.js]"]
  node_filedownload["File downloader<br/>[download-file.js]"]
  node_transcode["FFmpeg processing<br/>[ffmpeg.js]"]
  node_language["Language matching<br/>[compre-lang.js]"]
  node_subtitle["Subtitle conversion"]
  node_thumbnail["Thumbnail extraction"]
  node_upload["File upload<br/>[upload-file.js]"]
end

subgraph group_persistence["Results and state"]
  node_db[("SQLite database<br/>[index.js]")]
  node_schema["Process and media records<br/>[schema.js]"]
  node_lookup["Process lookup<br/>[find-process.js]"]
  node_status["Status logging<br/>[process-log.js]"]
end

subgraph group_web["Web application"]
  node_site["Web application<br/>[page.tsx]"]
  node_newrequest["New request form<br/>[new.tsx]"]
  node_processview["Process detail view<br/>[content.tsx]"]
  node_fetchers["Data fetchers<br/>[fetchers.ts]"]
  node_hooks["Client hooks<br/>[hooks.ts]"]
end

node_consumer(("API client"))

node_consumer -->|"submits requests"| node_api
node_api -->|"selects providers"| node_registry
node_api -->|"creates processes"| node_db
node_api -->|"reads process"| node_lookup
node_api -.->|"enqueues work"| node_queue
node_queue -->|"runs jobs"| node_worker
node_api -->|"resumes jobs"| node_recovery
node_checker -->|"checks records"| node_db
node_worker -.->|"invokes providers"| node_registry
node_worker -->|"records progress"| node_status
node_worker -->|"extracts thumbnails"| node_thumbnail
node_worker -->|"uploads results"| node_upload
node_worker -->|"stores trailers"| node_db
node_worker -->|"writes records"| node_schema
node_registry -->|"registers provider"| node_apple
node_registry -->|"registers provider"| node_netflix
node_registry -->|"registers provider"| node_prime
node_registry -->|"registers provider"| node_imdb
node_apple -->|"downloads streams"| node_hls
node_netflix -->|"downloads media"| node_filedownload
node_netflix -->|"merges tracks"| node_transcode
node_netflix -->|"matches language"| node_language
node_netflix -->|"converts subtitles"| node_subtitle
node_prime -->|"downloads media"| node_filedownload
node_prime -->|"matches language"| node_language
node_prime -->|"converts subtitles"| node_subtitle
node_hls -->|"downloads segments"| node_filedownload
node_hls -->|"merges tracks"| node_transcode
node_hls -->|"matches language"| node_language
node_thumbnail -->|"extracts image"| node_transcode
node_lookup -->|"queries records"| node_db
node_lookup -->|"reads entities"| node_schema
node_status -->|"updates status"| node_db
node_status -->|"loads process"| node_lookup
node_site -.->|"renders form"| node_newrequest
node_processview -.->|"loads process data"| node_fetchers
node_hooks -->|"uses fetchers"| node_fetchers

click node_api "https://github.com/theryston/trailers-api/blob/main/src/index.js"
click node_queue "https://github.com/theryston/trailers-api/blob/main/src/index.js"
click node_worker "https://github.com/theryston/trailers-api/blob/main/src/worker.js"
click node_recovery "https://github.com/theryston/trailers-api/blob/main/src/continue-process.js"
click node_checker "https://github.com/theryston/trailers-api/blob/main/src/check-process.js"
click node_webhook "https://github.com/theryston/trailers-api/blob/main/src/index.js"
click node_registry "https://github.com/theryston/trailers-api/blob/main/src/services/index.js"
click node_apple "https://github.com/theryston/trailers-api/blob/main/src/services/appleTv/index.js"
click node_netflix "https://github.com/theryston/trailers-api/blob/main/src/services/netflix/index.js"
click node_prime "https://github.com/theryston/trailers-api/blob/main/src/services/primeVideo/index.js"
click node_imdb "https://github.com/theryston/trailers-api/blob/main/src/services/imdb/index.js"
click node_hls "https://github.com/theryston/trailers-api/blob/main/src/utils/download-hls.js"
click node_filedownload "https://github.com/theryston/trailers-api/blob/main/src/utils/download-file.js"
click node_transcode "https://github.com/theryston/trailers-api/blob/main/src/utils/ffmpeg.js"
click node_language "https://github.com/theryston/trailers-api/blob/main/src/utils/compre-lang.js"
click node_subtitle "https://github.com/theryston/trailers-api/blob/main/src/utils/subtitle-xml-to-vtt.js"
click node_thumbnail "https://github.com/theryston/trailers-api/blob/main/src/extract-thumbnail.js"
click node_upload "https://github.com/theryston/trailers-api/blob/main/src/upload-file.js"
click node_db "https://github.com/theryston/trailers-api/blob/main/src/db/index.js"
click node_schema "https://github.com/theryston/trailers-api/blob/main/src/db/schema.js"
click node_lookup "https://github.com/theryston/trailers-api/blob/main/src/db/find-process.js"
click node_status "https://github.com/theryston/trailers-api/blob/main/src/utils/process-log.js"
click node_site "https://github.com/theryston/trailers-api/blob/main/web/app/page.tsx"
click node_newrequest "https://github.com/theryston/trailers-api/blob/main/web/components/new.tsx"
click node_processview "https://github.com/theryston/trailers-api/blob/main/web/app/process/%5Bid%5D/content.tsx"
click node_fetchers "https://github.com/theryston/trailers-api/blob/main/web/lib/fetchers.ts"
click node_hooks "https://github.com/theryston/trailers-api/blob/main/web/lib/hooks.ts"

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_api,node_queue,node_worker,node_recovery,node_checker,node_webhook,node_consumer toneBlue
class node_registry,node_apple,node_netflix,node_prime,node_imdb toneAmber
class node_hls,node_filedownload,node_transcode,node_language,node_subtitle,node_thumbnail,node_upload toneMint
class node_db,node_schema,node_lookup,node_status toneRose
class node_site,node_newrequest,node_processview,node_fetchers,node_hooks toneIndigo
```

## Components

### API and process control

- [HTTP API](https://github.com/theryston/trailers-api/blob/main/src/index.js): `src/index.js`
- [Worker queue](https://github.com/theryston/trailers-api/blob/main/src/index.js): `src/index.js`
- [Download worker](https://github.com/theryston/trailers-api/blob/main/src/worker.js): `src/worker.js`
- [Process recovery](https://github.com/theryston/trailers-api/blob/main/src/continue-process.js): `src/continue-process.js`
- [Startup checker](https://github.com/theryston/trailers-api/blob/main/src/check-process.js): `src/check-process.js`
- [Webhook callbacks](https://github.com/theryston/trailers-api/blob/main/src/index.js): `src/index.js`

### Trailer providers

- [Provider registry](https://github.com/theryston/trailers-api/blob/main/src/services/index.js): `src/services/index.js`
- [Apple TV provider](https://github.com/theryston/trailers-api/blob/main/src/services/appleTv/index.js): `src/services/appleTv/index.js`
- [Netflix provider](https://github.com/theryston/trailers-api/blob/main/src/services/netflix/index.js): `src/services/netflix/index.js`
- [Prime Video provider](https://github.com/theryston/trailers-api/blob/main/src/services/primeVideo/index.js): `src/services/primeVideo/index.js`
- [IMDb provider](https://github.com/theryston/trailers-api/blob/main/src/services/imdb/index.js): `src/services/imdb/index.js`

### Media processing

- [HLS downloader](https://github.com/theryston/trailers-api/blob/main/src/utils/download-hls.js): `src/utils/download-hls.js`
- [File downloader](https://github.com/theryston/trailers-api/blob/main/src/utils/download-file.js): `src/utils/download-file.js`
- [FFmpeg processing](https://github.com/theryston/trailers-api/blob/main/src/utils/ffmpeg.js): `src/utils/ffmpeg.js`
- [Language matching](https://github.com/theryston/trailers-api/blob/main/src/utils/compre-lang.js): `src/utils/compre-lang.js`
- [Subtitle conversion](https://github.com/theryston/trailers-api/blob/main/src/utils/subtitle-xml-to-vtt.js): `src/utils/subtitle-xml-to-vtt.js`
- [Thumbnail extraction](https://github.com/theryston/trailers-api/blob/main/src/extract-thumbnail.js): `src/extract-thumbnail.js`
- [File upload](https://github.com/theryston/trailers-api/blob/main/src/upload-file.js): `src/upload-file.js`

### Results and state

- [SQLite database](https://github.com/theryston/trailers-api/blob/main/src/db/index.js): `src/db/index.js`
- [Process and media records](https://github.com/theryston/trailers-api/blob/main/src/db/schema.js): `src/db/schema.js`
- [Process lookup](https://github.com/theryston/trailers-api/blob/main/src/db/find-process.js): `src/db/find-process.js`
- [Status logging](https://github.com/theryston/trailers-api/blob/main/src/utils/process-log.js): `src/utils/process-log.js`

### Web application

- [Web application](https://github.com/theryston/trailers-api/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [New request form](https://github.com/theryston/trailers-api/blob/main/web/components/new.tsx): `web/components/new.tsx`
- [Process detail view](https://github.com/theryston/trailers-api/blob/main/web/app/process/%5Bid%5D/content.tsx): `web/app/process/[id]/content.tsx`
- [Data fetchers](https://github.com/theryston/trailers-api/blob/main/web/lib/fetchers.ts): `web/lib/fetchers.ts`
- [Client hooks](https://github.com/theryston/trailers-api/blob/main/web/lib/hooks.ts): `web/lib/hooks.ts`

### Other components

- **API client**

## Connections

- API client → HTTP API: submits requests (evidence: `src/index.js`)
- HTTP API → Provider registry: selects providers (evidence: `src/index.js`)
- HTTP API → SQLite database: creates processes (evidence: `src/index.js`)
- HTTP API → Process lookup: reads process (evidence: `src/index.js`)
- HTTP API → Worker queue: enqueues work (evidence: `src/index.js`)
- Worker queue → Download worker: runs jobs (evidence: `src/index.js`)
- HTTP API → Process recovery: resumes jobs (evidence: `src/index.js`)
- Startup checker → SQLite database: checks records (evidence: `src/check-process.js`)
- Download worker → Provider registry: invokes providers
- Download worker → Status logging: records progress (evidence: `src/worker.js`)
- Download worker → Thumbnail extraction: extracts thumbnails (evidence: `src/worker.js`)
- Download worker → File upload: uploads results (evidence: `src/worker.js`)
- Download worker → SQLite database: stores trailers (evidence: `src/worker.js`)
- Download worker → Process and media records: writes records (evidence: `src/worker.js`)
- Provider registry → Apple TV provider: registers provider (evidence: `src/services/index.js`)
- Provider registry → Netflix provider: registers provider (evidence: `src/services/index.js`)
- Provider registry → Prime Video provider: registers provider (evidence: `src/services/index.js`)
- Provider registry → IMDb provider: registers provider (evidence: `src/services/index.js`)
- Apple TV provider → HLS downloader: downloads streams (evidence: `src/services/appleTv/index.js`)
- Netflix provider → File downloader: downloads media (evidence: `src/services/netflix/index.js`)
- Netflix provider → FFmpeg processing: merges tracks (evidence: `src/services/netflix/index.js`)
- Netflix provider → Language matching: matches language (evidence: `src/services/netflix/index.js`)
- Netflix provider → Subtitle conversion: converts subtitles (evidence: `src/services/netflix/index.js`)
- Prime Video provider → File downloader: downloads media (evidence: `src/services/primeVideo/index.js`)
- Prime Video provider → Language matching: matches language (evidence: `src/services/primeVideo/index.js`)
- Prime Video provider → Subtitle conversion: converts subtitles (evidence: `src/services/primeVideo/index.js`)
- HLS downloader → File downloader: downloads segments (evidence: `src/utils/download-hls.js`)
- HLS downloader → FFmpeg processing: merges tracks (evidence: `src/utils/download-hls.js`)
- HLS downloader → Language matching: matches language (evidence: `src/utils/download-hls.js`)
- Thumbnail extraction → FFmpeg processing: extracts image (evidence: `src/extract-thumbnail.js`)
- Process lookup → SQLite database: queries records (evidence: `src/db/find-process.js`)
- Process lookup → Process and media records: reads entities (evidence: `src/db/find-process.js`)
- Status logging → SQLite database: updates status (evidence: `src/utils/process-log.js`)
- Status logging → Process lookup: loads process (evidence: `src/utils/process-log.js`)
- Web application → New request form: renders form
- Process detail view → Data fetchers: loads process data
- Client hooks → Data fetchers: uses fetchers (evidence: `web/lib/hooks.ts`)