ClauseClarity AI — Contract Review Automation API

Concepto

ClauseClarity AI es un micro-SaaS B2B que automatiza la revisión de contratos legales mediante IA generativa. Los equipos legales de PYMEs y startups suben documentos PDF/DOCX y obtienen en segundos un análisis estructurado de riesgos con sistema de semáforo (🔴 Rojo / 🟡 Ámbar / 🟢 Verde) para cada cláusula clave: Vigencia, Responsabilidad, Confidencialidad y Terminación.

Problema: Revisión manual de contratos = horas de trabajo + riesgo de errores humanos + coste de abogados. Solución: Análisis LLM en segundos, con resultado estructurado, exportable y trazable en BD.

---

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT (curl / frontend)                  │
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTPS + JWT Bearer
┌───────────────────────────────▼─────────────────────────────────┐
│                    Spring Boot 4.0.4 API                         │
│                                                                   │
│  ┌──────────────┐  ┌──────────────────────┐  ┌───────────────┐  │
│  │ AuthController│  │  ContractController  │  │  JwtAuthFilter│  │
│  └──────┬───────┘  └──────────┬───────────┘  └───────────────┘  │
│         │                     │                                   │
│  ┌──────▼───────┐  ┌──────────▼───────────┐                     │
│  │  AuthService │  │   ContractService     │                     │
│  └──────────────┘  └──────────┬───────────┘                     │
│                                │ @Async (Virtual Thread)         │
│                    ┌───────────▼───────────┐                     │
│                    │   AnalysisService     │                     │
│                    └───────────┬───────────┘                     │
│                                │                                  │
│           ┌────────────────────┼──────────────┐                  │
│           ▼                    ▼               ▼                  │
│  ┌──────────────┐  ┌──────────────────┐  ┌──────────────┐       │
│  │StorageService│  │TextExtractService│  │  LlmClient   │       │
│  │ (in-memory)  │  │  (PDF/DOCX MVP)  │  │  (Feign →    │       │
│  └──────────────┘  └──────────────────┘  │  OpenAI API) │       │
│                                           └──────────────┘       │
│                                                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              H2 (dev) / PostgreSQL (prod)                   │  │
│  │   users | contracts | clause_analyses                       │  │
│  └────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Capas

Capa	Clases principales
Controller	%%INLINE0%%, %%INLINE1%%
Service	%%INLINE2%%, %%INLINE3%%, %%INLINE4%%, %%INLINE5%%, %%INLINE6%%, %%INLINE7%%
Repository	%%INLINE8%%, %%INLINE9%%, ClauseAnalysisRepository
Model	%%INLINE11%%, %%INLINE12%%, %%INLINE13%%, %%INLINE14%%, ContractStatus
Security	%%INLINE16%%, %%INLINE17%%, %%INLINE18%%, %%INLINE19%%
Feign	%%INLINE20%%, %%INLINE21%%, LlmResponse
Config	%%INLINE23%%, %%INLINE24%%, %%INLINE25%%, %%INLINE26%%

---

Endpoints

Autenticación (públicos)

Método	Path	Descripción
%%INLINE27%%	%%INLINE28%%	Registra un nuevo usuario, devuelve JWT
%%INLINE29%%	%%INLINE30%%	Login, devuelve JWT

Register body:

{
  "fullName": "Ana García",
  "email": "ana@empresa.com",
  "password": "miPassword123"
}

Respuesta auth:

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "email": "ana@empresa.com",
  "fullName": "Ana García",
  "plan": "FREE"
}

Contratos (requieren Authorization: Bearer <token>)

Método	Path	Descripción
%%INLINE32%%	%%INLINE33%%	Carga un PDF/DOCX y dispara el análisis asíncrono
%%INLINE34%%	%%INLINE35%%	Lista todos los contratos del usuario
%%INLINE36%%	%%INLINE37%%	Detalle + panel de riesgos con semáforo
%%INLINE38%%	%%INLINE39%%	Descarga informe exportable (TXT estructurado)

Carga de contrato:

curl -X POST http://localhost:8080/api/contracts/analyze \
  -H "Authorization: Bearer <token>" \
  -F "file=@contrato.pdf"

Respuesta inmediata (202 Accepted):

{
  "contractId": "3fa85f64-5717-4562-b3fc",
  "fileName": "contrato.pdf",
  "status": "PENDING",
  "message": "Contrato recibido. El análisis está en curso. Consulte GET /api/contracts/3fa85f64..."
}

Panel de análisis (GET /api/contracts/{id}):

