InsightPilot API — EXPLAINER

Concepto

InsightPilot es un copiloto de IA para Product Managers, inspirado en la tendencia "Cursor for PMs". Elimina el 40% del tiempo que los PMs invierten en recopilar y analizar datos de múltiples fuentes (Jira, Intercom, Zendesk, Google Analytics) y lo convierte en insights accionables listos para el roadmap.

Problema

Los PMs se ahogan en datos dispares: tickets de soporte, entrevistas de usuario, analíticas, encuestas. El proceso de síntesis manual es lento, propenso a sesgos y retrasa decisiones críticas de producto.

Solución MVP

Pipeline completo de IA:

Fuentes (Jira/Intercom) → Ingesta (Virtual Threads) → Análisis LLM → Insights + Alertas → API REST

---

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│  Spring Boot 4.0.4  /  Java 25  /  H2 (dev) / PostgreSQL (prod) │
├──────────────┬──────────────────┬──────────────┬────────────────┤
│  controller/ │    service/      │   client/    │   repository/  │
│              │                  │              │                │
│ AuthCtrl     │ AuthService      │ LlmClient    │ UserRepo       │
│ IntegCtrl    │ IntegService     │  (Feign)     │ IntegRepo      │
│ InsightCtrl  │ DataIngestion    │              │ RawDataRepo    │
│ AlertCtrl    │  Service         │ JiraClient   │ InsightRepo    │
│ GlobalEx     │ InsightService   │  (mock+real) │ AlertRepo      │
│  Handler     │ AlertService     │ IntercomClient│               │
│              │ JwtService       │  (mock+real) │                │
│              │ UserDetailsSvc   │              │                │
└──────────────┴──────────────────┴──────────────┴────────────────┘
                         ▲
              SecurityConfig + JwtAuthFilter
              (Spring Security 7 — STATELESS JWT)

Capas

Capa	Responsabilidad
controller	REST endpoints, validación de entrada, mapeo HTTP
service	Lógica de negocio: auth, ingesta, análisis IA, alertas
client	LLM via Feign (OpenAI-compatible); Jira/Intercom mock/real
repository	Spring Data JPA — acceso a datos
model	Entidades JPA (User, Integration, RawData, Insight, Alert)
dto	Java Records — contratos de API inmutables
security	JwtAuthenticationFilter — valida Bearer token por request
config	SecurityConfig, FeignClientConfig, JacksonConfig

Decisiones técnicas clave

• Java 25 Virtual Threads — %%INLINE0%% usa %%INLINE1%% para ingestar N integraciones concurrentemente sin bloquear threads de plataforma. También usado en el endpoint POST /integrations/{id}/sync.
• Feign (OpenAI) — LlmClient usa Spring Cloud OpenFeign para llamar cualquier API compatible con OpenAI (GPT-4o-mini por defecto, configurable).
• Mock graceful degradation — Si %%INLINE4%% no está configurado, %%INLINE5%% devuelve datos mock realistas para demo.
• JWT stateless — jjwt 0.12.6 con HS256; secret y expiración configurables.
• H2 en dev, PostgreSQL en prod — configurado vía spring.datasource.*.

---

Endpoints

Auth (público)

Método	Path	Descripción
POST	/api/v1/auth/register	Crea cuenta, devuelve JWT
POST	/api/v1/auth/login	Intercambia credenciales por JWT

Integraciones (JWT requerido)

Método	Path	Descripción
GET	/api/v1/integrations	Lista integraciones del usuario
POST	/api/v1/integrations	Conecta Jira/Intercom/Zendesk/GA
DELETE	/api/v1/integrations/{id}	Desactiva integración
POST	/api/v1/integrations/{id}/sync	Ingesta inmediata (async, virtual thread)

Insights & Dashboard (JWT requerido)

Método	Path	Descripción
GET	/api/v1/insights	Lista todos los insights del usuario
POST	/api/v1/insights/generate/{integrationId}	Ejecuta análisis IA sobre datos crudos
GET	/api/v1/insights/dashboard	Dashboard unificado: temas top + insights recientes + alertas activas
POST	/api/v1/insights/query	Pregunta en lenguaje natural al copiloto

Alertas de Tendencias (JWT requerido)

