BrandPulse AI — Technical Explainer

Concept

BrandPulse AI is a B2B SaaS brand-monitoring platform that lets marketing teams and startup founders track what people say about their brand across social channels — without hiring a dedicated analyst. Users register, add keywords, and the system automatically fetches mentions, classifies sentiment via an LLM, surfaces trends on a dashboard, and fires alerts when something spikes.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Client (browser / mobile / CLI)                                │
│  → Bearer JWT on every request                                  │
└───────────────────┬─────────────────────────────────────────────┘
                    │ HTTPS
┌───────────────────▼─────────────────────────────────────────────┐
│  Spring Boot 4.0.4  (Java 25, Virtual Threads)                  │
│                                                                 │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │AuthController│  │KeywordCtrl  │  │DashboardController   │   │
│  └──────┬──────┘  └──────┬───────┘  └──────────┬───────────┘   │
│         │                │                      │               │
│  ┌──────▼──────┐  ┌──────▼───────┐  ┌──────────▼───────────┐   │
│  │ AuthService │  │KeywordService│  │  DashboardService     │   │
│  └──────┬──────┘  └──────┬───────┘  └──────────┬───────────┘   │
│         │                │                      │               │
│  ┌──────▼──────────────────────────────────────▼───────────┐   │
│  │           Spring Data JPA / H2 (dev) / PostgreSQL (prod) │   │
│  │   User · TrackedKeyword · Mention                        │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  MentionIngestionService   (@Scheduled, Virtual Threads) │   │
│  │    └→ RedditClient (Feign) ──► Reddit JSON API           │   │
│  │    └→ MOCK generator       (offline / no-key fallback)   │   │
│  │    └→ SentimentAnalysisService                           │   │
│  │         └→ LlmClient (Feign) ──► OpenAI /v1/chat/...    │   │
│  │         └→ keyword-based mock (no API key fallback)      │   │
│  │    └→ AlertService  (email log + Slack log)              │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Key design decisions

Concern	Choice	Reason
Auth	Stateless JWT (jjwt 0.12.6)	No session state; horizontally scalable
DB	H2 (dev) / PostgreSQL (prod)	Fast local iteration; profile-switched
Feign clients	Graceful fallback to mock data	Works without real API keys for demo
Ingestion concurrency	Thread.ofVirtual() per keyword	Java 25 virtual threads; no thread-pool tuning
Sentiment	LLM call → keyword mock fallback	Always returns a result; offline-friendly
Security	Spring Security 7 + SecurityFilterChain	Stateless, CSRF disabled, CORS-ready

---

Endpoints

Authentication (public)

Method	Path	Body	Response
%%INLINE2%%	%%INLINE3%%	%%INLINE4%%	%%INLINE5%%
%%INLINE6%%	%%INLINE7%%	%%INLINE8%%	%%INLINE9%%

Keywords (JWT required)

Method	Path	Body	Response
%%INLINE10%%	%%INLINE11%%	—	[KeywordResponse]
%%INLINE13%%	%%INLINE14%%	%%INLINE15%%	%%INLINE16%% 201
%%INLINE17%%	%%INLINE18%%	%%INLINE19%%	%%INLINE20%%
%%INLINE21%%	%%INLINE22%%	—	204 No Content

KeywordRequest schema

{
  "keyword": "BrandPulse AI",
  "alertEmail": "cmo@example.com",
  "alertSlackWebhookUrl": "https://hooks.slack.com/...",
  "alertNegativeThreshold": 0.7,
  "alertViralThreshold": 1000
}

Dashboard (JWT required)

Method	Path	Query Params	Response
%%INLINE24%%	%%INLINE25%%	%%INLINE26%%	%%INLINE27%%
%%INLINE28%%	%%INLINE29%%	%%INLINE30%%	%%INLINE31%%

DashboardResponse schema

{
  "keywordId": 1,
  "keyword": "BrandPulse AI",
  "totalMentions": 142,
  "positiveMentions": 89,
  "neutralMentions": 31,
  "negativeMentions": 22,
  "positiveRatio": 0.627,
  "negativeRatio": 0.155,
  "dailyTrend": [
    { "date": "2026-05-19", "positive": 12, "neutral": 4, "negative": 3, "total": 19 }
  ],
  "topTopics": [
    { "topic": "pricing", "count": 34 },
    { "topic": "customer-support", "count": 21 }
  ],
  "topMentions": [ ... ]
}

