── The Boomer Dev Docs ← Volver a la app

MEMORIA FUNCIONAL — ThumbnailGen

Producto: ThumbnailGen — Generador de thumbnails con IA URL live: https://thumbnailgen.theboomer.dev Frontend: code/frontend/src/App.tsx (+ pages/, components/, services/, stores/, hooks/) Backend: FastAPI (/api/v1/thumbnail/*); auth Clerk; billing vía tentpole-stripe-api Fuente: Documento generado a partir del código real del frontend (App.tsx, QuotaBadge, UpgradeDialog, Billing, Profile, History, PlanCard, usePermissions, stripe.service) y el spec docs/03-MEMORIA_FUNCIONAL.md.

1. Introducción

ThumbnailGen es una aplicación web SPA (React + Vite + Tailwind + Clerk) que genera thumbnails para vídeo usando IA. El usuario describe el tema de su vídeo, elige plataforma, estilo visual y tipo de contenido, y el sistema devuelve una imagen PNG lista para descargar. Incluye autenticación (Clerk), cuotas diarias por plan, historial de generaciones, facturación con Stripe (suscripciones + paquetes de créditos) y gestión de API keys (solo Enterprise).

El idioma de la UI es configurable (ES/EN, default es) y el tema visual (dark/light/system, default dark), ambos persistidos en localStorage.

2. Tipos de usuario

Tipo Cómo se identifica Acceso
Usuario anónimo No autenticado (SignedOut) Puede generar 1 thumbnail/día (control por localStorage anon_thumbnails en frontend + IP en backend). Tras la 1ª generación se muestra el diálogo de upgrade.
Usuario registrado (Free) Sesión Clerk (SignedIn) 3 thumbnails/día (límite del plan free). Badge de cuota usados/límite en el header.
Usuario Pro Suscripción Stripe activa 50 thumbnails/día (según límites del plan devueltos por stripe-api).
Usuario Enterprise Suscripción Enterprise Ilimitado + API keys con IP whitelist (gestión exclusiva de este plan).

Nota: el backend consulta el plan del usuario a stripe-api (/api/v1/billing/internal/plan/{clerk_id}) y aplica límites diarios por plan; el frontend muestra la cuota aproximada en el QuotaBadge usando localStorage('usage_log') + los límites del plan.

3. Funcionalidades

F-101 Autenticación con Clerk

F-102 Cambio de idioma (ES/EN)

F-103 Tema visual (dark / light / system)

F-104 Generación de thumbnail

F-105 Descargar thumbnail

F-106 Crear nuevo thumbnail

F-107 Upgrade dialog para anónimos

F-108 Quota badge

F-109 Historial (inline en Generator + página History)

F-110 Planes y suscripción (Billing)

F-111 Perfil de usuario

4. Pantallas (wireframes textuales)

P1 — Header (común a todas las vistas)

┌────────────────────────────────────────────────────────────────────────────┐
│ [🖼 ThumbnailGen        ]  Generator | Historial | Perfil | Facturación    │
│  Generador de thumbnails│                                        [2/3 ⬢free]│
│  con IA                 │  [👤] [🌙☀️🖥] [EN ▾]  ó  [Iniciar sesión]       │
└────────────────────────────────────────────────────────────────────────────┘

P2 — Generator (vista principal, grid 3 columnas)

