Doc Validator

La IA no viene a quitarte el trabajo: viene a quitarte el papeleo.

Doc Validator AI es una aplicación de validación documental asistida por inteligencia artificial. El proyecto nace de una idea sencilla: muchas tareas administrativas no son complejas por sí mismas, pero se vuelven costosas cuando hay que repetirlas una y otra vez sobre decenas, cientos o miles de expedientes.

La solución aplica document intelligence, IA generativa, procesamiento asíncrono y arquitectura cloud sobre AWS para convertir documentos dispersos en información estructurada, trazable y útil para la revisión profesional.

No se plantea como un chatbot, sino como una solución de negocio orientada a reducir trabajo manual repetitivo en procesos de validación documental.

---

El problema

En muchos procesos administrativos, una parte importante del trabajo consiste en comprobar que todo está en orden:

• Revisar documentos recibidos.
• Comprobar que no falta información.
• Localizar datos relevantes.
• Detectar incoherencias.
• Validar si un expediente puede avanzar.
• Mantener trazabilidad del estado de revisión.

Visto de forma aislada, cada revisión puede parecer sencilla. El problema aparece cuando ese proceso se repite expediente tras expediente.

Ahí aparece la fricción operativa:

• Pérdida de tiempo administrativo.
• Documentos faltantes detectados tarde.
• Errores que pueden pasar desapercibidos.
• Revisiones duplicadas.
• Baja trazabilidad.
• Dificultad para conocer el estado real de cada expediente.

La IA no elimina la revisión. La ordena.

---

Qué aporta la IA

El objetivo del proyecto no es que la IA tome la decisión final, sino que prepare el terreno para que una persona pueda revisar mejor.

En lugar de enfrentarse a una carpeta desordenada de documentos, el profesional puede trabajar sobre una primera lectura estructurada:

• Qué documentos se han recibido.
• Qué información se ha extraído.
• Qué posibles incoherencias existen.
• Qué advertencias se han generado.
• Qué expediente requiere atención prioritaria.

La IA actúa como una capa de asistencia, no como una fuente infalible de verdad.

---

Idea principal

Doc Validator convierte este flujo:

documentos dispersos
        ↓
revisión manual repetitiva
        ↓
detección tardía de errores
        ↓
decisión con poca trazabilidad

en este otro:

documentos recibidos
        ↓
extracción documental
        ↓
interpretación con IA generativa
        ↓
resultados estructurados
        ↓
revisión profesional

La clave está en separar dos responsabilidades:

Textract convierte el documento en contenido.
Bedrock convierte el contenido en contexto.

---

Caso de uso inicial

El primer caso de uso se centra en la validación documental de expedientes, como podría ocurrir en procesos administrativos, inmobiliarios, financieros o internos de una organización.

Un usuario puede:

1. Crear un expediente.
2. Subir documentos asociados.
3. Consultar el estado del procesamiento.
4. Revisar resultados, advertencias e incidencias.
5. Tomar una decisión final con más contexto.

El sistema procesa documentos como PDFs, imágenes, formularios o documentación semiestructurada.

---

Arquitectura funcional

Desde un punto de vista funcional, la solución se organiza como una cadena de responsabilidades:

Interfaz de usuario
        ↓
Backend / orquestación
        ↓
Almacenamiento seguro
        ↓
Procesamiento asíncrono
        ↓
Extracción documental
        ↓
IA generativa
        ↓
Datos y resultados
        ↓
Revisión profesional

Cada pieza cumple una función concreta:

Capa	Responsabilidad
Interfaz de usuario	Crear expedientes, subir documentos y consultar resultados
Backend	Validar peticiones, registrar documentos y orquestar el flujo
Almacenamiento	Conservar documentos originales
Mensajería	Desacoplar la subida del procesamiento
Procesamiento	Ejecutar el análisis documental en segundo plano
Extracción documental	Obtener texto y estructura del documento
IA generativa	Clasificar, normalizar y generar advertencias
Persistencia	Guardar estados, resultados e incidencias
Revisión profesional	Validar resultados y tomar la decisión final

---

Arquitectura cloud en AWS

La arquitectura cloud permite llevar el flujo funcional a un entorno real: seguro, escalable y mantenible.

La solución utiliza:

• React + Nginx para el frontend.
• FastAPI para el backend.
• Amazon EKS para ejecutar frontend y backend en Kubernetes gestionado.
• Application Load Balancer e Ingress para exponer la aplicación.
• Amazon S3 para almacenar documentos originales.
• Amazon RDS PostgreSQL para guardar expedientes, documentos, jobs y resultados.
• Amazon SQS para desacoplar la subida del procesamiento.
• AWS Lambda como worker asíncrono de documentos.
• Amazon Textract para OCR y extracción documental.
• Amazon Bedrock para clasificación, normalización y extracción semántica.
• Amazon ECR para almacenar imágenes Docker.
• Terraform para aprovisionar infraestructura.
• IRSA para evitar credenciales AWS estáticas dentro de EKS.
• CloudWatch para logs y trazabilidad.

---

Flujo de procesamiento

Cuando un usuario sube un documento, el backend no intenta procesarlo todo en la misma petición.

