docu-ai-flow

El problema

Gestionar facturas de proveedores es trabajo manual repetitivo: descargar PDFs, abrirlos uno a uno, copiar datos a una hoja de cálculo, enviarlos al asesor cada trimestre. Un error en cualquier paso significa declaraciones incorrectas. Necesitaba un sistema que hiciera ese trabajo solo, sin intervención manual, y que sirviera como campo de pruebas real para un workflow de desarrollo asistido por IA.

La solución

• Watcher de carpeta

  Detecta PDFs en ./data/inbox/ en tiempo real. Un watcher de filesystem más polling de seguridad garantizan que ninguna factura se pierda. Un gate de concurrencia evita procesar el mismo archivo dos veces.

• Extracción con IA

  Google Document AI (Invoice Parser) extrae proveedor, CIF, número, fecha, base imponible, IVA y total como campos tipados, detrás de un único port IInvoiceDataExtractor. El adaptador de LlamaParse se conserva como referencia. Un umbral de confianza configurable descarta extracciones dudosas y las mueve a ./data/failed/ automáticamente.

• Exportación a Excel

  ClosedXML genera un Excel trimestral con tipos nativos — fechas y números reales para ordenar, filtrar y sumar sin conversiones. El maestro acumulativo se regenera con cada nueva factura.

• Envío al asesor

  Resend empaqueta los PDFs del trimestre en un ZIP y los envía al asesor fiscal. Si el ZIP supera el límite de 40 MB de Resend, se divide automáticamente por mes y se envían varios correos.

Stack técnico

Decisiones técnicas

• Arquitectura hexagonal

  Google Document AI, SQLite, el archivador y Resend son adaptadores intercambiables detrás de interfaces (ports). Los use cases del Application no conocen ningún detalle de implementación. Un test de arquitectura con NetArchTest verifica que las fronteras nunca se crucen en cada build.

• Extracción intercambiable

  El extractor empezó siendo LlamaParse, pero su precisión se quedó corta. Cambiarlo a Google Document AI fue una sola línea en el composition root: el dominio, los use cases y los tests de pipeline no se tocaron, porque dependen del port IInvoiceDataExtractor, no del proveedor. LlamaParse permanece en el repo como prueba de resultado, con sus tests de contrato en verde.

• Result/Error para errores de negocio

  Un error de extracción (confianza baja, total incoherente, número ausente) es un caso de negocio esperado, no una excepción. Result<TValue, TError> lo expresa como un valor de retorno. Las excepciones quedan para lo transitorio — API caída, disco lleno — que Polly reintenta automáticamente.

• Desarrollado con agentes de Claude Code

  Cada feature siguió el mismo ciclo: el orquestador exploró y debatió el enfoque, el planner-backend diseñó la arquitectura, el coder-backend implementó en TDD y el reviewer auditó contra el plan aprobado. El resultado: código consistente y un historial de commits que cuenta la historia de cada decisión.

Construido con Claude Code

El proyecto es también un experimento sobre cómo organizar el desarrollo asistido por IA. Los agentes y skills están en .claude/ y forman parte del repo público.

• Orquestador

  Coordina el flujo completo: explora, debate, planifica, implementa y revisa. Ninguna fase comienza sin acuerdo explícito. El plan vive en workflow/ y viaja por plans/ → in-progress/ → reviewing/ → done/.

• Agentes especializados

  planner-backend diseña la arquitectura y los contratos; coder-backend implementa en TDD estricto; reviewer audita contra el plan aprobado. Cada agente tiene su propio system prompt en .claude/agents/.

• Skills reutilizables

  Skills en Markdown cargadas al inicio de cada sesión: commit.md define el formato de commits, tdd.md codifica el ciclo Red-Green-Refactor y orchestrate.md el flujo completo de orquestación.

• TDD asistido por IA

  Cada feature empieza con un test en rojo. El coder escribe el mínimo código para que pase, luego refactoriza. 111 tests en tres capas: Domain (puro), Application (use cases con dobles NSubstitute) e Integration (SQLite, Excel, zip, watcher, golden-master del mapper y pipeline end-to-end con un extractor fake).