Método	Path	Descripción
GET	/api/v1/alerts	Todas las alertas (leídas + no leídas)
GET	/api/v1/alerts/unread	Solo alertas no leídas (badge count)
PATCH	/api/v1/alerts/{id}/read	Marca alerta como leída

---

Análisis de Negocio

Modelo de Monetización — B2B SaaS Freemium

Plan	Precio	Límites
Free	$0	1 integración, 50 análisis/mes, 1 usuario
Starter	$49/mes	5 integraciones, 500 análisis/mes, 3 usuarios
Growth	$199/mes	15 integraciones, ilimitado, 15 usuarios
Enterprise	Custom	Todo ilimitado, SSO, SLA

TAM / SAM / SOM

• TAM: 10M Product Managers globalmente × $600 ARPU = $6B
• SAM: 2M PMs en tech companies × $600 ARPU = $1.2B
• SOM (3 años): 0.1% SAM = $1.2M ARR objetivo

Métricas clave

• Time-to-insight: de horas → minutos (target: < 2 min por análisis)
• Temas detectados por ciclo: ≥ 5 temas accionables
• Alert precision: > 80% alertas con seguimiento real
• API latency: P95 < 500ms (excluyendo tiempo LLM)

---

Cómo Ejecutar

Prerrequisitos

• Java 25 (JDK 25+)
• Maven 3.9+
• (Opcional) OpenAI API key para análisis LLM real

Inicio rápido (H2 en memoria)

cd solutions/2026-06-07-insight-pilot-api
mvn clean spring-boot:run

El servidor arranca en http://localhost:8080 con H2 embebido.

Con LLM real (OpenAI o compatible)

export APP_LLM_API_KEY=sk-...
export APP_LLM_MODEL=gpt-4o-mini
# O cualquier proveedor compatible:
export APP_LLM_BASE_URL=https://api.anthropic.com
mvn spring-boot:run

Con PostgreSQL (producción)

# application-prod.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/insightpilot
    username: insightpilot
    password: secret
  jpa:
    hibernate:
      ddl-auto: validate

mvn spring-boot:run -Dspring-boot.run.profiles=prod

Demo rápido (curl)

# 1. Registrar usuario
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana PM","email":"ana@startup.com","password":"password123"}'

# → {"token":"eyJ...","email":"ana@startup.com","name":"Ana PM"}

# 2. Conectar integración Jira (modo demo — usa datos mock)
TOKEN="eyJ..."
curl -X POST http://localhost:8080/api/v1/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"JIRA","name":"Mi Jira","accessToken":"demo-token","workspaceUrl":"https://myco.atlassian.net"}'

# 3. Trigger ingesta inmediata
INTEGRATION_ID=1
curl -X POST http://localhost:8080/api/v1/integrations/$INTEGRATION_ID/sync \
  -H "Authorization: Bearer $TOKEN"

# 4. Generar insights con IA
curl -X POST http://localhost:8080/api/v1/insights/generate/$INTEGRATION_ID \
  -H "Authorization: Bearer $TOKEN"

# 5. Dashboard unificado
curl http://localhost:8080/api/v1/insights/dashboard \
  -H "Authorization: Bearer $TOKEN"

# 6. Pregunta en lenguaje natural
curl -X POST http://localhost:8080/api/v1/insights/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"¿Cuáles son los principales problemas de los usuarios esta semana?"}'

# 7. Ver alertas de tendencias
curl http://localhost:8080/api/v1/alerts/unread \
  -H "Authorization: Bearer $TOKEN"

Compilación

mvn clean compile   # Verificar que compila
mvn clean package   # Generar JAR
java -jar target/insight-pilot-api-0.0.1-SNAPSHOT.jar

---

Configuración (properties)

Propiedad	Default	Descripción
app.jwt.secret	(string largo)	Secreto para firma JWT (HS256, mín. 32 chars)
%%INLINE22%%	%%INLINE23%%	Duración del token en ms (24h)
%%INLINE24%%	%%INLINE25%%	Base URL del LLM provider
%%INLINE26%%	(vacío → mock)_	API key del LLM
%%INLINE27%%	%%INLINE28%%	Modelo a usar

---

Referencias

• Y Combinator — AI for Product Managers (Spring 2026)
• Spring Boot 4.0 Reference
• Spring Security 7 — JWT
• Spring Cloud OpenFeign 4.2
• jjwt 0.12.x Migration Guide
• Java 25 Virtual Threads (JEP 491)