ChurnGuard AI — API

Concepto

Plataforma B2B SaaS de Automatización del Éxito del Cliente. Sustituye el monitoreo manual de "customer churn" por un Health Score calculado por IA sobre señales de uso de producto, logins y tickets de soporte, con alertas proactivas y **Talking Points / Next Best Actions generados por LLM** para que cada CSM sepa exactamente cómo actuar antes de perder una cuenta.

Multi-tenant: cada Company (empresa cliente de ChurnGuard) aísla sus propios %%INLINE1%%, %%INLINE2%%, %%INLINE3%% y %%INLINE4%% — reforzado en cada consulta vía JWT (companyId embebido en el token) y en cada repositorio (%%INLINE6%%, %%INLINE7%%).

Arquitectura

controller/   AuthController, CustomerController, AlertController, IngestionController
service/      AuthService, DataIngestionService, HealthScoreService, AiInsightService, AlertService
client/       HubSpotClient, MixpanelClient, LlmClient (Feign)
repository/   CompanyRepository, CSMUserRepository, CustomerRepository, HealthDataRepository, AlertRepository
model/        Company, CSMUser, Customer, HealthData, Alert (+ enums CsmRole, AlertStatus)
security/     JwtService, JwtAuthenticationFilter, AuthenticatedUser
config/       SecurityConfig, FeignConfig, SchedulingConfig, JacksonConfig (pre-escrito)
dto/          records para requests/responses y payloads de integración
exception/    GlobalExceptionHandler + excepciones de dominio
bootstrap/    DemoDataSeeder (datos demo al arrancar)

Flujo de datos:

1. %%INLINE8%% llama a %%INLINE9%% (CRM) y MixpanelClient

(analítica de producto) vía OpenFeign para obtener logins, minutos de uso y tickets de soporte abiertos. Protegido con Resilience4j @CircuitBreaker: si el proveedor externo falla, cae a telemetría simulada (útil en sandbox sin credenciales reales).

1. HealthScoreService.recalculateHealthScore calcula el Health Score con

un modelo tipo regresión logística (sigmoide sobre señales ponderadas, 0–100) y persiste un HealthData. Se ejecuta también vía %%INLINE14%% cada hora (%%INLINE15%%).

1. Si el score cae bajo el umbral crítico (40/100), AlertService pide a

AiInsightService que genere Talking Points + Next Best Actions invocando un LLM (Anthropic Messages API) a través de LlmClient. Sin churnguard.integrations.llm.api-key configurada, o si el LLM falla, cae a un guion basado en reglas (nunca deja una alerta sin guía).

1. El Alert resultante queda disponible para el CSM vía API.

Endpoints

Todos bajo %%INLINE21%%, protegidos con JWT excepto %%INLINE22%%.

Método	Ruta	Descripción
POST	%%INLINE23%%	Login CSM → JWT (%%INLINE24%%)
GET	/api/customers	Clientes de la empresa autenticada + último Health Score
GET	/api/customers/{id}	Detalle de un cliente
GET	/api/alerts	Alertas abiertas de la empresa (score crítico)
GET	/api/alerts/{id}	Detalle de alerta con Talking Points / Next Best Actions
POST	/api/alerts/{id}/resolve	Marca una alerta como resuelta
POST	/api/ingestion/trigger	Dispara ingesta + recálculo de Health Score bajo demanda

Autenticación: Authorization: Bearer <token>.

Referencias

• Spring Boot 4.0.4 / Spring Framework 7.x / Java 25.
• Jackson 3 (%%INLINE32%%) vía %%INLINE33%% pre-escrito.
• Spring Cloud OpenFeign 4.2.1 para integraciones CRM/Analytics/LLM.
• jjwt 0.12.6 para emisión/validación de JWT (HMAC).
• Resilience4j 2.2.0 (@CircuitBreaker) para tolerancia a fallos en

integraciones externas.

• Spring Security 7 (stateless, filtro JWT propio).

Análisis de negocio

• Problema: los equipos de Customer Success detectan el churn

demasiado tarde porque cruzan manualmente datos de CRM, producto y soporte. ChurnGuard AI automatiza ese cruce y prioriza el trabajo del CSM con alertas accionables, no solo dashboards pasivos.

• Monetización: SaaS B2B con pricing por niveles según nº de clientes

monitorizados y nº de asientos de CSM — el modelo de datos ya soporta esto (Company.pricingTier, aislamiento multi-tenant).

• Ventaja competitiva del MVP: el motor de Health Score y el motor de

IA de alertas están desacoplados de las integraciones concretas (Feign clients intercambiables) y son resilientes por diseño (circuit breakers + fallback rule-based), por lo que el producto sigue funcionando y generando valor incluso si un proveedor externo cae.

• Siguiente iteración natural: sustituir la fórmula logística fija por

un modelo entrenado (scikit-learn/PMML servido vía microservicio, o Spring AI con un modelo embebido) sin tocar el contrato de HealthScoreService.

Cómo ejecutar

# Requiere PostgreSQL accesible. Variables típicas (Spring Boot estándar):
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/churnguard
export SPRING_DATASOURCE_USERNAME=churnguard
export SPRING_DATASOURCE_PASSWORD=churnguard
export SPRING_JPA_HIBERNATE_DDL_AUTO=update