El flujo es:

1. El frontend envía el documento al backend.
2. El backend guarda el documento original en S3.
3. El backend registra el documento en PostgreSQL.
4. El backend crea un job de procesamiento.
5. El backend publica un evento en SQS.
6. Lambda consume el evento.
7. Lambda recupera el documento desde S3.
8. Lambda usa Textract para extraer texto y estructura.
9. Lambda usa Bedrock para interpretar y normalizar el contenido.
10. Lambda guarda resultados, advertencias e incidencias en PostgreSQL.
11. El frontend consulta el estado y muestra los resultados al usuario.

Frontend
   ↓
Backend FastAPI
   ↓
S3 + RDS + SQS
   ↓
Lambda
   ↓
Textract
   ↓
Bedrock
   ↓
RDS
   ↓
Frontend

Este diseño permite que el procesamiento sea:

• Asíncrono.
• Trazable.
• Escalable.
• Tolerante a errores.
• Más cómodo para el usuario.

---

Por qué SQS y Lambda

El procesamiento documental puede tardar varios segundos o más, dependiendo del tamaño y tipo de documento.

Por eso, el backend no bloquea la petición del usuario. Solo registra el trabajo y lo delega.

Backend → SQS → Lambda → Textract / Bedrock → RDS

SQS permite desacoplar la experiencia de usuario del trabajo pesado.

Lambda permite ejecutar el procesamiento bajo demanda.

---

Qué hacen Textract y Bedrock

Amazon Textract

Textract se encarga de la extracción documental.

Su papel es obtener texto y estructura a partir de documentos que pueden venir en distintos formatos:

• PDFs.
• Imágenes.
• Formularios.
• Documentos escaneados.
• Documentos semiestructurados.

Textract responde a una pregunta técnica:

¿Qué texto y estructura hay en este documento?

Amazon Bedrock

Bedrock actúa como capa de inteligencia generativa.

A partir del contenido extraído, ayuda a:

• Clasificar el tipo de documento.
• Extraer campos relevantes.
• Normalizar información.
• Detectar posibles incoherencias.
• Generar advertencias revisables.

Bedrock responde a preguntas más cercanas al proceso de negocio:

¿Qué tipo de documento es?
¿Qué datos relevantes contiene?
¿Falta algo?
¿Hay alguna incoherencia?
¿Qué debería revisar una persona?

La IA no decide por el profesional.

Prepara el expediente para que pueda revisarlo mejor.

---

Seguridad e IRSA

El backend necesita permisos para operar con servicios AWS como S3 y SQS.

En lugar de usar credenciales estáticas, el proyecto utiliza IRSA.

IRSA permite asociar un ServiceAccount de Kubernetes con un rol IAM de AWS.

Pod backend
    ↓
ServiceAccount backend
    ↓
IAM Role asociado
    ↓
Permisos S3 + SQS

Esto permite que el backend obtenga credenciales temporales gestionadas por AWS.

Ventajas:

• No hay claves AWS estáticas en Kubernetes.
• Los permisos están limitados al backend.
• Se aplica el principio de mínimo privilegio.
• Las credenciales son temporales.

---

Modelo de datos

El modelo de datos se centra en expedientes, documentos y procesamiento.

Entidades principales:

Entidad	Descripción
expedients	Expediente documental
documents	Documento subido al expediente
processing_jobs	Trabajo de procesamiento asociado a un documento
document_extractions	Resultado bruto de Textract
document_normalizations	Resultado normalizado por Bedrock
validation_issues	Incidencias detectadas
validation_checks	Checks de validación

---

Estructura del repositorio

doc_validator/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── core/
│   │   ├── db/
│   │   ├── lambdas/
│   │   ├── models/
│   │   ├── schemas/
│   │   ├── services/
│   │   └── main.py
│   ├── Dockerfile
│   ├── Dockerfile.lambda
│   └── requirements.txt
│
├── frontend/
│   ├── public/
│   ├── src/
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── package.json
│   └── vite.config.ts
│
├── infra/
│   ├── k8s-eks/
│   └── terraform/
│       └── aws/
│
├── Makefile
├── README.md
└── .gitignore

---

Tecnologías utilizadas

Backend

• Python
• FastAPI
• SQLAlchemy
• Pydantic
• PostgreSQL
• boto3
• Uvicorn

Frontend

• React
• TypeScript
• Vite
• Nginx

IA y procesamiento documental

• Amazon Textract
• Amazon Bedrock
• AWS Lambda
• Amazon SQS

Infraestructura

• Amazon EKS
• Amazon ECR
• Amazon RDS PostgreSQL
• Amazon S3
• Application Load Balancer
• AWS Load Balancer Controller
• Terraform
• Kubernetes
• Makefile

Seguridad y operación

• IAM
• IRSA
• OIDC provider de EKS
• Security Groups
• VPC Endpoints
• CloudWatch

---

Backend

El backend expone la API principal del sistema.

Responsabilidades:

• Crear expedientes.
• Recibir documentos.
• Subir documentos a S3.
• Registrar documentos en PostgreSQL.
• Crear jobs de procesamiento.
• Publicar eventos en SQS.
• Consultar resultados de extracción, normalización y validación.

