BrandVoice AI API

Hyper-Personalised Content Generation for Brand Voice — Spring Boot 4.0.4 MVP

---

Concept

Marketing teams waste hours editing AI-generated content because generic tools ignore brand voice. BrandVoice AI solves this with a RAG pipeline that retrieves proprietary brand context before every generation, so the output is always on-brand, on-tone, and ready to publish.

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        HTTP Clients / CMS                           │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ REST (JWT Bearer)
┌───────────────────────────────▼─────────────────────────────────────┐
│                   Spring Boot 4.0.4 API Layer                       │
│   AuthController  BrandProfileController  ContentController         │
└──────────┬───────────────────┬──────────────────────────────────────┘
           │                   │
    ┌──────▼──────┐    ┌───────▼──────────────────────────┐
    │  AuthService │    │ BrandProfileService               │
    │  JwtService  │    │  └─ @Async processDocumentAsync  │
    └─────────────┘    │     (Virtual Threads)             │
                       └───────┬──────────────────────────┘
                               │
                  ┌────────────▼────────────────────────────┐
                  │  ContentGenerationService               │
                  │  1. RAG keyword retrieval               │
                  │  2. Enriched prompt construction        │
                  │  3. LlmClient (Feign → OpenAI API)      │
                  │  4. ComplianceService scoring           │
                  └───────────────────────────────────────┘
                               │
                  ┌────────────▼────────────────────────────┐
                  │  H2 (dev) / PostgreSQL (prod)           │
                  │  users, brand_profiles,                 │
                  │  content_documents, content_generations │
                  └─────────────────────────────────────────┘

Key Design Decisions

Decision	Rationale
JWT stateless auth	No session state — scales horizontally
@Async + Virtual Threads	Document ingestion is I/O bound; virtual threads prevent blocking
Keyword-based RAG simulation	No pgvector dependency; swap for real vector DB in production
LLM fallback to mock	App runs fully without an API key in dev/test
RFC 9457 ProblemDetail	Standardised error responses across all endpoints

---

Endpoints

Auth (/api/v1/auth) — Public

Method	Path	Description
%%INLINE2%%	%%INLINE3%%	Register a new user, returns JWT
%%INLINE4%%	%%INLINE5%%	Login with email + password, returns JWT

Brand Profiles (/api/v1/profiles) — Authenticated

Method	Path	Description
%%INLINE7%%	%%INLINE8%%	Create a Brand Voice Profile
%%INLINE9%%	%%INLINE10%%	List owned profiles
%%INLINE11%%	%%INLINE12%%	Get profile by ID
%%INLINE13%%	%%INLINE14%%	Update profile
%%INLINE15%%	%%INLINE16%%	Delete profile + documents
%%INLINE17%%	%%INLINE18%%	Ingest a brand document (async, returns 202)
%%INLINE19%%	%%INLINE20%%	List ingested documents

Content & Compliance (/api/v1) — Authenticated

Method	Path	Description
%%INLINE22%%	%%INLINE23%%	Generate on-brand content (RAG + LLM)
%%INLINE24%%	%%INLINE25%%	Score existing content against a profile
%%INLINE26%%	%%INLINE27%%	Generation history for the current user

---

Request/Response Examples

Register

POST /api/v1/auth/register
{
  "name": "Acme Marketing",
  "email": "user@acme.com",
  "password": "s3cur3!"
}
→ 201 { "token": "eyJ...", "userId": "...", "email": "...", "name": "..." }

Create Brand Profile

POST /api/v1/profiles
Authorization: Bearer <token>
{
  "name": "Acme Corporate Voice",
  "description": "B2B SaaS company targeting enterprise buyers",
  "toneKeywords": "bold,innovative,trustworthy,clear,professional",
  "styleGuidelines": "Use active voice. Short sentences. Avoid jargon.",
  "prohibitedTerms": "cheap,basic,simple,unfortunately"
}

Ingest Brand Document

