video-downloader/CLAUDE.md

Approach

• Read existing files before writing. Don't re-read unless changed.
• Thorough in reasoning, concise in output.
• Skip files over 100KB unless required.
• No sycophantic openers or closing fluff.
• No emojis or em-dashes.
• Do not guess APIs, versions, flags, commit SHAs, or package names. Verify by reading code or docs before asserting.

Global

• Utilise Docker & Docker-Compose pour la base de données (MariaDB)
• On développe tout en NodeJS notamment avec : NextJS & Prisma pour la partie backend et React pour la partie frontend
• Utilise Tailwind pour le CSS
• Si tu dois utiliser des Workers, gère le avec Passenger (pm2)
• L'application est toujours multilangue (EN, FR, ES, IT — voir messages/)

Application : Ombrora-YTDLP

• Interface web publique permettant de soumettre des URLs de videos a telecharger via yt-dlp, avec pages SEO par plateforme (/[locale]/[slug], ex. /youtube-downloader, definies dans src/lib/downloader-platforms.ts) et une page supported-sites listant tous les sites geres par yt-dlp.
• Avant soumission, l'URL est analysee en temps reel via un probe yt-dlp (POST /api/probe, src/lib/ytdlp-probe.ts, yt-dlp -J) : les options presentees a l'utilisateur (qualite, sous-titres disponibles, decoupe, qualite audio MP3) sont derivees de cette analyse et non d'une liste statique ; la soumission est bloquee tant que le probe n'a pas reussi.
• Les telechargements sont geres via une file d'attente (queue) executee par un worker Node.js (worker/, lance via tsx) supervise par pm2, avec support du multithreading (concurrence configurable via WORKER_CONCURRENCY).
• Chaque telechargement est stocke en base de donnees (MariaDB via Prisma). Aucune entree n'est jamais supprimee : la DB conserve l'historique complet de tous les telechargements (statuts, erreurs, metadata).
• yt-dlp est le zipapp Python officiel (bin/yt-dlp), pas le binaire standalone PyInstaller : ce dernier s'auto-extrait dans /tmp et echoue avec "failed to map segment from shared object" quand /tmp est monte noexec (cas d'o2switch). Le zipapp est toujours invoque explicitement via PYTHON_BIN (src/lib/ytdlp.ts) plutot que via son shebang, car le python3 systeme d'o2switch (3.6) est trop ancien pour yt-dlp (3.10+ requis) — sur o2switch, PYTHON_BIN=/opt/alt/python311/bin/python3.

Deployment (o2switch)

• o2switch is shared hosting: no compiler toolchain, no root access. Any dependency with a native/binary component must ship as a precompiled binary — it cannot be built from source on the server. This is why yt-dlp/ffmpeg/ffprobe ship as precompiled binaries in bin/ (or BIN_DIR) rather than as npm deps.
• Before adding any new dependency with native bindings, confirm it publishes prebuilt binaries for o2switch's platform/arch — otherwise it will fail to install or run there.
• Single Next.js app with a single package.json/node_modules at the repo root — there is no separate frontend build or subfolder to keep in sync. Deployed via cPanel "Setup Node.js App" (Passenger) for the web app; the worker is a separate process that Passenger does not supervise, kept alive by pm2 instead (ecosystem.config.cjs, npm run worker:pm2:*). Full deployment steps (including npm run deploy / scripts/deploy.sh) are documented in README.md.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes or query_graph instead of Grep
• Understanding impact: get_impact_radius instead of manually tracing imports
• Code review: detect_changes + get_review_context instead of reading entire files
• Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool	Use when
detect_changes	Reviewing code changes — gives risk-scored analysis
get_review_context	Need source snippets for review — token-efficient
get_impact_radius	Understanding blast radius of a change
get_affected_flows	Finding which execution paths are impacted
query_graph	Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes	Finding functions/classes by name or keyword
get_architecture_overview	Understanding high-level codebase structure
refactor_tool	Planning renames, finding dead code

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes for code review.
3. Use get_affected_flows to understand impact.
4. Use query_graph pattern="tests_for" to check coverage.