ChurnGuard AI — Technical Explainer

Concept

ChurnGuard AI is a B2B SaaS Customer Success platform that predicts which subscribers are about to churn — before they cancel. Teams plug in their CRM (HubSpot), product analytics (Mixpanel), and support data (Zendesk); ChurnGuard fuses these signals into a single Churn Score (0–100) per customer with a human-readable explanation of the top-3 risk drivers.

Core value proposition: turn reactive CS teams into proactive revenue protectors. One dashboard, one score, one clear action.

---

Architecture

┌───────────────────────────────────────────────────────────────────┐
│                     Spring Boot 4.0.4 / Java 25                   │
│                                                                   │
│  ┌──────────────┐   ┌───────────────────┐   ┌──────────────────┐ │
│  │ AuthController│   │CustomerController │   │ AlertController  │ │
│  │ /api/v1/auth  │   │/api/v1/customers  │   │/api/v1/alerts   │ │
│  └──────┬───────┘   └────────┬──────────┘   └───────┬──────────┘ │
│         │                   │                        │            │
│  ┌──────▼───────┐   ┌────────▼──────────┐   ┌───────▼──────────┐ │
│  │  AuthService │   │  CustomerService  │   │   AlertService   │ │
│  └──────┬───────┘   └────────┬──────────┘   └───────┬──────────┘ │
│         │                   │                        │            │
│  ┌──────▼──────────────────────────────────────────────────────┐  │
│  │              PredictionService (heuristic engine)           │  │
│  └──────────────────────────┬────────────────────────────────┘  │
│                             │                                    │
│  ┌──────────────────────────▼────────────────────────────────┐  │
│  │  DataIngestionService  (@Scheduled + Virtual Threads)      │  │
│  │  ├── HubSpotFeignClient   (CRM contacts)                   │  │
│  │  ├── MixpanelFeignClient  (product events)                 │  │
│  │  └── ZendeskFeignClient   (support tickets)                │  │
│  └──────────────────────────┬────────────────────────────────┘  │
│                             │                                    │
│  ┌──────────────────────────▼────────────────────────────────┐  │
│  │          PostgreSQL  (JPA / Hibernate)                     │  │
│  │  organizations · app_users · customers                     │  │
│  │  churn_predictions · alert_configs                         │  │
│  └───────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘

Key design decisions

Decision	Rationale
Virtual Threads (Java 25)	Fan-out concurrent Feign calls to 3 external APIs without blocking platform threads
Heuristic scoring engine	Ships now, replace with ML model call (Spring AI) in v2 with no contract change
JWT / stateless auth	Multi-tenant SaaS; no sticky sessions needed
RFC-9457 Problem Detail	Standard error envelope — client-friendly and future-proof
Tiered alert configs	MRR + score thresholds = high-signal, low-noise alerting

---

API Endpoints

All endpoints except %%INLINE0%% require %%INLINE1%%.

Auth

Method	Path	Description
%%INLINE2%%	%%INLINE3%%	Create account + organisation → returns JWT
%%INLINE4%%	%%INLINE5%%	Authenticate → returns JWT

Register payload

{
  "organizationName": "Acme Corp",
  "email": "alice@acme.io",
  "password": "securepass",
  "fullName": "Alice Smith"
}

Customers

Method	Path	Description
%%INLINE6%%	%%INLINE7%%	All customers sorted by churn score ↓
%%INLINE8%%	%%INLINE9%%	At-risk subset (default ≥ 70)
%%INLINE10%%	%%INLINE11%%	Full detail + top-3 churn reasons

Customer detail response

{
  "id": 3,
  "name": "Umbrella Corp",
  "churnScore": 85,
  "mrrUsd": 22000,
  "reasons": [
    { "rank": 1, "signal": "PRODUCT_INACTIVITY",     "description": "No product login in 30 days" },
    { "rank": 2, "signal": "OPEN_SUPPORT_TICKETS",   "description": "5 unresolved support tickets" },
    { "rank": 3, "signal": "CONTRACT_EXPIRY_IMMINENT","description": "Contract renews in 10 day(s)" }
  ],
  "openTickets": 5,
  "featureAdoptionPct": 20,
  "contractRenewalDate": "2026-04-30"
}

Dashboard

Method	Path	Description
%%INLINE12%%	%%INLINE13%%	KPI summary: total, at-risk, avg score, MRR at risk

Alerts

Method	Path	Description
%%INLINE14%%	%%INLINE15%%	Create email alert rule
%%INLINE16%%	%%INLINE17%%	List org alert rules

