PersonaGen AI — API Explainer

Concept

PersonaGen AI is a B2B SaaS API that automates the creation of personalised marketing copy at scale. Marketing teams and e-commerce operators submit batches of customer data; the platform clusters them into audience segments and then calls an LLM (OpenAI-compatible) to generate on-brand email, social-post, and ad-copy variants for each segment — honouring a configurable Brand Voice.

The result moves through a DRAFT → APPROVED → EXPORTED lifecycle so teams can review and tweak AI output before it goes live.

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   Spring Boot 4.0.4                 │
│                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │ AuthController│  │AudienceCtrl │  │ContentCtrl│  │
│  └──────┬───────┘  └──────┬───────┘  └────┬─────┘  │
│         │                 │               │         │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌───▼──────┐  │
│  │  AuthService │  │AudienceService│  │ContentSvc│  │
│  └──────┬───────┘  └──────┬───────┘  └────┬─────┘  │
│         │                 │               │         │
│  ┌──────▼─────────────────▼───────────────▼──────┐  │
│  │               JPA Repositories                 │  │
│  │   User · Company · BrandVoice · Segment        │  │
│  │   CustomerProfile · GeneratedContent           │  │
│  └──────────────────────┬────────────────────────┘  │
│                         │                           │
│  ┌──────────────────────▼────────────────────────┐  │
│  │        H2 (dev) / PostgreSQL (prod)            │  │
│  └────────────────────────────────────────────────┘  │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │  OpenFeign LlmClient → OpenAI /completions  │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  JWT Auth filter · Spring Security 7 · Virtual Threads│
└─────────────────────────────────────────────────────┘

Key design choices

Concern	Decision
Concurrency	Tomcat runs on Java 25 virtual threads → no thread-pool tuning needed for LLM I/O
Auth	Stateless JWT (jjwt 0.12.6 · HS256) — token carries company context
LLM integration	OpenFeign declarative client; falls back to mock copy when app.llm.enabled=false
Multi-tenancy	Every entity is scoped to company_id; resolved from the JWT on every request
Persistence	JPA with H2 for dev (create-drop) and PostgreSQL for prod
DTOs	Java 25 Records — immutable, zero boilerplate
Error responses	RFC 7807 %%INLINE3%% via %%INLINE4%%

---

Endpoints

Authentication — public

Method	Path	Description
%%INLINE5%%	%%INLINE6%%	Create user + company, receive JWT
%%INLINE7%%	%%INLINE8%%	Authenticate, receive JWT

All other endpoints require Authorization: Bearer <token>.

Brand Voice

Method	Path	Description
%%INLINE10%%	%%INLINE11%%	Create or update brand voice (tone, style, guidelines)
%%INLINE12%%	%%INLINE13%%	Retrieve current brand voice

Audience Segmentation

Method	Path	Description
%%INLINE14%%	%%INLINE15%%	Ingest customer profiles → auto-segment by age bracket
%%INLINE16%%	%%INLINE17%%	List all segments
%%INLINE18%%	%%INLINE19%%	Single segment detail

Content Generation & Dashboard

Method	Path	Description
%%INLINE20%%	%%INLINE21%%	Generate AI copy for a segment + campaign objective
%%INLINE22%%	%%INLINE23%%	List all generated content (dashboard)
%%INLINE24%%	%%INLINE25%%	Single content detail
%%INLINE26%%	%%INLINE27%%	Edit copy before approval
%%INLINE28%%	%%INLINE29%%	Approve content
%%INLINE30%%	%%INLINE31%%	Export as plain text (marks EXPORTED)

---

Quick-start (dev — H2 in-memory)

# 1. Clone / navigate to project
cd solutions/2026-04-19-personagen-ai-api

# 2. Compile & run
mvn spring-boot:run

# 3. Register a company + user
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@acme.com","password":"password123","companyName":"ACME Corp"}'
# → { "token": "eyJ...", "companyId": 1 }

# 4. Set token
TOKEN="eyJ..."

# 5. Define Brand Voice
curl -X PUT http://localhost:8080/api/v1/brand-voice \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tone":"playful","style":"conversational","guidelines":"Always end with a CTA","targetPersona":"Online shoppers aged 25-40"}'