# Opcional — habilita generación real de Talking Points vía LLM (Anthropic):
export CHURNGUARD_INTEGRATIONS_LLM_API_KEY=sk-ant-...

mvn clean spring-boot:run

Al arrancar, DemoDataSeeder crea la empresa "Acme SaaS Inc." con el CSM %%INLINE38%% / %%INLINE39%% y 3 clientes de ejemplo. Flujo de prueba:

TOKEN=$(curl -s -X POST localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"csm.demo","password":"demo1234"}' | jq -r .token)

curl -s -X POST localhost:8080/api/ingestion/trigger -H "Authorization: Bearer $TOKEN"
curl -s localhost:8080/api/customers -H "Authorization: Bearer $TOKEN"
curl -s localhost:8080/api/alerts -H "Authorization: Bearer $TOKEN"

---

FinOps Analysis para ChurnGuard AI

Resumen de Costos y Rentabilidad

ChurnGuard AI, en su fase de micro-startup, proyecta una operación con costos iniciales muy controlados, lo que permite un alto margen de beneficio. La estimación se basa en una base inicial de 5 clientes de pago, cada uno con un plan básico de $60/mes.

• Ingreso Mensual Estimado: $300 (5 clientes x $60/mes)
• Costos Operativos Mensuales Estimados: $65

* Costo de LLM (OpenAI gpt-4o-mini): $30/mes * Estimación de ~100K tokens/mes (asumiendo 50 alertas, cada una con 1000 tokens de entrada y 300 de salida, más un buffer para pruebas). * Desglose: 75K tokens de entrada ($0.00015/K) = $11.25; 25K tokens de salida ($0.0006/K) = $15.00. * Costo de Infraestructura Cloud (AWS): $35/mes * Instancia EC2 t3.small (para la aplicación Spring Boot): ~$15/mes. * Base de datos RDS db.t4g.micro (PostgreSQL): ~$15/mes (incluye 20GB de almacenamiento y backups básicos). * Costos de red y almacenamiento adicionales (estimado): ~$5/mes. * APIs Externas (CRM/Analytics): Costo directo insignificante, ya que se asume que los clientes de ChurnGuard AI ya pagan por sus propias suscripciones a HubSpot/Mixpanel.

• Beneficio Mensual Estimado: $235
• Margen de Beneficio: 78%

Principales Impulsores de Costo

Los principales impulsores de costo son la infraestructura de la nube (instancia de aplicación y base de datos gestionada) y el consumo de tokens del LLM. A medida que la startup escale, el costo del LLM será el componente más variable y potencialmente el de mayor crecimiento.

Estrategias FinOps para la Optimización de Costos

1. Optimización del Consumo de LLM:

* Caché Inteligente: Implementar un sistema de caché para las respuestas del LLM cuando los contextos de los clientes o los tipos de alertas sean similares o recurrentes. Esto reducirá las llamadas redundantes a la API del LLM. * Prompt Engineering: Refinar los prompts para ser lo más concisos y efectivos posible, minimizando el número de tokens de entrada sin comprometer la calidad de la respuesta. Priorizar la extracción de información relevante en lugar de la generación de texto extenso cuando sea posible. * Modelos de Menor Costo/Serverless: Para la fase de generación de 'Talking Points', considerar el uso de funciones serverless (ej. AWS Lambda) que invocan el LLM, pagando solo por la ejecución y no por una instancia siempre activa. A mayor escala, evaluar LLMs más económicos o incluso modelos de código abierto auto-hosteados (si la complejidad lo justifica y el rendimiento es aceptable).

1. Optimización de Infraestructura Cloud:

* Uso de Instancias Reservadas (RIs): Una vez que se establezca un patrón de uso predecible para EC2 y RDS, la compra de RIs puede generar ahorros significativos (20-40%) en comparación con las instancias bajo demanda. * Escalabilidad Elástica: Asegurarse de que la infraestructura sea elástica y pueda escalar automáticamente hacia arriba o hacia abajo según la demanda, evitando el sobreaprovisionamiento. Para una micro-startup, esto puede significar inicialmente usar las instancias más pequeñas y monitorear de cerca el rendimiento. * Monitoreo de Costos Detallado: Implementar herramientas de monitoreo de costos (ej. AWS Cost Explorer, GCP Cost Management) con alertas para detectar y corregir rápidamente cualquier gasto inesperado o ineficiente.

1. Gestión de APIs Externas:

* Aunque las APIs de CRM/Analytics son gratuitas para la integración, es crucial manejar eficientemente las llamadas para evitar posibles límites de tasa o cargos futuros si los proveedores cambian sus políticas.

Conclusión

ChurnGuard AI muestra un modelo de negocio con un alto potencial de margen de beneficio en sus etapas iniciales debido a la naturaleza de bajos costos fijos de un SaaS impulsado por IA. La clave para mantener esta rentabilidad a medida que crece será la gestión proactiva de los costos del LLM y la optimización continua de la infraestructura cloud, siguiendo principios FinOps.