POST /api/v1/profiles/{id}/documents
Authorization: Bearer <token>
{
  "fileName": "brand-guidelines-2026.txt",
  "content": "Our brand voice is defined by three pillars: Innovation..."
}
→ 202 { "id": "...", "status": "PENDING", ... }

Generate Content

POST /api/v1/generate
Authorization: Bearer <token>
{
  "profileId": "...",
  "contentType": "EMAIL",
  "brief": "Write a cold outreach email for enterprise CTOs about our new AI analytics platform",
  "maxTokens": 600
}
→ {
  "generationId": "...",
  "generatedContent": "...",
  "complianceScore": 87.5,
  "complianceSummary": "Score: 87.5 (B). Content is well-aligned with your brand voice."
}

Score Compliance

POST /api/v1/compliance/score
Authorization: Bearer <token>
{
  "profileId": "...",
  "content": "This simple and cheap tool is basically all you need."
}
→ {
  "overallScore": 22.0,
  "grade": "F",
  "prohibitedTermFound": ["simple", "cheap", "basically"],
  "missingKeywords": ["bold", "innovative", "trustworthy"],
  "suggestions": ["Remove prohibited terms: simple, cheap, basically"]
}

---

Business Analysis

Problem

Content marketing teams at B2B SaaS companies spend 40–60% of their time editing AI-generated content to align with brand voice — defeating the purpose of AI tooling.

Solution

BrandVoice AI ingests brand documents, builds a rich voice profile, and uses RAG to ground every LLM call in proprietary brand context. The compliance scorer gives real-time feedback.

Target Audience

• Content marketing teams (3–20 people) at B2B SaaS companies
• Digital marketing agencies managing multiple brand identities

Monetisation (Tiered SaaS)

Tier	Price	Limits
Starter	$49/mo	2 profiles, 3 users, 100 generations
Growth	$149/mo	10 profiles, 10 users, 500 generations
Enterprise	Custom	Unlimited, SSO, custom LLM

Market References

• The Importance of Brand Voice — Semrush
• RAG Explained — AWS
• Writer.com — Similar product

---

How to Run

Prerequisites

• Java 25
• Maven 3.9+

Dev (H2 in-memory, mock LLM)

cd solutions/2026-06-05-brandvoice-ai-api
mvn spring-boot:run

App starts on http://localhost:8080. H2 Console: http://localhost:8080/h2-console JDBC URL: jdbc:h2:mem:brandvoicedb

With Real LLM (OpenAI)

export LLM_API_KEY=sk-...
export LLM_MODEL=gpt-4o
mvn spring-boot:run

With PostgreSQL (Production)

export SPRING_PROFILES_ACTIVE=prod
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/brandvoice
export SPRING_DATASOURCE_USERNAME=brandvoice
export SPRING_DATASOURCE_PASSWORD=secret
export LLM_API_KEY=sk-...
export JWT_SECRET=<base64-256bit-key>
mvn spring-boot:run

Build

mvn clean package
java -jar target/brandvoice-ai-api-0.0.1-SNAPSHOT.jar

---

Technology Stack

Layer	Technology
Framework	Spring Boot 4.0.4 / Spring Framework 7
Language	Java 25 (Records, Virtual Threads, Text Blocks)
Security	Spring Security 7 + JJWT 0.12.6
Persistence	Spring Data JPA + Hibernate / H2 (dev) / PostgreSQL (prod)
HTTP Client	Spring Cloud OpenFeign 4.2.1
JSON	Jackson 3 (tools.jackson.*)
Async	Java 25 Virtual Threads + Spring @Async
Error Handling	RFC 9457 ProblemDetail

---

FinOps Analysis para BrandVoice AI

Resumen Ejecutivo

BrandVoice AI muestra un modelo de negocio con un potencial de margen de beneficio extremadamente alto, impulsado por los bajos costos operativos de los LLMs de última generación (como GPT-4o-mini) y una infraestructura cloud lean para un MVP. Con una base inicial de 10 clientes pagando $75/mes, la startup puede alcanzar un margen de beneficio del 88%, lo que es excelente para un SaaS B2B.

Estimación de Costos Operativos Mensuales

1. Estimación de Tokens LLM:

Basado en 10 clientes, cada uno generando un promedio de 50 contenidos al mes (incluyendo borradores y revisiones de cumplimiento de marca), y considerando un promedio de 3500 tokens por interacción (prompt + contexto RAG + output) y 1000 tokens por chequeo de cumplimiento: Generación de Contenido: 10 clientes 50 generaciones/cliente * 3500 tokens/generación = 1.75M tokens Puntuación de Cumplimiento: 10 clientes 50 generaciones/cliente 2 chequeos/generación 1000 tokens/chequeo = 1M tokens

• Ingesta de Perfiles de Marca (inicial): Estimado adicional por procesamiento inicial de documentos.
• Total Estimado: ~2.75M tokens/mes, redondeado a ~3M tokens/mes para incluir un buffer.

2. Desglose de Costos Mensuales:

• LLM (OpenAI GPT-4o-mini):

Input: 2M tokens (estimado) $0.15/1M tokens = $0.30 Output: 1M tokens (estimado) $0.60/1M tokens = $0.60 * Costo Total LLM: ~$0.90. Se asigna un presupuesto de $15/mes para cubrir el uso de modelos ligeramente más caros (ej. GPT-4o para tareas críticas) y un buffer de seguridad.

• Cloud Hosting (AWS):

* EC2 (t3.medium): $30-40/mes (para la API Spring Boot y procesamiento asíncrono). * RDS (t3.small PostgreSQL con pgvector): $30-40/mes (para base de datos relacional y vectorial). * S3 (Almacenamiento de documentos de marca): $1-5/mes. * Monitoring (CloudWatch, logs): $1-5/mes. * Costo Total Cloud: Estimado en $75/mes para una infraestructura robusta de MVP.

• Costo Mensual Total: $15 (LLM) + $75 (Cloud) = $90/mes.

Estimación de Ingresos Mensuales

Considerando un modelo de monetización B2B SaaS por niveles y un público objetivo de medianas empresas y agencias:

• Nivel Básico/Intermedio: $75/mes por cliente (ej. 2 perfiles de marca, 5 usuarios, 50 generaciones de contenido).
• Clientes Iniciales: 10 clientes.

Ingreso Mensual Estimado: 10 clientes $75/cliente = $750/mes.

Margen de Beneficio

• Ingreso Total: $750/mes
• Costo Total: $90/mes
• Beneficio Bruto: $750 - $90 = $660/mes

Margen de Beneficio: (($660) / $750) 100 = 88%.

Optimizaciones FinOps Clave

1. Optimización del Uso de LLM: Implementar estrategias de caching para reducir llamadas repetitivas. Refinar las prompts y la recuperación de RAG para minimizar el tamaño del contexto. Priorizar el uso de modelos más económicos (como GPT-4o-mini) para la mayoría de las tareas y reservar los modelos premium para funcionalidades donde el valor añadido justifique el costo.
2. Gestión de Infraestructura Cloud: Monitorear activamente el uso de recursos para asegurar que las instancias de EC2 y RDS estén correctamente dimensionadas, evitando el sobreaprovisionamiento. A medida que la carga de trabajo se estabilice, explorar opciones como AWS Savings Plans o Reserved Instances para reducir los costos de infraestructura a largo plazo.
3. Almacenamiento Inteligente: Utilizar clases de almacenamiento de S3 con niveles inteligentes (Intelligent-Tiering) para mover automáticamente los datos a las clases de almacenamiento más rentables según el patrón de acceso.
4. Procesamiento Asíncrono y en Lotes: Aprovechar las capacidades de Java 25 y Spring @Async para procesar la ingesta de documentos y las tareas de análisis intensivas de forma asíncrona y en lotes durante períodos de baja demanda, lo que puede permitir el uso de recursos de menor costo o de menor prioridad (ej. Spot Instances si es aplicable a los jobs).
5. Monitoreo y Alertas de Costos: Configurar alertas en la nube (ej. AWS Budgets) para ser notificado si los costos superan ciertos umbrales, permitiendo una acción proactiva para controlar el gasto.