# 6. Ingest customer profiles and segment
curl -X POST http://localhost:8080/api/v1/audiences/segment \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profiles": [
      {"name":"Alice","age":28,"location":"NYC","purchaseHistory":"electronics, fashion","externalId":"c001"},
      {"name":"Bob","age":45,"location":"LA","purchaseHistory":"sports, home","externalId":"c002"},
      {"name":"Carol","age":32,"location":"NYC","purchaseHistory":"beauty, fashion","externalId":"c003"}
    ]
  }'
# → [{ "id": 1, "name": "Young Adults (20-29)", ... }, ...]

# 7. Generate content
curl -X POST http://localhost:8080/api/v1/content/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"segmentId":1,"campaignObjective":"summer_promo","contentType":"email"}'

# 8. Review / edit
curl -X PATCH http://localhost:8080/api/v1/content/1/review \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated email copy here..."}'

# 9. Approve
curl -X POST http://localhost:8080/api/v1/content/1/approve \
  -H "Authorization: Bearer $TOKEN"

# 10. Export
curl http://localhost:8080/api/v1/content/1/export \
  -H "Authorization: Bearer $TOKEN"

Enable real LLM

export LLM_API_KEY="sk-..."
export LLM_ENABLED=true
mvn spring-boot:run

Production (PostgreSQL)

# application-prod.yml (create separately)
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/personagen
    username: ${DB_USER}
    password: ${DB_PASS}
  jpa:
    database-platform: org.hibernate.dialect.PostgreSQLDialect
    hibernate:
      ddl-auto: validate  # use Flyway/Liquibase for migrations

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

---

Business Analysis

Problem → Solution fit

Pain	PersonaGen solution
Manual copy creation is slow	Fully automated via LLM in < 2 s
Generic campaigns = low CTR	Segment-specific copy tuned to audience characteristics
Brand inconsistency across channels	Brand Voice system enforces tone/style on every generation
No review step → errors go live	DRAFT → APPROVED → EXPORTED lifecycle with inline editor

Monetisation tiers (proposed)

Tier	Profiles/month	Generations/month	Price
Starter	1 000	50	$49
Growth	25 000	500	$199
Scale	Unlimited	Unlimited	$699+

Competitive advantage

• API-first: integrates directly into existing marketing stacks (Shopify, HubSpot, etc.)
• Brand Voice layer: differentiates from raw LLM wrappers — output is always on-brand
• Virtual threads: handles bursty LLM I/O without horizontal scaling during MVP phase

---

References

• Generative AI for SaaS — text.com
• Spring Boot 4.0 Reference
• Spring Security 7 JWT Guide
• Spring Cloud OpenFeign 4.2
• jjwt 0.12 API
• Java 25 Virtual Threads

---

FinOps Analysis

Estimación de Costos Operativos

Para PersonaGen AI, los costos operativos iniciales se han estimado considerando una fase de micro-startup con un MVP funcional. La estrategia se centra en la eficiencia y la escalabilidad a bajo costo.

1. Consumo de Tokens LLM: Se estima un consumo mensual de aproximadamente 1 millón de tokens. Esta cifra incluye el procesamiento de la ingesta y segmentación de audiencias (prompts para clasificar perfiles de cliente) y la generación de contenido (prompts detallados para la creación de textos de marketing más las respuestas generadas). Se asume el uso de OpenAI GPT-4 Turbo por su equilibrio entre calidad y coste para contenido de marketing.

2. Desglose de Costos Mensuales:

• LLM (OpenAI GPT-4 Turbo): $15/mes (basado en ~1M tokens, con una división aproximada de 70% entrada y 30% salida).
• Cloud Hosting (AWS/GCP - Compute): $25/mes (equivalente a una instancia t3.small de AWS EC2 para la aplicación Spring Boot, incluyendo una pequeña fracción por transferencia de datos y monitoreo básico).
• Base de Datos (AWS RDS PostgreSQL): $15/mes (equivalente a una instancia db.t3.micro de RDS, adecuada para un MVP con datos de usuarios, perfiles y BrandVoice).
• Total Estimado: $55/mes