Capas principales:

Capa	Responsabilidad
api	Rutas y endpoints
schemas	Validación y serialización
models	Modelos ORM
services	Lógica de negocio e integración con AWS
db	Conexión y sesiones de base de datos
core	Configuración centralizada
lambdas	Handlers serverless

---

Frontend

El frontend está desarrollado con React y TypeScript.

En cloud se compila y se sirve con Nginx dentro de EKS.

El acceso externo se produce mediante ALB e Ingress:

Ruta	Servicio
/	Frontend React
/api	Backend FastAPI

Esto permite que el frontend use rutas relativas hacia la API:

/api

---

Endpoints principales

Health check

GET /api/health

Crear expediente

POST /api/expedients

Ejemplo:

{
  "candidate_name": "Juan Pérez"
}

Listar expedientes

GET /api/expedients

Consultar expediente

GET /api/expedients/{expedient_id}

Subir documento

POST /api/expedients/{expedient_id}/documents

Listar documentos de un expediente

GET /api/expedients/{expedient_id}/documents

Consultar extracción

GET /api/documents/{document_id}/extraction

Consultar normalización

GET /api/documents/{document_id}/normalized

Resumen de validación

GET /api/expedients/{expedient_id}/validation-summary

Revalidar expediente

POST /api/expedients/{expedient_id}/revalidate

---

Infraestructura con Terraform

Terraform gestiona la infraestructura principal en AWS:

• Bucket S3 para documentos.
• Cola SQS y DLQ.
• RDS PostgreSQL.
• Repositorios ECR.
• Función Lambda.
• Clúster EKS.
• Node group de EKS.
• IAM roles y policies.
• OIDC provider para IRSA.
• AWS Load Balancer Controller.
• VPC Endpoints.
• Security Groups.

Outputs útiles

terraform -chdir=infra/terraform/aws output

Outputs concretos:

terraform -chdir=infra/terraform/aws output -raw backend_ecr_repository_url
terraform -chdir=infra/terraform/aws output -raw frontend_ecr_repository_url
terraform -chdir=infra/terraform/aws output -raw document_processor_lambda_name
terraform -chdir=infra/terraform/aws output -raw eks_cluster_name
terraform -chdir=infra/terraform/aws output -raw backend_iam_role_arn

---

Despliegue en AWS

El flujo principal se ejecuta con:

make up

Este comando encadena:

tf-init
    ↓
deploy-lambda
    ↓
deploy-eks
    ↓
show-outputs

Para eliminar el entorno:

make down

---

Makefile

El Makefile centraliza operaciones habituales.

Comandos útiles:

make tf-plan
make tf-apply
make tf-destroy
make outputs

make deploy-backend
make deploy-frontend
make deploy-eks-images

make eks-status
make eks-ingress
make eks-alb-url

make logs-backend
make logs-frontend
make logs-lambda

---

Configuración

El proyecto separa configuración no sensible, secretos y valores generados dinámicamente.

.env.local

Contiene configuración no sensible:

APP_ENV=cloud
EVENT_SOURCE=doc-validator-backend
AWS_REGION=eu-west-1
BEDROCK_MODEL_ID=eu.amazon.nova-lite-v1:0
BEDROCK_TEMPERATURE=0
BEDROCK_MAX_TOKENS=1200
SQS_WAIT_TIME_SECONDS=10
SQS_MAX_NUMBER_OF_MESSAGES=1
SQS_VISIBILITY_TIMEOUT_SECONDS=300

.env.secret

No contiene credenciales AWS para el backend en EKS.

El backend obtiene permisos mediante IRSA.

Actualmente contiene principalmente:

DATABASE_URL

Ficheros no versionados

Fichero	Motivo
.env.local	Configuración específica del entorno
.env.secret	Secretos locales si fueran necesarios
infra/terraform/aws/terraform.tfvars	Variables reales de Terraform
infra/terraform/aws/terraform.tfstate	Estado de Terraform
infra/terraform/aws/.terraform/	Providers y metadatos locales

---

Operaciones útiles

Ver pods:

kubectl get pods -n doc-validator

Ver servicios:

kubectl get svc -n doc-validator

Ver Ingress / ALB:

make eks-ingress
make eks-alb-url

Ver logs:

make logs-backend
make logs-frontend
make logs-lambda

Comprobar ServiceAccount del backend:

kubectl describe serviceaccount backend -n doc-validator

Comprobar que el pod usa IRSA:

kubectl exec -n doc-validator deployment/backend -- env | grep AWS

---

Conclusión

Doc Validator muestra una forma práctica de aplicar inteligencia artificial generativa a un proceso real.

La IA no sustituye al profesional.

Le evita empezar desde cero.

La arquitectura cloud sostiene el flujo. Textract extrae el contenido. Bedrock interpreta la información. Y la persona mantiene el control final sobre la revisión y la decisión.

El objetivo no es automatizar por automatizar, sino reducir ruido, ordenar información dispersa y permitir que los profesionales dediquen más tiempo a lo que realmente requiere criterio.