┌───────────────┬────────────────────────────────────────────────────────────┐
│ Configuración │  [Error banner rojo si error]                              │
│               │  [Loading: spinner + "Esto puede tardar unos segundos"]    │
│ Tema          │  ┌──────────────────────────┐                              │
│ textarea      │  │ Thumbnail Generado       │  ← panel resultado          │
│ (¿De qué trata│  │ [imagen PNG full-width]  │     (solo si result)        │
│  tu video?)   │  │ [Descargar] [Crear Nuevo]│                              │
│               │  └──────────────────────────┘                              │
│ Plataforma    │  ┌──────────────────────────┐                              │
│ [▶ YouTube]   │  │ Sin thumbnail generado   │  ← estado vacío inicial     │
│ [📷 Instagram]│  │ Configura los parámetros │     (solo si !result)       │
│ [🎵 TikTok]   │  │ y pulsa "Generar..."     │                              │
│ [💬 X/Twitter]│  └──────────────────────────┘                              │
│               │  ┌──────────────────────────┐                              │
│ Estilo Visual │  │ Historial                │                              │
│ pills:        │  │ [Thumb] tema1 · youtube  │  ← últimos 10 items        │
│ profesional,  │  │ [Thumb] tema2 · instagram│     o "Sin thumbnails aún"  │
│ gaming, ...   │  └──────────────────────────┘                              │
│               │                                                             │
│ Tipo contenido│                                                             │
│ pills:        │                                                             │
│ tutorial, ... │                                                             │
│               │                                                             │
│ [✨ Generar    │                                                             │
│  Thumbnail]   │                                                             │
└───────────────┴────────────────────────────────────────────────────────────┘

P3 — Billing (Facturación)

← Volver al Generador
Facturación — Gestiona tu suscripción y facturación   [🔗 Gestionar facturación si suscripción]

┌─────────────────────────────────────────┐
│ Tu Plan                                  │
│ Suscrito a: Pro [Activo]                 │
│ Fecha de renovación: 05 sep 2026         │
│ (aviso ámbar si cancelAtPeriodEnd)       │
│ 9,00 €/month                             │
│ — o — "Sin suscripción activa"           │
└─────────────────────────────────────────┘

Planes de Precios
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Free          │ │ Pro           │ │ Enterprise    │
│ Gratis        │ │ 9,00 €/mes    │ │ 29,00 €/mes   │
│ ✓ 3 thumbnails│ │ ✓ 50 thumbnails│ │ ✓ Ilimitado  │
│   diarios     │ │ ...           │ │ ...           │
│ [Suscribirse] │ │ [Suscribirse] │ │ [Suscribirse] │
└───────────────┘ └───────────────┘ └───────────────┘

Paquetes de Créditos — Créditos Extra
┌────────────┐ ┌────────────┐ ┌────────────┐
│ 1.000      │ │ 5.000      │ │ 10.000     │
│ créditos   │ │ créditos   │ │ créditos   │
│ €9,99      │ │ €39,99     │ │ €69,99     │
│ [Comprar]  │ │ [Comprar]  │ │ [Comprar]  │
└────────────┘ └────────────┘ └────────────┘

Historial de Facturas
┌───────────┬──────────┬────────┬───────┬──────┐
│ Factura # │ Fecha    │ Importe│ Estado│      │
│ inv_...   │ 05 ago   │ 9,00 € │ Paid  │ [Ver]│
└───────────┴──────────┴────────┴───────┴──────┘
  (o "Sin facturas aún")

P4 — Profile (Perfil)

← Volver al Generador
Perfil — Gestiona la configuración de tu cuenta

┌─────────────────────────────────────────────┐
│ Información del Usuario                     │
│ [avatar] Nombre Apellidos                   │
│          email@example.com                  │
│ Nombre: X · Email: X · Miembro desde: X    │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ Plan y Uso                                  │
│ Plan: FREE · Límite diario: 3 · Usados: 1   │
│ Restantes: 2 (verde) · Créditos Extra: X    │
│ Acceso API: Activado / No disponible        │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ Claves API (Enterprise only)                │
│ ┌─ si NO enterprise ─────────────────────┐  │
│ │ 🛡 Actualiza a Enterprise              │  │
│ │ "La gestión de claves API está ..."    │  │
│ │ [Ver Planes]                           │  │
│ └────────────────────────────────────────┘  │
│ ┌─ si enterprise ────────────────────────┐  │
│ │ [➕ Generar Clave API]                 │  │
│ │ (form: nombre + Generar + ×)          │  │
│ │ [clave nueva visible una vez 🟢]      │  │
│ │ Lista: nombre · creada · último uso   │  │
│ │        [copiar] [revocar]             │  │
│ │ Lista Blanca de IPs: input + Guardar  │  │
│ └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

