── The Boomer Dev Docs ← Volver a la app

MEMORIA FUNCIONAL — SocialCutter

Producto: SocialCutter — Procesador de imágenes para redes sociales URL live: https://socialcutter.theboomer.dev Frontend: code/frontend/src/App.tsx (+ components/ImageUploader, PlatformSelector, ProcessingOptions, Results, CreditsDisplay, QuotaBadge, ApiKeysManager, pages/, services/socialcutter.service.ts) Backend: FastAPI (code/src/main.py + src/api/routes/{process,credits,history,apikeys,auth}.py); GridFS/MongoDB; auth Clerk Fuente: Documento generado a partir del código real del frontend y del backend.

1. Introducción

SocialCutter redimensiona y optimiza una imagen de origen para múltiples formatos de redes sociales en una sola operación. El usuario sube una imagen (URL o archivo), selecciona una o varias combinaciones plataforma+formato (con vista previa del ratio de aspecto), ajusta calidad/formato de salida/color de fondo y obtiene una o varias imágenes listas para descargar (individualmente o en ZIP). Incluye autenticación Clerk, sistema de créditos por destino + cuota diaria, historial con las imágenes procesadas, API keys, facturación Stripe y enlace a la documentación de la API (/docs).

UI bilingüe ES/EN (default es) y tema dark/light/system (default dark), persistidos en localStorage.

2. Tipos de usuario

Tipo Acceso
Usuario anónimo Puede procesar 1 imagen/día (localStorage anon_processes + límite IP en backend). Tras el primer proceso se abre el UpgradeDialog.
Usuario registrado (Free) 3 procesos/día (plan free). Badge de cuota usados/límite + CreditsDisplay de créditos diarios.
Usuario Pro / Enterprise Límites mayores según plan (stripe-api); extra_rate para excesos con cargo; API keys disponibles (el gestor de API keys no está restringido a Enterprise en la UI actual).

Regla clave: cada destino (plataforma+formato) consume 1 crédito. Un proceso con 4 destinos cuesta 4 créditos del límite diario (el backend valida y descuenta dest_count créditos).

3. Funcionalidades

F-101 Autenticación con Clerk

F-102 Selección de imagen (URL o archivo)

F-103 Selección de plataformas y formatos

Plataforma Formatos (resolución, ratio)
Instagram post 1080×1080 (1:1) · story 1080×1920 (9:16) · landscape 1080×566 (1.91:1)
Facebook post 1200×630 (1.91:1) · story 1080×1920 (9:16) · cover 820×312 (2.63:1)
X/Twitter post 1200×675 (16:9) · header 1500×500 (3:1)
LinkedIn post 1200×627 (1.91:1) · cover 1128×191 (5.9:1)
YouTube thumbnail 1280×720 (16:9) · banner 2560×1440 (16:9)
TikTok cover 1080×1920 (9:16)

F-104 Opciones de procesamiento

F-105 Procesar imagen

F-106 Resultados y descarga

F-107 Créditos (CreditsDisplay)

F-108 Quota badge (cuota diaria)

F-109 Historial

F-110 API keys

F-111 Facturación (Billing) y Perfil

F-112 Enlace a documentación API

4. Pantallas (wireframes textuales)

P1 — Header

┌──────────────────────────────────────────────────────────────────────────┐
│ [✨ SocialCutter        ]  Generator | Historial | Facturación | Perfil  │
│  Procesador de imágenes │  API                                            │
│  para redes sociales    │            [⚡2/3] [2/3 ⬢free] [👤] [🌙☀️🖥] [ES▾]│
└──────────────────────────────────────────────────────────────────────────┘

P2 — Generator (bento grid 5 columnas)

┌───────────────────────────┬───────────────────────────────────────────────┐
│ [Step 1]                  │ [Step 2]                                      │
│ Seleccionar Imagen        │ Elegir Plataformas                            │
│ (2 cols, min 25vh)        │ (3 cols)                                      │
│                           │ [📸 Instagram][📘 Facebook][🐦 X/Twitter]     │
│ ( ) URL   ( ) Base64/File │ [💼 LinkedIn][▶ YouTube][🎵 TikTok]           │
│ ┌───────────────────────┐ │ ┌──────────┐ ┌──────────┐                     │
│ │ input URL + Use URL   │ │ │ [ratio]  │ │ [ratio]  │                     │
│ │ — o —                 │ │ │ post     │ │ story    │                     │
│ │ zona drag&drop        │ │ │ 1080×1080│ │ 1080×1920│                     │
│ │ [Select File]         │ │ │ 1:1      │ │ 9:16     │                     │
│ └───────────────────────┘ │ └──────────┘ └──────────┘                     │
│ (preview imagen cargada)  │ Selected (2)          ⚡ 2 credits            │
│                           │ [📸post×1080 ✕] [🎵cover×1080 ✕]              │
├───────────────────────────┼───────────────────────────────────────────────┤
│ ┌───────────────────────┐ │ ┌───────────────────────────────────────────┐ │
│ │ Processing Options    │ │ │ [✨ Procesar Imagen]                       │ │
│ │ Quality·Format·Bg     │ │ │ (botón gradiente full-height)             │ │
│ └───────────────────────┘ │ └───────────────────────────────────────────┘ │
└───────────────────────────┴───────────────────────────────────────────────┘
[Error banner rojo si error]

