CampaignPilot — CMO Autónomo como Servicio

Concepto

CampaignPilot es un agente de IA autónomo que actúa como "CMO como servicio" para PyMEs y startups sin equipo de marketing dedicado. El usuario define su negocio en un onboarding guiado, conecta sus cuentas de Google Ads / Meta Ads, y el agente:

1. Genera texto e imagen (prompt) de anuncios vía LLM.
2. Lanza campañas sobre la cuenta publicitaria conectada.
3. Sincroniza métricas de rendimiento diariamente.
4. Optimiza de forma autónoma: pausa anuncios de bajo CTR y reasigna presupuesto

al mejor performer.

Esto ataca el punto de dolor central del problemStatement: falta de tiempo, presupuesto y experiencia de las PyMEs para ejecutar marketing digital efectivo.

Arquitectura

Spring Boot 4.0.4 / Java 25, capas clásicas + orquestación de IA:

controller/   → REST endpoints (auth, onboarding, ad-accounts, campaigns, dashboard)
service/      → lógica de negocio (AuthService, CampaignService, OptimizationService...)
repository/   → Spring Data JPA sobre PostgreSQL
model/        → entidades JPA (User, AdAccount, Campaign, PerformanceMetric)
dto/          → Records inmutables para request/response
client/       → cliente Feign hacia el LLM (chat-completions)
security/     → JWT stateless (JwtService, JwtAuthFilter, UserPrincipal)
scheduler/    → PerformanceSyncScheduler (@Scheduled + Virtual Threads)
config/       → SecurityConfig, FeignConfig, VirtualThreadConfig
exception/    → GlobalExceptionHandler (@RestControllerAdvice)

Decisiones clave:

• LlmContentService llama al LlmClient (Feign) para generar creatividades;

si no hay campaignpilot.llm.api-key configurada o el LLM falla, degrada a una plantilla local — el flujo de creación de campañas nunca se bloquea, y la arquitectura queda lista para enchufar un proveedor real (GPT-4, Claude, etc.).

• AdAccountService simula el intercambio OAuth2 (código → tokens) para no

depender de credenciales de cliente reales de Google/Meta en el MVP; los tokens se persisten en %%INLINE3%% tal como exige el %%INLINE4%%.

• OptimizationService + PerformanceSyncScheduler: tarea diaria que sincroniza

métricas (simulando la llamada I/O real a las APIs de reporting) usando Executors.newVirtualThreadPerTaskExecutor() para paralelizar sin bloquear hilos de plataforma (Java 25 Virtual Threads), y luego aplica la regla de optimización: CTR < 1.0% → pausa; el 50% del presupuesto liberado se reasigna al ganador (mayor CTR).

• VirtualThreadConfig también configura Tomcat para atender requests HTTP

sobre hilos virtuales, clave para escalar I/O concurrente hacia APIs externas.

• Seguridad: JWT stateless (jjwt 0.12.6), BCryptPasswordEncoder,

%%INLINE7%% + %%INLINE8%% (API vigente en Spring Security 7.x).

Endpoints

Método	Ruta	Auth	Descripción
POST	/api/auth/register	pública	Alta de cuenta PyME
POST	/api/auth/login	pública	Login, devuelve JWT
POST	/api/onboarding	JWT	Onboarding: objetivo, público, presupuesto
POST	/api/ad-accounts/connect	JWT	Conecta cuenta Google/Meta Ads (OAuth2)
GET	/api/ad-accounts	JWT	Lista cuentas conectadas
POST	/api/campaigns	JWT	Genera creatividad IA y lanza campaña
GET	/api/campaigns	JWT	Lista campañas del usuario
GET	/api/campaigns/{id}	JWT	Detalle de campaña
POST	/api/campaigns/{id}/pause	JWT	Pausa manual
POST	/api/campaigns/{id}/resume	JWT	Reanuda campaña
GET	/api/dashboard	JWT	Métricas unificadas (CPC, CTR, conversiones)

Todas las rutas %%INLINE20%% excepto %%INLINE21%% requieren header Authorization: Bearer <token>.

Referencias

• Business case: Agentes de IA Autónomos para Funciones Empresariales Específicas

(fuente: Wellows Blog — https://wellows.com/blog/ai-startups).

• Spring Boot 4.0.4 / Spring Framework 7.x / Spring Security 7.x / Jackson 3.x.
• jjwt 0.12.6 (io.jsonwebtoken) para JWT.
• Spring Cloud OpenFeign 4.2.1 para el cliente LLM.

Análisis de negocio

• Modelo de ingresos: SaaS por niveles según Ad Spend gestionado — a mayor

presupuesto publicitario que el agente administra, mayor el fee. Alinea el incentivo de CampaignPilot con el crecimiento real del cliente.

• Defensibilidad: la combinación de generación de creatividad + conexión

directa a cuentas + optimización autónoma es una categoría nueva ("CMO como servicio"), más profunda que una herramienta de asistencia puntual.

• Riesgo principal: dependencia de las APIs de Google Ads / Meta Marketing

(rate limits, cambios de políticas) y calidad del LLM para creatividades — mitigado con el patrón de fallback ya implementado en LlmContentService.

• Siguiente paso de validación: sustituir el intercambio OAuth2 simulado de

AdAccountService por los flujos reales de Google/Meta y medir el CTR real de las creatividades generadas por LLM vs. plantillas humanas.

Cómo ejecutar

cd solutions/2026-08-02-campaign-pilot
mvn clean compile        # compila el proyecto
mvn spring-boot:run      # levanta el servicio en :8080

Variables de entorno relevantes (no están en application.yml, usan defaults seguros para desarrollo si no se configuran):

• %%INLINE26%% / %%INLINE27%% / SPRING_DATASOURCE_PASSWORD

— conexión a PostgreSQL (requerido en runtime; sin esto Spring Boot no podrá crear el DataSource al arrancar).

• %%INLINE30%%, %%INLINE31%% — proveedor LLM real

(si se omite, LlmContentService usa plantillas locales).

• CAMPAIGNPILOT_SECURITY_JWT_SECRET — secreto de firma JWT (usa un default

de desarrollo si no se define; cambiar en producción).

Ejemplo de flujo E2E:

curl -X POST localhost:8080/api/auth/register -H "Content-Type: application/json" \
  -d '{"email":"demo@pyme.com","password":"secret123","businessName":"Café Aurora"}'

curl -X POST localhost:8080/api/onboarding -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"businessName":"Café Aurora","industry":"Gastronomía","targetAudience":"jóvenes urbanos 20-35","monthlyBudget":800,"primaryObjective":"SALES"}'

curl -X POST localhost:8080/api/ad-accounts/connect -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"platform":"META_ADS","authorizationCode":"mock-code"}'

curl -X POST localhost:8080/api/campaigns -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"adAccountId":1,"name":"Lanzamiento Café Aurora","objective":"SALES","product":"Café de especialidad","targetAudience":"jóvenes urbanos 20-35","budget":300}'

curl localhost:8080/api/dashboard -H "Authorization: Bearer <token>"

Nota conocida del scaffold: el pom.xml pre-escrito declara org.testcontainers:postgresql sin versión explícita. La BOM de %%INLINE36%% importa %%INLINE37%%, que en Testcontainers 2.x renombró ese módulo a org.testcontainers:testcontainers-postgresql, por lo que Maven no puede resolver la versión del artefacto legado. Al ser un archivo pre-escrito fuera de alcance de esta tarea, no se modificó; para desbloquear %%INLINE39%% bastaría con fijar %%INLINE40%% (última release de la serie 1.x) o renombrar el artifactId a testcontainers-postgresql.