viral-engine

SaaS que convierte un video de YouTube (y, en la próxima etapa, el archivo del creador) en clips verticales 9:16 con subtítulos, copy para redes y scores de viralidad. Español-first; cliente objetivo: podcasters y coaches.

Leer	Para qué
docs/PROYECTO.md	Entendimiento completo: producto, arquitectura, pipeline, datos, API, infra, estado, plan
CONTEXT.md	Glosario del dominio
docs/adr/	Decisiones de arquitectura y por qué
AGENTS.md	Reglas de trabajo para agentes IA (Claude Code, Antigravity, OpenCode)
worker/WORKER.md	Detalle operativo del worker

Arquitectura

Vercel (frontend Next.js)  →  Render (API Express)  →  Supabase (Postgres + Auth; la tabla `jobs` es la cola)
                                                            ↑
                                                   OVH VPS (worker Python, Docker)  →  Cloudflare R2 (clips)

Componente	Carpeta	Runtime	Puerto local
Frontend	frontend/	Node ≥ 20, Next.js 16	3001
API	backend/	Node ≥ 20 (imagen node:20-slim), Express	3000
Worker	worker/	Python 3.12, FFmpeg	— (sondea Supabase cada 3 s)

Desarrollo local (macOS)

Requisitos: Node ≥ 20, uv (instala Python 3.12), FFmpeg, Supabase CLI. Un solo .env en la raíz alimenta API y worker (copiar de .env.example); el frontend usa frontend/.env.local (NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_API_URL). En local usá un proyecto Supabase de desarrollo: un worker local apuntado al Supabase de la beta le roba jobs al del VPS.

# API
cd backend && npm ci && npm run dev
NODE_ENV=test npm test

# Worker
cd worker && uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -r requirements.txt pytest
source .venv/bin/activate && python main.py
ENVIRONMENT=development SUPABASE_URL=https://test.supabase.co SUPABASE_SERVICE_KEY=test \
  OPENROUTER_API_KEY=test OPENAI_API_KEY=test python -m pytest tests/ -q

# Frontend
cd frontend && npm ci && npx next dev -p 3001
npx tsc --noEmit

En una IP residencial (tu Mac) yt-dlp descarga de YouTube sin proxies ni RapidAPI; dejá ENVIRONMENT=development en local. En el VPS (ENVIRONMENT=production) el worker exige RAPIDAPI_KEY y proxies residenciales (proxies.txt).

Base de datos

El esquema se versiona con Supabase CLI (supabase/migrations/, ver ADR 0006): supabase link --project-ref <ref> → supabase db pull (primera vez) → supabase migration new <nombre> → supabase db push. Los SQL históricos aplicados a mano están en supabase/legacy/.

Deploy

• Frontend: Vercel desde main.
• API: Render desde main con render.yaml; variables en el dashboard de Render.
• Worker: .github/workflows/deploy.yml hace SSH al VPS y corre deploy/deploy-worker.sh (git reset --hard origin/main + rebuild de docker-compose.worker.yml). Secrets del repo: VPS_HOST, VPS_USER, VPS_SSH_KEY (clave privada cuyo .pub está en ~/.ssh/authorized_keys del VPS; generar con ssh-keygen -t ed25519 -f ~/.ssh/viralengine_deploy).
• Manual en el VPS: ssh ubuntu@<ip> && cd ~/viralengine && bash deploy/deploy-worker.sh. Solo worker: bash deploy/worker-only.sh. Provisión de un VPS nuevo: deploy/setup-vps.sh. Proxies Webshare: bash deploy/format-proxies.sh proxies-raw.txt > proxies.txt. Logs: bash scripts/worker-logs.sh tail 200.
• Archivos que viven solo en el VPS: .env, proxies.txt, cookies.txt (opcional), worker-logs/.

Salud: GET /health (readiness con Supabase) y GET /health/live en la API.