Behind the Scenes (Architecture)

For the curious developers, this page explains how ClipCookBook works under the hood.

Frontend & Backend

The core of the application is built with Next.js (App Router). This allows us to seamlessly build React components and server-side API routes (Route Handlers) on the same platform. We use Bun as the runtime and package manager for optimal speed.

  • Styling: Handled by Tailwind CSS for sleek and consistent components.
  • Data Storage: Prisma is chosen as the ORM. It communicates with a local SQLite database to keep infrastructure requirements (and costs!) minimal for self-hosting.

How Extraction Works

When a user submits a URL:

  1. The Next.js API route accepts the URL.
  2. yt-dlp extracts metadata and downloads media, using Netscape cookies when configured (especially for Instagram).
  3. If Instagram auth fails, a public embed fallback may still provide caption and thumbnail so a recipe can be saved without video.
  4. If needed, ffmpeg converts video to a suitable format for analysis.
  5. With PROCESS_METHOD=ai, Google Gemini analyzes text and/or video (Deep Search / short captions skip straight to video). The default model is gemini-3.5-flash (GEMINI_MODEL overrides). Failures throw clearly — there is no silent heuristic fallback in AI mode.
  6. The AI output is parsed and, together with links to local video files, stored via Prisma for the frontend.

yt-dlp Maintenance

By default the app can update the yt-dlp binary on a nightly schedule (and optionally at startup). See the YT_DLP_AUTO_UPDATE* variables in Installation.

Alerts

SMTP is used for recipe sharing and for operational alerts (backup failures, missing media, expired cookies) when SMTP_ALERT_TO is set.