---

Data Model

users
 ├── id (PK)
 ├── email (unique)
 ├── password (BCrypt)
 ├── name
 ├── role  [FREE | STARTER | PRO | ADMIN]
 └── active

tracked_keywords
 ├── id (PK)
 ├── user_id (FK → users)
 ├── keyword
 ├── active
 ├── alert_email
 ├── alert_slack_webhook_url
 ├── alert_negative_threshold   (default 0.70)
 ├── alert_viral_threshold      (default 1000)
 └── last_checked_at

mentions
 ├── id (PK)
 ├── keyword_id (FK → tracked_keywords)
 ├── source  [REDDIT | TWITTER | GOOGLE_NEWS | MOCK]
 ├── external_id (unique — deduplication key)
 ├── content
 ├── url, author
 ├── sentiment  [POSITIVE | NEUTRAL | NEGATIVE]
 ├── sentiment_score  (0.0–1.0)
 ├── topics  (comma-separated)
 ├── engagement_score
 └── analyzed, analyzed_at, mentioned_at

---

Business Analysis

Problem → Solution fit

Pain point	BrandPulse AI answer
Expensive tools (Brandwatch ~$1k/mo)	Freemium entry at $0
Fragmented data sources	Unified ingestion pipeline
Reactive crisis management	Real-time alerts on negative spikes
Manual analysis overhead	LLM classifies every mention automatically

Monetisation tiers

Plan	Price	Keywords	Data retention	Sources
Free	$0	1	7 days	Reddit + Mock
Starter	$29/mo	5	30 days	+ Twitter
Pro	$99/mo	25	90 days	+ Google News
Enterprise	Custom	Unlimited	2 years	Custom sources + API

Go-to-market

1. SEO content — "How to monitor brand mentions for free" → captures inbound intent.
2. Product Hunt launch — freemium drives viral coefficient.
3. Slack App Directory — alert integration = built-in distribution.
4. G2 / Capterra listings — self-serve B2B discovery.

---

How to Run

Quickstart (H2, no external keys needed)

cd solutions/2026-05-26-brandpulse-ai-api

# Compile
mvn clean compile

# Run with default profile (H2 in-memory, mock data, no API keys needed)
mvn spring-boot:run

# H2 console → http://localhost:8080/h2-console
# JDBC URL: jdbc:h2:mem:brandpulsedb

Register + use the API

# Register
curl -s -X POST http://localhost:8080/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com","password":"secret123"}' | jq

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

# Add a keyword
curl -s -X POST http://localhost:8080/api/v1/keywords \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"BrandPulse AI","alertNegativeThreshold":0.6}' | jq

# Trigger ingestion manually (the scheduler runs automatically every 15 min)
# Check dashboard (replace 1 with your keyword ID)
curl -s http://localhost:8080/api/v1/dashboard/1 \
  -H "Authorization: Bearer $TOKEN" | jq

With real LLM + PostgreSQL (production-like)

# Set env vars
export SPRING_PROFILES_ACTIVE=local
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/brandpulse
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=secret
export APP_EXTERNAL_APIS_LLM_API_KEY=sk-...
export APP_JWT_SECRET="your-64-char-production-secret-here"

mvn spring-boot:run

---

References

• BrandCapsule AI — B2B SaaS opportunities
• Spring Boot 4.0 Reference
• Spring Security 7 — Stateless JWT
• Spring Cloud OpenFeign 4.x
• jjwt 0.12.x API
• OpenAI Chat Completions API
• Reddit JSON API

---

FinOps Analysis para BrandPulse AI

💰 Estimación de Costos Operativos Mensuales:

Para una micro-startup como BrandPulse AI, la gestión de costos es crucial. Hemos desglosado los gastos operativos esperados para un MVP inicial con 20 clientes de pago:

• LLM Tokens (OpenAI gpt-4o-mini): ~$63

* Basado en un estimado de 330 millones de tokens mensuales (600,000 menciones analizadas, con ~500 tokens de input y ~50 de output por mención).

• Cloud Hosting (Servidor Spring Boot): ~$25

* Equivalente a una instancia AWS EC2 t3.small, suficiente para la aplicación Spring Boot inicial.

• Base de Datos (PostgreSQL): ~$15