Resultados
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ [preview]     │ │ [preview]     │ │ ...           │
│ Instagram post│ │ TikTok cover  │ │               │
│ 1080 × 1080   │ │ 1080 × 1920   │ │               │
│ 245.3 KB      │ │ 312.1 KB      │ │               │
│ [Download]    │ │ [Download]    │ │               │
└───────────────┘ └───────────────┘ └───────────────┘
               [⬇ Download All (ZIP)]  (si >1 resultado)

P3 — Modal Processing Options

┌────────────────────────────────────────┐
│ ⚙ Processing Options              [×] │
│ Calidad: 85%                          │
│ ────●──────────────────  Smaller file │
│                         Better quality│
│ Formato de salida: [WebP][PNG][JPEG]  │
│ Color de fondo: [🟥][ #000000      ]  │
│ (aviso si color picker abierto)       │
│ [ Done ]                              │
└────────────────────────────────────────┘

P4 — Billing / Profile / History

P5 — UpgradeDialog (modal global)

┌───────────────────────────────┐
│                          [×]  │
│             ✨                │
│   Desbloquea mas procesos     │
│ "Crea una cuenta gratis y     │
│  obten 3 procesos al dia!"    │
│   [G Iniciar sesion con Google]│
└───────────────────────────────┘

5. Flujos de trabajo

Flujo 1 — Anónimo procesa una imagen

  1. Step 1: pega una URL y pulsa "Use URL" (o arrastra un archivo).
  2. Step 2: elige Instagram → tarjeta "post" → aparece chip Selected (1) y "⚡ 1 credit".
  3. (Opcional) Abre Processing Options y ajusta calidad/formato/fondo → Done.
  4. "Procesar Imagen" → spinner → Resultados (1 output) → descarga.
  5. Se abre el UpgradeDialog ("Crea una cuenta gratis y obten 3 procesos al dia!").

Flujo 2 — Usuario registrado procesa multi-formato

  1. Login → header muestra ⚡ 3/3 y QuotaBadge.
  2. Selecciona 2 plataformas + 3 formatos (ej. IG post + IG story + TikTok cover) → "⚡ 3 credits".
  3. Procesa → 3 outputs → "Download All (ZIP)" descarga socialcutter-images.zip.
  4. El historial guarda el job (con processing_time_ms); los créditos se descuentan (3).
  5. Con 1 crédito restante, el badge pasa a ámbar con "Más créditos".

Flujo 3 — Cuota agotada

6. Reglas de negocio

Créditos y cuotas

Validaciones de entrada (backend)

API (endpoints)

Método Endpoint Uso
POST /api/v1/images/process Procesar (source + destinations + options) → {outputs: [{platform, format, url, width, height, size_bytes}]}
POST /api/v1/images/upload Procesar base64 (alternativa)
POST /api/v1/images/upload/file Procesar multipart (file + destinations/options JSON)
POST /api/v1/images/batch Procesar lote de imágenes (no usado por la UI actual)
GET /api/v1/images/{id} Detalle de un job
GET /api/v1/platforms / /api/v1/formats / /api/v1/fit-modes Catálogos
GET /api/v1/credits Resumen de créditos
GET /api/v1/history Historial de procesados
GET/POST/DELETE /api/v1/apikeys[/{id}] Gestión API keys
GET/POST /api/v1/auth/me, /api/v1/auth/sync Perfil y sync Clerk
GET /api/v1/billing/pricing-plans · /summary · /invoices · /credit-packs Billing
POST /api/v1/billing/create-checkout-session · /create-portal-session · /buy-credits Checkout/portal/créditos
GET /api/v1/storage/{file_id} Servir archivos GridFS (Cache-Control 1 año)

Notas técnicas