Skip to main content

Architecture Overview

Vylux is not a collection of shell scripts. It is a single binary backed by shared infrastructure: an HTTP server, a queue worker, PostgreSQL, Redis, S3-compatible storage, and the FFmpeg / libvips / Shaka Packager toolchain.

Runtime roles​

The same vylux binary currently supports three modes:

  • all: run the HTTP server and worker together, useful for local development and minimal deployments
  • server: run only the HTTP server, synchronous image delivery, playback proxying, and primary metrics
  • worker: run only the queue consumer and expose /metrics and /healthz on WORKER_METRICS_PORT

This keeps the implementation model unified while still allowing separate server and worker deployments.

System structure​

Components and boundaries​

ComponentResponsibility
HTTP serverserves /img, /original, /thumb, /api/jobs, /stream, /api/key, /healthz, /readyz, and /metrics
Workerconsumes async jobs, downloads source media, runs cover / preview / transcode workflows, and sends webhooks
PostgreSQLstores job rows, workflow results, retry metadata, wrapped content keys, and image cache tracking
Redisbacks asynq queues, task state, and API/key endpoint rate limiting
Source storesource bucket plus SOURCE_S3_*; immutable or upstream-managed source objects; Vylux reads from it
Media storemedia bucket plus MEDIA_S3_*; derived images, previews, covers, playlists, segments, and caches; Vylux reads and writes it
Media toolchainvips for images, FFmpeg / ffprobe for video, Shaka Packager for HLS CMAF packaging

HTTP server responsibilities​

  • /img real-time image processing
  • /original signed source-object proxying
  • /thumb signed reads of already-generated image assets
  • /api/jobs job creation and lookup
  • /stream/{hash}/* HLS asset proxying
  • /api/key/{hash} Bearer-token validation and 16-byte key delivery
  • /healthz, /readyz, and /metrics

The HTTP side also owns:

  • request tracing middleware and X-Trace-ID
  • Prometheus HTTP metrics
  • readiness checks
  • API key auth and Redis-backed rate limiting

Worker responsibilities​

  • download source media
  • generate cover, preview, and transcode outputs
  • generate encrypted HLS CMAF when requested
  • upload derived artifacts
  • persist status, progress, and results JSON
  • produce machine-readable workflow results and retry plans when needed
  • deliver success or failure webhooks

The worker does not only run video:transcode. Supported job types today are:

  • image:thumbnail
  • video:cover
  • video:preview
  • video:transcode
  • video:full

video:full is a single workflow handler that downloads the source once and coordinates cover, preview, and transcode stages within one task.

Queue model​

Vylux uses asynq with three named queues:

QueueWeightPurpose
critical6fast tasks such as image:thumbnail
default3normal video jobs
video:large1lower-priority large transcode work

For video jobs, the POST /api/jobs path performs a source-storage preflight check, measures the actual source size, and can route large work to video:large before enqueueing.

Shared state​

  • PostgreSQL stores jobs, results, and wrapped keys
  • Redis stores queue state and rate limits
  • source and media stores hold original and derived media assets

What Vylux does not do​

Vylux is intentionally narrow in scope:

  • it transforms media
  • it exposes playback and management APIs
  • it does not replace upstream authorization or content management systems

Your upstream application is still responsible for deciding who can submit jobs, who can receive signed URLs, and who is allowed to obtain playback tokens.