* Equivalente a una instancia AWS RDS t3.micro, adecuada para almacenar usuarios, palabras clave, menciones y resultados de análisis.

• APIs Externas (Fuentes de Datos): ~$10

* Estimación conservadora para el uso de APIs de fuentes de datos (ej. Reddit, Google News o APIs de noticias de bajo costo). Se asume que se priorizarán los niveles gratuitos o de bajo costo para el MVP, dado que las APIs de X/Twitter pueden ser costosas.

• Monitoreo y Otros: ~$2

* Incluye servicios básicos de monitoreo de la nube y transferencia de datos mínima.

Total de Costos Operativos Mensuales Estimados: $115

💸 Ingresos Mensuales Estimados:

Con un modelo de monetización B2B SaaS freemium y un precio de nivel de entrada de $25 por cliente, y asumiendo una base inicial de 20 clientes de pago:

Ingreso Mensual Estimado: 20 clientes * $25/cliente = $500

📈 Margen de Beneficio:

Considerando los ingresos y costos estimados:

• Beneficio Bruto: $500 (Ingresos) - $115 (Costos) = $385
• Margen de Beneficio: ($385 / $500) * 100 = 77%

Un margen de beneficio del 77% es excelente para una fase inicial, indicando una buena viabilidad del modelo de negocio con los costos estimados. Sin embargo, es crucial monitorear la escalabilidad de los costos de LLM y APIs de datos a medida que la base de usuarios crece.

🚀 Optimización de Costos (FinOps):

Para mantener este margen y asegurar la rentabilidad a medida que BrandPulse AI escale, se recomiendan las siguientes estrategias de optimización de FinOps:

1. Optimización de Uso de LLM:

* Prompt Engineering: Refinar constantemente los prompts para ser más concisos y eficientes, minimizando los tokens de entrada y salida sin sacrificar la calidad del análisis. * Caching de Respuestas: Implementar una capa de caché para las menciones ya analizadas o para respuestas comunes del LLM, evitando llamadas redundantes para contenido idéntico o muy similar. * Batch Processing: Agrupar las menciones para el análisis del LLM en lotes, especialmente para tareas no críticas en tiempo real, lo que puede reducir los costos por token en algunos proveedores y mejorar la eficiencia. Filtrado Pre-LLM: Desarrollar algoritmos de filtrado para descartar menciones irrelevantes antes* de enviarlas al LLM, reduciendo significativamente el volumen de tokens procesados. * Evaluación de Modelos: Continuar evaluando modelos de LLM más pequeños o de código abierto (ej. Llama 3) para tareas específicas donde la complejidad es menor, o explorar APIs de LLM alternativas con precios más competitivos si la calidad es adecuada.

1. Optimización de Infraestructura Cloud:

* Serverless para Tareas Programadas: Migrar la lógica de ingesta y análisis (@Scheduled) a servicios serverless como AWS Lambda o Google Cloud Functions. Esto permite pagar solo por el tiempo de ejecución de las funciones, lo cual es más económico que mantener una VM 24/7 si la carga de trabajo es intermitente. * Autoscaling: Implementar políticas de autoescalado para el servidor de Spring Boot (ej. en un grupo de Auto Scaling de AWS) y la base de datos (ej. Aurora Serverless) para ajustar dinámicamente los recursos a la demanda y evitar el sobreaprovisionamiento. * Contenerización con Fargate/Cloud Run: Dockerizar la aplicación y desplegarla en plataformas como AWS Fargate o Google Cloud Run, que ofrecen modelos de pago por uso más granulares y reducen la sobrecarga de gestión de infraestructura.

1. Gestión de APIs de Fuentes de Datos:

* Estrategia de Ingesta Inteligente: Priorizar las fuentes de datos con APIs gratuitas o de muy bajo costo. Si el acceso a APIs costosas (como X/Twitter) se vuelve indispensable, planificar cuidadosamente el volumen de llamadas y explorar alternativas como servicios de scraping gestionados. * Frecuencia de Sondeo Dinámica: Ajustar la frecuencia de sondeo de las APIs externas basándose en la importancia de la palabra clave, el nivel de servicio del cliente o la actividad histórica de la fuente. No todas las fuentes necesitan ser consultadas a la misma velocidad.

La implementación proactiva de estas estrategias de FinOps permitirá a BrandPulse AI mantener su rentabilidad y escalar de manera sostenible.