{
  "id": "3fa85f64-5717-4562-b3fc",
  "fileName": "contrato.pdf",
  "status": "COMPLETED",
  "uploadedAt": "2026-05-19T10:30:00",
  "analyzedAt": "2026-05-19T10:30:05",
  "clauses": [
    {
      "id": "a1b2c3d4...",
      "clauseType": "Responsabilidad",
      "content": "El prestador será responsable de todos los daños...",
      "summary": "Responsabilidad ilimitada del prestador.",
      "riskLevel": "RED",
      "riskReason": "La responsabilidad ilimitada supone riesgo financiero crítico."
    },
    {
      "clauseType": "Confidencialidad",
      "riskLevel": "GREEN",
      ...
    }
  ]
}

---

Análisis de Negocio

Propuesta de Valor

• Ahorro de tiempo: De 2-4 horas de revisión manual a < 30 segundos.
• Reducción de riesgo: Identificación automática de cláusulas abusivas antes de firmar.
• Accesibilidad: Herramienta enterprise-grade al alcance de PYMEs y autónomos.

Modelo de Monetización (Freemium B2B SaaS)

Plan	Precio	Límites
FREE	0€	2 contratos/mes, análisis básico
PRO	49€/mes	50 contratos/mes, informe PDF, historial
ENTERPRISE	299€/mes	Ilimitado, API access, SSO, soporte prioritario

TAM (Total Addressable Market)

• 3.5M+ PYMEs en España que gestionan contratos regularmente.
• Mercado global de LegalTech: $35B en 2026, CAGR 10.4%.
• Coste por análisis con abogado: €150-500/hora vs < €0.10 con GPT-4o.

Ventaja Competitiva MVP

1. Especialización: Prompt engineering específico para derecho contractual español/europeo.
2. Velocidad de salida: MVP funcional en días, no meses.
3. Integración: API REST estándar, integrable con cualquier ERP/CRM.

---

Tecnologías

Componente	Tecnología
Framework	Spring Boot 4.0.4 + Spring Framework 7.x
Lenguaje	Java 25 con Virtual Threads
Seguridad	Spring Security 7 + JWT (JJWT 0.12.6)
Persistencia	JPA/Hibernate + H2 (dev) / PostgreSQL (prod)
IA	LLM via OpenFeign → OpenAI GPT-4o (o compatible)
Serialización	Jackson 3.x (tools.jackson.*)
Async	%%INLINE41%% + %%INLINE42%%

---

Cómo Ejecutar

Prerequisitos

• Java 25+
• Maven 3.9+

Modo Desarrollo (H2 + Mock LLM)

cd solutions/2026-05-19-clause-clarity-api
mvn clean spring-boot:run

La app arranca con:

• Base de datos H2 in-memory (auto-configurada por Spring Boot)
• Análisis LLM mock — no requiere API key. Devuelve 4 cláusulas de ejemplo.
• Puerto: http://localhost:8080

Modo Producción

Configurar variables de entorno o application-prod.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/clauseclarity
    username: ${DB_USER}
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate

app:
  jwt-secret: ${JWT_SECRET}           # min 32 chars
  jwt-expiration-ms: 86400000
  llm-api-key: ${OPENAI_API_KEY}
  llm-api-url: https://api.openai.com
  llm-model: gpt-4o

mvn clean package -DskipTests
java -jar target/clause-clarity-api-0.0.1-SNAPSHOT.jar \
  --spring.profiles.active=prod

Ejemplo Completo con curl

# 1. Registrar usuario
curl -s -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Ana García","email":"ana@test.com","password":"pass123"}' | jq .

# 2. Obtener token (guardar en variable)
TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@test.com","password":"pass123"}' | jq -r .token)

