ProductScribe AI — Explainer

Concepto

ProductScribe AI elimina el cuello de botella de creación de contenido para equipos de e-commerce. Dado el nombre de un producto, sus atributos clave y palabras clave objetivo, el sistema genera múltiples variantes de descripciones optimizadas para SEO en diferentes tonos (profesional, persuasivo, casual, técnico) mediante un LLM externo — todo en segundos, no horas.

Propuesta de valor principal: reducir el tiempo de escritura de descripciones de ~20 min a <10 s, con texto de mayor calidad, consistente y orientado a conversión.

---

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                         Cliente HTTP                            │
│            (Postman / Frontend React / Shopify Plugin)          │
└───────────────────────────┬─────────────────────────────────────┘
                            │ REST JSON
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Spring Boot 4.0.4 / Java 25                  │
│                                                                 │
│  ┌──────────────┐   ┌──────────────────────────────────────┐    │
│  │ AuthController│   │       DescriptionController          │    │
│  │  /api/v1/auth│   │     /api/v1/descriptions             │    │
│  └──────┬───────┘   └──────────────┬───────────────────────┘    │
│         │                          │                            │
│  ┌──────▼───────┐   ┌──────────────▼───────────────────────┐    │
│  │  AuthService │   │    DescriptionGeneratorService        │    │
│  └──────┬───────┘   │  ┌──────────────────────────────┐    │    │
│         │           │  │  Virtual Thread Pool          │    │    │
│         │           │  │  (1 thread per tone)          │    │    │
│         │           │  └──────────┬───────────────────┘    │    │
│         │           └────────────-│────────────────────────┘    │
│         │                         │                             │
│  ┌──────▼─────────────────────────▼───────────────────────┐     │
│  │               JPA Repositories (H2 / PostgreSQL)        │     │
│  │  UserRepository · ProductInputRepository               │     │
│  │  GeneratedDescriptionRepository                        │     │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌────────────────────────────────────────────────────────┐     │
│  │          Spring Cloud OpenFeign — LlmClient            │     │
│  │     POST /v1/chat/completions (OpenAI-compatible)      │     │
│  └───────────────────────────┬────────────────────────────┘     │
└──────────────────────────────│──────────────────────────────────┘
                               │ HTTPS + Bearer token
                               ▼
                    ┌─────────────────────┐
                    │  External LLM API   │
                    │ (OpenAI / Groq /    │
                    │  Mistral / Ollama)  │
                    └─────────────────────┘

Capas

Capa	Paquete	Responsabilidad
Controller	controller/	HTTP in/out, validación de entrada, mapeo a DTOs
Service	service/	Lógica de negocio, virtual threads, prompts LLM
Repository	repository/	JPA queries, acceso a datos
Model	%%INLINE3%%	Entidades JPA (%%INLINE4%%, %%INLINE5%%, %%INLINE6%%)
DTO	dto/	Java Records inmutables para API request/response
Client	client/	Feign interface + DTOs OpenAI-compatible
Security	%%INLINE9%%	JWT filter, %%INLINE10%% impl
Config	%%INLINE11%%	%%INLINE12%%, %%INLINE13%%, %%INLINE14%%, JacksonConfig

Decisiones técnicas destacadas

• Virtual Threads (Executors.newVirtualThreadPerTaskExecutor()): cada tono dispara una llamada

al LLM en su propio virtual thread. Sin bloquear carrier threads, el throughput de I/O es máximo.

• Java 25 Records para todos los DTOs: inmutables, %%INLINE17%%/%%INLINE18%%/hashCode automáticos.
• Pattern matching %%INLINE20%% en %%INLINE21%% y userPrompt() — código conciso y exhaustivo.
• %%INLINE23%% en %%INLINE24%% rompe el ciclo de dependencias Spring Security.
• Mock LLM integrado: cuando app.llm.api-key=mock-key (defecto dev) se devuelven descripciones

realistas sin consumir créditos de API.

• %%INLINE26%% para H2 en dev — %%INLINE27%% base no se modifica.

---

Entidades JPA

app_users
  id BIGINT PK, email VARCHAR UNIQUE, password VARCHAR,
  name VARCHAR, role VARCHAR, created_at TIMESTAMP

product_inputs
  id BIGINT PK, product_name VARCHAR, key_attributes TEXT,
  target_keywords TEXT, created_at TIMESTAMP, user_id FK

generated_descriptions
  id BIGINT PK, content TEXT, tone VARCHAR,
  generated_at TIMESTAMP, product_input_id FK

---

Endpoints REST

Auth (público)

Método	Ruta	Body	Respuesta
%%INLINE28%%	%%INLINE29%%	%%INLINE30%%	%%INLINE31%% 201
%%INLINE32%%	%%INLINE33%%	%%INLINE34%%	%%INLINE35%% 200

Descripciones (requieren Authorization: Bearer <token>)