P5 — History (Historial)

← Volver
Historial de Contenido — Tu contenido generado anteriormente
[🔍 Buscar por tema...]
(siempre estado vacío en la implementación actual: "Aún no has generado contenido")

P6 — UpgradeDialog (modal global)

┌───────────────────────────────┐
│                          [×]  │
│             ✨                │
│   Desbloquea mas thumbnails   │
│ "Crea una cuenta gratis y     │
│  obten 3 thumbnails al dia!"  │
│   [G Iniciar sesion con Google]│
└───────────────────────────────┘
(backdrop blur; clic fuera cierra)

5. Flujos de trabajo

Flujo 1 — Anónimo genera su primer thumbnail

  1. Entra a la app (estado vacío, botón "Iniciar sesión" en header).
  2. Rellena Tema, elige plataforma/estilo/tipo y pulsa "Generar Thumbnail".
  3. Ve el spinner ("Esto puede tardar unos segundos") y luego el resultado con "Descargar".
  4. incrementAnonThumbnails() → se abre el UpgradeDialog ("Crea una cuenta gratis...").
  5. Opción A: cierra el diálogo → ha gastado su generación del día (el contador anon_thumbnails persiste por día; el backend limita a 1/día por IP).
  6. Opción B: "Iniciar sesión con Google" → modal Clerk → pasa a autenticado (Free, 3/día).

Flujo 2 — Registrado Free genera y descarga

  1. Login Clerk → header muestra QuotaBadge 0/3, badge "Gratis" y avatar.
  2. Configura y genera → resultado visible; QuotaBadge pasa a 1/3 (localStorage usage_log).
  3. Descarga PNG (thumbnail-{id}.png) o pulsa "Crear Nuevo".
  4. El panel Historial se actualiza con el nuevo item.
  5. Al agotar el límite, el backend responde 429 quota_exceeded → banner de error; clic en QuotaBadge → Billing para hacer upgrade.

Flujo 3 — Upgrade a Pro/Enterprise

  1. Pestaña Facturación → "Planes de Precios".
  2. "Suscribirse" en un plan → checkout de Stripe → pago → webhook actualiza el plan.
  3. De vuelta, "Tu Plan" muestra la suscripción activa; QuotaBadge muestra el nuevo límite diario.
  4. Enterprise adicionalmente desbloquea la sección de API keys en Perfil (generar → copiar una sola vez → usar en integraciones; whitelist de IPs).

6. Reglas de negocio

Cuotas y límites (back-end vía stripe-api; frontend como referencia)

Usuario Límite diario Control
Anónimo 1 thumbnail/día IP (backend) + localStorage('anon_thumbnails') (frontend)
Free 3 thumbnails/día plan.limits.daily_captions (stripe-api); usage_log en frontend
Pro 50 thumbnails/día idem
Enterprise Ilimitado idem

Validaciones de entrada

API (endpoints usados por el frontend)

Método Endpoint Uso
POST /api/v1/thumbnail/generate Generar (body: {description, template_id, text}) → {id, image_b64, download_url}
GET /api/v1/thumbnail/list Listar historial → {items: [{id, template_name, platform, ...}]}
GET /api/v1/billing/pricing-plans Planes (con limits.daily_captions, max_characters, languages, has_api, ai_model, extra_rate)
GET /api/v1/billing/summary Resumen suscripción + bonus_credits_remaining
GET /api/v1/billing/invoices Facturas
POST /api/v1/billing/create-checkout-session Checkout Stripe
POST /api/v1/billing/create-portal-session Portal Stripe
GET /api/v1/billing/credit-packs Paquetes de créditos
POST /api/v1/billing/buy-credits Comprar créditos (redirect a Stripe)
GET/POST /api/v1/auth/me, /api/v1/auth/sync Perfil y sync Clerk→Mongo
GET/POST/DELETE /api/v1/api-keys* Gestión API keys (Enterprise)

Facturación

Notas técnicas