Alert rule payload

{
  "recipientEmail": "cs-team@acme.io",
  "scoreThreshold": 75,
  "mrrThresholdUsd": 5000
}

---

Churn Score Signals

Signal	Weight	Trigger
Low feature adoption	+35 pts	adoption < 30 %
Moderate adoption	+15 pts	adoption 30–59 %
Product inactivity	+25 pts	no login > 14 days
Declining usage	+10 pts	no login 7–14 days
No activity recorded	+20 pts	lastActiveAt null
Multiple open tickets	+25 pts	openTickets ≥ 3
Single/dual tickets	+10 pts	openTickets 1–2
Contract renewal ≤ 30d	+15 pts	daysToRenewal ≤ 30

Score capped at 100. Replace PredictionService.computeScore() with a Spring AI call to plug in an ML model (e.g., OpenAI function calling or Vertex AI).

---

Business Analysis

Market

• TAM: $2.3 B (Customer Success platforms, 2026)
• Target: 50K+ B2B SaaS companies globally with > 50 customers
• Buyer: Head of CS / VP Growth / Founder

Pricing (tiered SaaS)

Tier	Customers tracked	Integrations	Price
Starter	up to 200	1	$199/mo
Growth	up to 2 000	3	$799/mo
Enterprise	Unlimited	Unlimited + SSO	Custom

Unit Economics (Starter)

• CAC: ~$1 200 (outbound + demo)
• LTV (24-month): $4 776 → LTV:CAC = 3.98×
• Payback: ~6 months

Competitive Differentiator

Competitors (Gainsight, ChurnZero) are expensive enterprise suites ($50K+/yr). ChurnGuard AI targets the mid-market gap: companies too big for spreadsheets, too small for Gainsight. Entry price 10× lower, setup < 1 day.

---

Running Locally

Prerequisites

• Java 25
• Docker (for PostgreSQL)
• Maven 3.9+

1. Start PostgreSQL

docker run -d \
  --name churnguard-db \
  -e POSTGRES_DB=churnguard \
  -e POSTGRES_USER=churnguard \
  -e POSTGRES_PASSWORD=churnguard \
  -p 5432:5432 \
  postgres:16

2. Build & Run

cd solutions/2026-04-20-churnguard-ai-api
mvn clean package -DskipTests
java -jar target/churnguard-ai-api-0.0.1-SNAPSHOT.jar

On startup, %%INLINE19%% inserts a demo org (%%INLINE20%%) with 6 customers spanning the full risk spectrum.

3. Authenticate

curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@acme.io","password":"password123"}' | jq .token

4. Query At-Risk Customers

TOKEN=<paste token here>

curl -s http://localhost:8080/api/v1/customers/at-risk \
  -H "Authorization: Bearer $TOKEN" | jq .

5. View Dashboard Stats

curl -s http://localhost:8080/api/v1/dashboard/stats \
  -H "Authorization: Bearer $TOKEN" | jq .

6. Configure Integration Tokens (optional)

export HUBSPOT_TOKEN=pat-na1-...
export MIXPANEL_SECRET=...
export ZENDESK_TOKEN=...

The ingestion cycle runs every 6 hours. Tokens without values → safe fallback (skip that source, score from existing DB data).

---

References

• AI SaaS Product Ideas 2026
• Spring Boot 4.0 Reference
• Spring Cloud OpenFeign
• JJWT 0.12.x docs
• HubSpot CRM API v3
• Mixpanel Data Export API
• Zendesk Search API

---

FinOps Analysis para ChurnGuard AI

Visión General

ChurnGuard AI, como micro-startup en su fase MVP, se beneficiará de una estructura de costos ajustada y un enfoque en la eficiencia. La estrategia FinOps se centrará en optimizar el uso de los recursos de la nube y las APIs de LLM para maximizar el margen de beneficio desde el inicio.

Estimación de Costos Mensuales

1. Estimación de Tokens LLM:

Para el MVP, se asume que el LLM (gpt-4o-mini) se utilizará principalmente para generar las "3 principales razones" del Churn Score. Consideramos un escenario inicial con 7 clientes de ChurnGuard AI, analizando un total de aproximadamente 2500 clientes finales.

• Uso: Generación de explicaciones para el 20% de los clientes finales en riesgo (500 clientes) semanalmente, más 1500 solicitudes bajo demanda al mes.

Llamadas LLM: (500 clientes 4 semanas/mes) + 1500 on-demand = 3500 llamadas/mes.