Método	Ruta	Descripción
%%INLINE37%%	%%INLINE38%%	Genera variantes para un producto
%%INLINE39%%	%%INLINE40%%	Dashboard — historial del usuario
%%INLINE41%%	%%INLINE42%%	Edita (refina) una descripción existente
%%INLINE43%%	%%INLINE44%%	Exporta como texto plano (descarga)

Ejemplo: generar descripciones

POST /api/v1/descriptions/generate
Authorization: Bearer eyJhbGc...
Content-Type: application/json

{
  "productName": "Auriculares Bluetooth Pro X200",
  "keyAttributes": "Cancelación activa de ruido, 30h batería, drivers de 40mm, plegables",
  "targetKeywords": ["auriculares bluetooth", "noise cancelling", "auriculares gaming"],
  "tones": ["PROFESSIONAL", "PERSUASIVE", "CASUAL"]
}

HTTP/1.1 201 Created
{
  "productInputId": 1,
  "productName": "Auriculares Bluetooth Pro X200",
  "generatedAt": "2026-05-01T12:00:00Z",
  "variants": [
    {
      "id": 1,
      "tone": "PROFESSIONAL",
      "content": "Introducing Auriculares Bluetooth Pro X200 — engineered for..."
    },
    {
      "id": 2,
      "tone": "PERSUASIVE",
      "content": "Transform your audio experience with the Pro X200! Imagine..."
    },
    {
      "id": 3,
      "tone": "CASUAL",
      "content": "Hey, looking for auriculares bluetooth? You've found it!..."
    }
  ]
}

---

Análisis de Negocio

Mercado objetivo

• Gerentes de e-commerce en Shopify, MercadoLibre, Amazon.
• Agencias de marketing digital que gestionan múltiples catálogos.
• Pymes con catálogos de >50 SKUs.

Propuesta de valor

Antes	Con ProductScribe AI
20 min/descripción manual	<10 s generación automática
Textos inconsistentes	Tono controlado por parámetro
Sin SEO estratégico	Keywords integradas en el texto
Costo copywriter ~$50/h	Fracción del costo en créditos LLM

Monetización (SaaS por niveles)

Plan	Precio/mes	Descripciones/mes	Tonos	Exportación
Free	$0	20	2	Copy manual
Basic	$29	200	4	CSV / TXT
Pro	$99	Ilimitadas	4 + custom	API + Shopify plugin

ROI estimado: 1 copywriter full-time (~$3.000/mes) ≈ 3.000 descripciones/mes. Plan Pro → $99/mes para las mismas 3.000 desc. = 97% ahorro en contenido.

Ruta al mercado

1. MVP (este repo): API + mock LLM → validar propuesta.
2. Beta: conectar OpenAI real, añadir UI web (React/Next.js).
3. v1.0: plugin Shopify, multi-idioma, bulk import CSV.
4. v2.0: fine-tuning por industria (moda, electrónica, alimentos).

---

Cómo ejecutar

Requisitos previos

• Java 25+
• Maven 3.9+

Arrancar en modo dev (H2 in-memory, LLM mock)

cd solutions/2026-05-01-product-scribe-ai
mvn spring-boot:run

La API queda disponible en http://localhost:8080.

Con LLM real (OpenAI)

LLM_API_KEY=sk-... mvn spring-boot:run

O añadir al entorno:

export LLM_API_KEY=sk-...
export APP_LLM_MODEL=gpt-4o
mvn spring-boot:run

Con PostgreSQL (producción)

mvn spring-boot:run \
  -Dspring-boot.run.profiles=prod \
  -Dspring.datasource.url=jdbc:postgresql://localhost:5432/productscribedb \
  -Dspring.datasource.username=ps_user \
  -Dspring.datasource.password=secret \
  -DLLM_API_KEY=sk-...

Compilar y empaquetar

mvn clean package -DskipTests
java -jar target/product-scribe-ai-0.0.1-SNAPSHOT.jar

Flujo de prueba rápida

# 1. Registrar usuario
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"demo1234","name":"Demo User"}'

# 2. Login → obtener token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"demo1234"}' | jq -r .token)

# 3. Generar descripciones
curl -X POST http://localhost:8080/api/v1/descriptions/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "Running Shoes UltraBoost Z",
    "keyAttributes": "Lightweight mesh, carbon fiber plate, 250g, waterproof",
    "targetKeywords": ["running shoes", "marathon shoes", "lightweight running"],
    "tones": ["PROFESSIONAL", "PERSUASIVE"]
  }'

# 4. Ver historial
curl http://localhost:8080/api/v1/descriptions/history \
  -H "Authorization: Bearer $TOKEN"

# 5. Exportar descripción id=1
curl http://localhost:8080/api/v1/descriptions/1/export \
  -H "Authorization: Bearer $TOKEN"

---

Referencias