# 3. Subir contrato (cualquier fichero de texto para el MVP)
echo "Cláusula 1: Vigencia de 12 meses..." > contrato.txt
ID=$(curl -s -X POST http://localhost:8080/api/contracts/analyze \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@contrato.txt" | jq -r .contractId)

# 4. Esperar 1-2s y consultar análisis
sleep 2
curl -s http://localhost:8080/api/contracts/$ID \
  -H "Authorization: Bearer $TOKEN" | jq .

# 5. Descargar informe
curl -s http://localhost:8080/api/contracts/$ID/report \
  -H "Authorization: Bearer $TOKEN" -o informe.txt && cat informe.txt

---

Referencias

• GroovyWeb — Best AI SaaS Product Ideas 2026
• Spring Boot 4.0 Reference
• JJWT 0.12.x Reference
• OpenAI Chat Completions API
• Spring Cloud OpenFeign

---

FinOps Analysis for ClauseClarity AI

1. Estimación de Tokens LLM Mensuales

Para la estimación, consideramos un escenario inicial de 20 clientes de pago, cada uno analizando un promedio de 5 contratos al mes. Asumiendo un contrato promedio de 15 páginas (6000 palabras) y un factor de conversión de 1.3 tokens/palabra, más una sobrecarga de prompt de 2000 tokens y 2000 tokens de salida estructurada por contrato:

• Input por contrato: (6000 palabras * 1.3) + 2000 tokens (prompt) = 9800 tokens
• Output por contrato: 2000 tokens (JSON estructurado)
• Total por contrato: 11,800 tokens (redondeado a 12,000 tokens)
• Volumen mensual: 20 clientes 5 contratos/cliente 12,000 tokens/contrato = 1,200,000 tokens/mes (~1.2M tokens/mes)

2. Desglose de Costos Mensuales

• Costos de LLM (OpenAI gpt-4o):

- Input (0.98M tokens): $0.98 * $5.00/1M tokens = $4.90 - Output (0.2M tokens): $0.20 * $15.00/1M tokens = $3.00 - Total LLM: ~$7.90 (redondeado a $10)

• Costos de Infraestructura Cloud (AWS):

- EC2 (t3.small, Linux): ~$18/mes - RDS (PostgreSQL, db.t4g.micro, 20GB): ~$18/mes - S3 (500MB storage, PUT/GET requests): ~$1/mes - Otros (Data transfer, CloudWatch, EBS): ~$3/mes - Total Cloud: ~$40/mes

• Costo Total Mensual Estimado: $10 (LLM) + $40 (Cloud) = $50/mes

3. Estimación de Ingresos Mensuales

Basado en un modelo B2B SaaS con tiers de pago para PYMES y consultores, asumiendo una tarifa promedio de $30/mes por cliente (por ejemplo, un plan intermedio que permite hasta 5-10 documentos).

• Clientes de pago inicial: 20
• Ingreso mensual promedio por cliente: $30
• Ingreso Mensual Estimado: 20 clientes * $30/cliente = $600/mes

4. Margen de Beneficio

• Ingresos: $600
• Costos: $50
• Beneficio: $600 - $50 = $550
• Margen de Beneficio: (($550 / $600) * 100) = 91.67% (redondeado a 90%)

5. Optimizaciones FinOps Concretas

El margen de beneficio inicial es excepcionalmente alto, lo que es una señal positiva para una micro-startup con bajos gastos operativos. Para mantener y mejorar esta eficiencia a medida que la startup crezca, se recomiendan las siguientes optimizaciones FinOps:

1. Optimización Continua del Prompt Engineering: La calidad y concisión de los prompts impactan directamente el costo de los tokens de entrada. Establecer un proceso para refinar y auditar los prompts garantizará la máxima eficiencia.
2. Estrategia de Caché Inteligente: Implementar un sistema de caché a nivel de cláusula o documento. Para documentos estándar (ej. NDAs), un análisis previo podría guardarse y reutilizarse, reduciendo drásticamente las llamadas al LLM.
3. Tiering de Modelos LLM: Investigar si modelos más económicos (como %%INLINE45%% o incluso modelos de código abierto auto-hospedados para tareas específicas como extracción de entidades) pueden ser utilizados para tipos de documentos o análisis de menor criticidad, reservando %%INLINE46%% para los casos más complejos.
4. Procesamiento Asíncrono y por Lotes: Utilizar la naturaleza asíncrona de las llamadas al LLM para procesar tareas en segundo plano. Para cargas de trabajo no urgentes, agrupar las solicitudes en lotes puede optimizar el uso de los recursos computacionales y de LLM.
5. Migración a Arquitectura Serverless: A medida que la carga de trabajo fluctúe, migrar la lógica de análisis a servicios serverless como AWS Lambda o Google Cloud Functions. Esto permite pagar solo por el tiempo de cómputo real utilizado, en lugar de mantener una instancia EC2 activa 24/7.
6. Políticas de Ciclo de Vida de Almacenamiento: Configurar políticas de ciclo de vida en AWS S3 para mover documentos más antiguos o menos accedidos a clases de almacenamiento más baratas (ej. S3 Infrequent Access o Glacier) después de un período definido, reduciendo los costos de almacenamiento.
7. Monitoreo y Alertas de Costos: Implementar herramientas de monitoreo de costos (ej. AWS Cost Explorer, GCP Billing Reports) con alertas para detectar y prevenir gastos inesperados, especialmente en el consumo de LLM y transferencia de datos.
8. Instancias Reservadas/Savings Plans: Una vez que la demanda y el uso de la infraestructura se estabilicen, considerar la compra de Instancias Reservadas (RIs) o la suscripción a Savings Plans para EC2 y RDS para obtener descuentos significativos a largo plazo.