• Tokens por Llamada: Se estima un promedio de 800 tokens de entrada (contexto del cliente) y 200 tokens de salida (3 razones) por llamada, totalizando 1000 tokens/llamada.

Tokens Mensuales Totales: 3500 llamadas 1000 tokens/llamada = ~3.5 millones de tokens/mes.

2. Desglose de Costos Mensuales:

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

Input: (800 tokens/llamada 3500 llamadas) / 1000 * $0.00015/1K tokens = $0.42 Output: (200 tokens/llamada 3500 llamadas) / 1000 * $0.0006/1K tokens = $0.42 * Total LLM: ~$0.84 (redondeado a $1/mes)

• Costo de Infraestructura Cloud (AWS):

* Compute: 1x EC2 t3.small (Linux, On-Demand) @ ~$15/mes. * Base de Datos: 1x AWS RDS db.t3.micro (PostgreSQL, 20GB almacenamiento) @ ~$15/mes. * Otros servicios: Networking (data transfer), Logs (CloudWatch), S3 (backups/assets pequeños), etc. @ ~$10/mes. * Total Cloud Hosting: ~$40/mes

• Total de Costos Operativos Mensuales Estimados: ~$41/mes

Estimación de Ingresos Mensuales

Dado que no se proporcionó un análisis de mercado específico, se asume un modelo de precios por niveles para ChurnGuard AI y una base de clientes inicial para una micro-startup:

• Nivel 1 (Básico): Hasta 100 clientes finales, 2 integraciones - $49/mes.
• Nivel 2 (Estándar): Hasta 500 clientes finales, 3 integraciones - $99/mes.

Proyección de Clientes Iniciales:

5 clientes en Nivel 1: 5 $49 = $245/mes 2 clientes en Nivel 2: 2 $99 = $198/mes

• Ingresos Mensuales Totales Estimados: ~$443 (redondeado a $450/mes)

Margen de Beneficio

• Ingresos Mensuales: $450
• Costos Mensuales: $41
• Beneficio Mensual: $450 - $41 = $409

Margen de Beneficio: ($409 / $450) 100 = ~90%

Optimizaciones FinOps Concretas

Para mantener y mejorar este excelente margen de beneficio a medida que ChurnGuard AI escala, se recomiendan las siguientes optimizaciones:

1. Optimización de LLM:

* Caché de Respuestas: Implementar un mecanismo de caché para almacenar explicaciones generadas por LLM para clientes que no han tenido cambios significativos en sus datos o score de churn. Esto reduce llamadas redundantes a la API del LLM. * Prompt Engineering Eficiente: Refinar continuamente los prompts para obtener las explicaciones deseadas con el menor número de tokens posible (tanto de entrada como de salida). * Generación Condicional: Limitar la generación de explicaciones LLM a los clientes con mayor riesgo o a aquellos que son activamente visualizados por los equipos de Customer Success, en lugar de una generación masiva periódica. * Batch Processing: Para las actualizaciones programadas, agrupar las solicitudes de generación de explicaciones para reducir la sobrecarga de llamadas a la API (aunque el costo principal es por token, no por llamada, esto puede optimizar el procesamiento interno).

1. Optimización de Infraestructura Cloud:

* Derecho de Dimensionamiento (Right-sizing): Revisar y ajustar regularmente el tamaño de las instancias de EC2 y RDS. Empezar con instancias pequeñas (como t3.small/t3.micro) y escalar solo cuando la carga de trabajo lo justifique. * Instancias Reservadas (Reserved Instances/Savings Plans): Una vez que la carga base de la aplicación sea predecible, considerar la compra de instancias reservadas o planes de ahorro para reducir significativamente los costos de compute y base de datos a largo plazo (20-60% de ahorro). * Monitoreo de Costos: Configurar dashboards y alertas en AWS Cost Explorer o CloudWatch para identificar rápidamente cualquier gasto inesperado o ineficiencia. * Limpieza de Recursos: Asegurarse de que no queden recursos no utilizados (volúmenes EBS, snapshots, IPs elásticas) que generen costos residuales.

1. Monetización y Crecimiento:

* Modelos de Precios Basados en Valor: A medida que se añadan más funcionalidades o el modelo de predicción se vuelva más sofisticado, ajustar los niveles de precios para reflejar el valor entregado, lo que puede aumentar el LTV (Lifetime Value) de los clientes. * Análisis de ROI para el Cliente: Ayudar a los clientes a cuantificar el ROI de ChurnGuard AI (ej., clientes retenidos, reducción de churn) para justificar precios más altos y facilitar la expansión a niveles superiores.