Arquitectura y flujo¶

Los dos componentes¶

Además hay una librería de firma digital (PDF/PAdES) que esta app consume — la entrega otro equipo, se usa como una dependencia de Maven, y no se modifica. Firma en 3 fases internas (una fase de preparación, una de firma del hash, y una de inserción de la firma en el documento).

Por qué esta app no se comunica por red con el servicio de documentos¶

Es una decisión de arquitectura deliberada, mantenida en todo el proyecto: esta app y el servicio de documentos nunca se llaman entre sí — ninguno expone un endpoint que el otro consuma, ninguno conoce la dirección del otro. Se coordinan solo por dos medios compartidos:

1. Una base de datos SQLite compartida (ssigner.db, journal_mode=WAL) — cada uno lee y escribe un subconjunto de tablas (ver Modelo de datos).
2. Carpetas de archivos compartidas — cada proceso tiene su propia carpeta de entrada (ruta_entrada) y de salida (ruta_salida).

La ventaja práctica: si esta app se cae, se reinicia, o se está reinstalando una versión nueva, el servicio de documentos sigue funcionando — los documentos simplemente se acumulan EN_PROCESO en la carpeta de entrada hasta que esta app vuelve a estar corriendo. No hay una llamada HTTP que falle en cascada.

El flujo completo de un documento¶

Esta es la continuación de lo que ya vimos en el índice — acá con el detalle de qué hace exactamente esta app en el medio:

sequenceDiagram
    participant FS as Envío de Documentos y Mantenimiento
    participant DB as ssigner.db (compartida)
    participant SS as Esta app (SSigner Server)
    participant M as Librería de firma

    Note over FS: (recibió el documento, ver su propia documentación)
    FS->>FS: escribe el PDF en ruta_entrada del proceso

    SS->>SS: detecta el archivo nuevo por notificación del sistema operativo (evento nativo, no polling)
    SS->>DB: SELECT configuración del proceso (certificado, apariencia, posición de firma)
    SS->>M: fase 1 — preparación (firma en blanco)
    SS->>M: fase 2 — firma del hash con el certificado
    SS->>M: fase 3 — inserción de la firma en el documento
    M-->>SS: PDF firmado
    SS->>SS: escribe _.pdf en ruta_salida
    SS->>SS: limpia los archivos intermedios de ruta_entrada

    Note over FS: detecta el archivo por polling periódico, actualiza el estado y lo entrega

Nota el detalle de detección: esta app usa eventos reales del sistema de archivos (el sistema operativo le avisa apenas aparece un archivo, con una vigilancia activa por cada proceso, filtrando solo archivos .pdf para no reprocesar los artefactos intermedios que el propio proceso de firma genera) — no revisa la carpeta cada cierto tiempo, se entera al instante. El servicio de documentos, del otro lado, sí usa polling periódico para detectar cuándo aparece el archivo firmado — es una asimetría intencional: esta app sabe exactamente qué carpetas vigilar apenas arranca un proceso, mientras que el servicio de documentos tiene que revisar contra el estado de su base de datos para saber qué carpetas mirar.

Qué pasa si esta app no está corriendo¶

El servicio de documentos no tiene forma de saber directamente si esta app está activa — no hay ninguna llamada de red entre los dos. La forma en que se detecta un problema es indirecta: si un documento lleva más de 15 minutos (configurable, del lado del servicio de documentos) sin aparecer firmado en la carpeta de salida, se marca como error automáticamente. Ese timeout es, en la práctica, el mecanismo de detección de "esta app no está corriendo".

Por eso es importante que esta app esté siempre activa — ver Retención y operación para el detalle de cómo se evita que se cierre por accidente.

Multi-tenant: certificados y procesos por cliente¶

El servicio de documentos administra varias organizaciones ("clientes") sobre la misma base de datos. Esta app participa de eso de forma limitada: cuando soporte configura o edita un proceso, puede asociarlo a un cliente ya creado (por el ADMIN, desde el servicio de documentos) usando un combo de solo lectura — esta app nunca crea ni edita clientes, solo los lee para poder etiquetar procesos.

Quien configura el proceso en sí (rutas, certificado, apariencia de la firma) sigue siendo soporte técnico, manualmente, desde esta app — eso no cambia sin importar cuántos clientes existan.