• Spring Boot 4.0.4 Reference
• Spring Security 7.x
• jjwt 0.12.x
• Spring Cloud OpenFeign 4.x
• OpenAI Chat Completions API
• AI SaaS Ideas 2026 — BigIdeasDB

---

Análisis FinOps para ProductScribe AI

Estimación de Costos Operativos Mensuales

Para el MVP de ProductScribe AI, hemos estimado los siguientes costos operativos mensuales, asumiendo un inicio con 20 clientes de pago en el plan básico:

• Uso de LLM (OpenAI gpt-4o-mini):

* Estimación de Tokens: Asumiendo 20 clientes generando 50 descripciones cada uno al mes (1000 generaciones totales), y cada generación requiere aproximadamente 150 tokens de entrada y 450 tokens de salida (para múltiples variantes), el total estimado es de ~600,000 tokens/mes. * Costo de API: Utilizando el modelo gpt-4o-mini de OpenAI, el costo estimado para 600K tokens es de aproximadamente $0.29. Para un cálculo más conservador y con un pequeño buffer para futuras expansiones o picos, se estima un costo de $5/mes.

• Infraestructura Cloud (AWS Baseline):

* Servidor de Aplicación (EC2 t3.small): Una instancia t3.small (2 vCPU, 2GB RAM) es adecuada para iniciar una aplicación Spring Boot con bajo tráfico. Costo estimado: $25/mes. * Base de Datos (RDS db.t3.micro PostgreSQL): Una instancia db.t3.micro de RDS para PostgreSQL con almacenamiento básico. Costo estimado: $15/mes. * Otros servicios (Monitoring, Storage, Data Transfer): Se asume un costo mínimo o gratuito para el MVP con los servicios básicos de la nube (ej. CloudWatch, S3 para logs). Costo estimado: $0-$5/mes (incluido en el buffer).

Costo Operativo Mensual Total Estimado:

• LLM: $5
• Cloud Hosting (EC2): $25
• Base de Datos (RDS): $15
• Total: $45/mes

Estimación de Ingresos Mensuales

Basándonos en el modelo de monetización SaaS por suscripción y el plan inicial:

• Modelo de Precios: Plan Básico a $25/mes por 50 descripciones.
• Clientes Iniciales: 20 clientes de pago.

Ingreso Mensual Estimado: 20 clientes $25/mes = $500/mes.

Margen de Beneficio

• Ingreso Mensual: $500
• Costo Mensual: $45
• Beneficio: $500 - $45 = $455

Margen de Beneficio: (($455 / $500) 100) = 91%

Este margen inicial es excelente, reflejando la alta escalabilidad de las soluciones SaaS basadas en IA con costos de infraestructura relativamente bajos para un MVP.

Estrategias de Optimización FinOps

Para mantener un margen de beneficio saludable y escalar de manera eficiente, se recomiendan las siguientes optimizaciones FinOps:

1. Optimización de Costos de LLM:

* Caché Inteligente: Implementar un sistema de caché para almacenar y reutilizar descripciones generadas para productos con atributos similares o idénticos. Esto reducirá significativamente las llamadas a la API de LLM. * Prompt Engineering Avanzado: Refinar continuamente los prompts para ser más concisos y eficientes en el uso de tokens, tanto de entrada como de salida. * Evaluación de Modelos: Monitorear el rendimiento de gpt-4o-mini y evaluar si modelos de menor costo o modelos de código abierto (self-hosted o vía API como Llama 3) podrían satisfacer las necesidades de calidad y reducir aún más los costos a medida que la escala aumenta.

1. Optimización de Infraestructura Cloud:

* Planes de Ahorro/Instancias Reservadas: Una vez que se establezca un uso base predecible, adquirir Reserved Instances o Savings Plans para EC2 y RDS puede generar ahorros significativos (20-60%) en comparación con el modelo on-demand. * Serverless para Bases de Datos: Considerar migrar a servicios de bases de datos serverless (ej. Amazon Aurora Serverless v2 o Google Cloud SQL Serverless). Estos servicios ajustan automáticamente la capacidad y solo cobran por el uso, lo que es ideal para cargas de trabajo variables y reduce los costos de inactividad. * Contenedorización y Orquestación: Si el servicio escala a múltiples instancias, el uso de contenedores (Docker) con un orquestador (ej. AWS ECS/Fargate, Google Cloud Run) puede optimizar el uso de recursos y facilitar el escalado automático basado en la demanda.

1. Gestión del Uso y la Demanda:

* Procesamiento Asíncrono/Batch: Para solicitudes de generación de descripciones que no requieren una respuesta inmediata, implementar un sistema de colas (ej. SQS, Kafka) para procesarlas en lotes. Esto puede permitir el uso de recursos en horas de menor demanda o la consolidación de llamadas a la API de LLM. * Monitoreo de Costos Detallado: Utilizar herramientas de FinOps (ej. AWS Cost Explorer, GCP Cost Management) para monitorear y analizar los gastos en detalle, identificando áreas de derroche o ineficiencia.