Componentes

Documentación detallada de los componentes de Duckling.

Arquitectura del frontend

Pila tecnológica

• React 18 – Framework de UI con componentes funcionales y hooks
• TypeScript – JavaScript con tipos
• Tailwind CSS – Framework CSS utility-first
• Framer Motion – Biblioteca de animaciones
• React Query – Gestión del estado del servidor
• Axios – Cliente HTTP
• Vite – Herramienta de compilación y servidor de desarrollo

Estructura de componentes

graph TD
    App[App.tsx]

    App --> Header[Cabecera]
    App --> Main[Área principal]
    App --> Panels[Paneles]

    Main --> DropZone[Zona de soltar]
    Main --> Progress[Progreso]
    Main --> Export[Exportar]

    Panels --> Settings[Ajustes]
    Panels --> History[Historial]
    Panels --> Docs[Documentación]

    style App fill:#3b82f6,color:#fff
    style Main fill:#14b8a6,color:#fff
    style Panels fill:#8b5cf6,color:#fff

Archivos de componentes

Gestión de estado

La aplicación combina:

1. Estado local – Estado a nivel de componente con useState
2. React Query – Caché y sincronización del estado del servidor
3. Hooks personalizados – Lógica de negocio encapsulada

Hooks clave

useConversion

Gestiona el flujo de conversión de documentos:

• Subida de archivos (individual y por lotes)
• Sondeo de estado
• Obtención de resultados
• Manejo de descargas

useSettings

Gestiona los ajustes de la aplicación:

• Ajustes OCR, tablas, imágenes, rendimiento y fragmentación
• Persistencia de ajustes vía API
• Validación de ajustes

Arquitectura del backend

Pila tecnológica

• Flask – Framework web
• SQLAlchemy – ORM para operaciones de base de datos
• SQLite – Base de datos embebida para el historial
• Docling – Motor de conversión de documentos
• Threading – Procesamiento asíncrono de trabajos

Estructura de módulos

Servicios

ConverterService

Gestiona la conversión de documentos con Docling:

class ConverterService:
    def convert(self, file_path: str, settings: dict) -> ConversionResult:
        """Convertir un documento con los ajustes indicados."""
        pass

    def get_status(self, job_id: str) -> JobStatus:
        """Obtener el estado de un trabajo de conversión."""
        pass

FileManager

Gestiona subidas y salidas:

class FileManager:
    def save_upload(self, file) -> str:
        """Guardar el archivo subido y devolver la ruta."""
        pass

    def get_output_path(self, job_id: str) -> str:
        """Obtener el directorio de salida de un trabajo."""
        pass

HistoryService

Operaciones CRUD del historial de conversiones:

class HistoryService:
    def create(self, job_id: str, filename: str) -> Conversion:
        """Crear una nueva entrada de historial."""
        pass

    def update(self, job_id: str, **kwargs) -> Conversion:
        """Actualizar una entrada existente."""
        pass

    def get_stats(self) -> dict:
        """Obtener estadísticas de conversión."""
        pass

Integración OCR

Docling admite varios backends OCR:

graph LR
    Input[Documento] --> OCR{Backend OCR}

    OCR --> Easy[EasyOCR]
    OCR --> Tess[Tesseract]
    OCR --> Mac[OcrMac]
    OCR --> Rapid[RapidOCR]

    Easy --> Out[Salida de texto]
    Tess --> Out
    Mac --> Out
    Rapid --> Out

    style Easy fill:#22c55e,color:#fff
    style Tess fill:#3b82f6,color:#fff
    style Mac fill:#8b5cf6,color:#fff
    style Rapid fill:#f59e0b,color:#fff

El backend recurre automáticamente al procesamiento sin OCR si falla la inicialización OCR.

Procesamiento por lotes

sequenceDiagram
    participant U as Usuario
    participant F as Frontend
    participant Q as Cola
    participant W as Workers

    U->>F: Subir 5 archivos
    F->>Q: Encolar 5 trabajos

    par Procesar 2 a la vez
        Q->>W: Job 1
        Q->>W: Job 2
    end

    W-->>Q: Job 1 listo
    Q->>W: Job 3
    W-->>Q: Job 2 listo
    Q->>W: Job 4

    Note over Q,W: Máx. 2 concurrentes

    F->>F: Mostrar progreso por archivo