3. Costos de Infraestructura Cloud: La infraestructura base se ha presupuestado en $40/mes, desglosada en:

• Compute: $25/mes (instancia t3.small de AWS EC2 o equivalente).
• Base de Datos: $15/mes (instancia db.t3.micro de AWS RDS para PostgreSQL).

4. Costos de APIs Externas: El principal costo de API externa proviene del proveedor de LLM, estimado en $15/mes para OpenAI GPT-4 Turbo.

Estimación de Ingresos y Margen de Beneficio

1. Ingreso Mensual Estimado: Considerando un modelo de monetización API-first SaaS por niveles, se asume un nivel de suscripción básico de $25/mes. Para una micro-startup en fase MVP, se proyecta la adquisición de 20 clientes iniciales. Esto resulta en un ingreso mensual estimado de $500/mes (20 clientes x $25).

2. Margen de Beneficio (Profit Margin):

• Ingresos: $500/mes
• Costos Totales: $55/mes
• Beneficio Bruto: $500 - $55 = $445/mes

Margen de Beneficio: ($445 / $500) 100 = 89%

El alto margen de beneficio inicial es típico de un modelo SaaS con bajos costos operativos en fase MVP y una base de clientes reducida. Este margen es saludable y permite reinvertir en desarrollo y crecimiento.

Optimización de Costos (FinOps)

Para mantener y mejorar este margen a medida que la startup escala, se proponen las siguientes optimizaciones FinOps:

1. Optimización del Uso de LLM:

* Caché Inteligente: Implementar un sistema de caché para respuestas de LLM, especialmente para solicitudes de contenido o segmentación que sean recurrentes o tengan parámetros de entrada similares. Esto reduce llamadas redundantes a la API del LLM. * Tiering de Modelos: Utilizar modelos LLM más económicos (ej. GPT-4o-mini, o incluso modelos open-source como Llama 3 auto-hosteados en instancias spot) para generar borradores, contenido de menor prioridad o para ofrecer distintos niveles de calidad/precio a los usuarios. * Prompt Engineering Eficiente: Refinar los prompts para ser más concisos y directos, minimizando el número de tokens de entrada sin comprometer la calidad de la salida. * Procesamiento por Lotes (Batch Processing): Agrupar las solicitudes de segmentación de audiencia o generación de contenido que no requieren inmediatez y procesarlas en lotes. Esto puede reducir los costos de API y permitir el uso de recursos computacionales más baratos (ej. instancias spot) durante horas de menor demanda.

1. Optimización de Infraestructura Cloud:

* Arquitectura Serverless: Migrar componentes específicos, como el procesamiento de la segmentación de audiencia o webhooks de ingesta de datos, a funciones serverless (ej. AWS Lambda, Google Cloud Functions). Esto permite pagar solo por la ejecución real, eliminando costos de instancias inactivas. * Contenedores en Plataformas Gestionadas: Utilizar servicios de contenedores gestionados como AWS Fargate o Google Cloud Run. Ofrecen escalado automático y pago por uso, reduciendo la sobrecarga de gestión y optimizando el coste. * Base de Datos Elástica: Considerar bases de datos serverless como Amazon Aurora Serverless o Google Cloud SQL Serverless, que escalan automáticamente y pueden reducir a cero el coste cuando no hay actividad, ideal para picos de uso o períodos de baja demanda. * Monitoreo y Logging: Auditar y optimizar la verbosidad de los logs y métricas. Utilizar el muestreo (sampling) para datos de monitoreo en entornos de producción para reducir los costos de ingesta y almacenamiento.

1. Estrategia de Crecimiento y Pricing:

* Niveles de Suscripción: A medida que la base de usuarios crezca, refinar los niveles de suscripción para alinearlos más estrechamente con el valor entregado y los costos operativos asociados (ej. límites de tokens, número de segmentos, calidad del LLM). * Análisis de Uso: Monitorear de cerca los patrones de uso de los clientes para identificar funcionalidades costosas y optimizarlas, o para ajustar la estructura de precios en consecuencia.