Cliente: Centrica Soluciones
Proyecto: Nebula ERP - Componente DataVault
Version: 1.0
Fecha: 16 de marzo, 2026
Autor: Carlos Torres (Arquitecto de Software)
Estado: VIGENTE
DataVault es el componente de preservacion digital del ecosistema Nebula ERP. Implementa el estandar OAIS (Open Archival Information System - ISO 14721) para la gestion, ingesta, preservacion y distribucion de documentos digitales.
DataVault opera como un componente autonomo de caja negra que se comunica con el ecosistema Nebula via API REST y base de datos compartida. No depende del stack Java/Spring de Simappe; utiliza su propio stack Python/FastAPI.
Nebula ERP (Java/Spring)
|
+-- API REST (JSON/HTTPS) --> DataVault Web (FastAPI/Next.js)
| |
| +-- Servidor OAIS (Python/Linux)
| | |
| | +-- Watcher (Daemon)
| | +-- Ingest Service
| | +-- Preservation Service
| | +-- Cloud Sync Daemons
| |
| +-- PostgreSQL (datavault)
| +-- Azure Blob Storage
|
+-- Modulos ERP (Contabilidad, Nomina, etc.)
La decision de mantener DataVault como componente independiente (stack dual Python/Java) responde a:
Nota critica: Esta arquitectura introduce complejidad de stack dual que debe gestionarse activamente. Ver seccion de analisis critico.
El sistema implementa las tres entidades fundamentales del modelo de referencia OAIS:
Paquete de entrada que contiene los archivos originales enviados al sistema.
Estructura implementada en disco:
{PROJECT}/SIP/{unique_id}/
data/ # Archivos originales (copiados)
archivo1.pdf
archivo2.xlsx
metadata/
descriptive_metadata.json # Dublin Core (titulo, autor, fecha)
technical_metadata.json # Hashes MD5/SHA-256, tamanos, tipos MIME
preservation_metadata.json # Politica de retencion, checksums, legal hold
{project}_{id}_meta.json # Metadata consolidada del proyecto
manifest.xml # Manifiesto METS
Proceso de generacion (IngestService.process):
ingest_sip/{nombre}_{timestamp}_{hash_corto}data/manifest.xml con estructura METSPaquete de preservacion a largo plazo. Es un archivo ZIP que contiene el SIP completo.
{PROJECT}/AIP/{unique_id}.zip
{unique_id}/
data/
metadata/
manifest.xml
Caracteristicas:
IntegrityCheckerPaquete de distribucion para consulta. Copia del AIP generada bajo demanda o automaticamente.
{PROJECT}/DIP/{unique_id}.zip
Caracteristicas:
| Capa | Tecnologia | Version | Proposito |
|---|---|---|---|
| Backend API | FastAPI | Python 3.10+ | REST API, procesamiento asincrono |
| Frontend | Next.js | 14 | Interfaz de usuario |
| ORM | SQLAlchemy | 2.x | Abstraccion de base de datos |
| Base de Datos | PostgreSQL | 16+ | Almacenamiento transaccional |
| Base de Datos (Dev) | SQLite | 3.x | Desarrollo y testing local |
| Almacenamiento | Filesystem (ext4) | - | Paquetes SIP, AIP, DIP en disco |
| Cloud Storage | Azure Blob Storage | - | Backup y distribucion cloud |
| Transferencia | SFTP (Paramiko) | - | Upload a servidor staging |
| Integracion | Archivematica API | - | Sistema OAIS externo (opcional) |
| Notificaciones | SMTP (Gmail/O365) | - | Alertas de consultas |
| SO | Ubuntu Server | 22.04+ | Host del servidor OAIS |
Las dependencias del proyecto incluyen:
sqlalchemy + psycopg2: Acceso a PostgreSQLparamiko: Cliente SFTPazure-storage-blob: Cliente Azuretqdm: Barra de progreso en uploadspython-dotenv: Configuracion via .envhashlib (stdlib): Checksums MD5/SHA-256zipfile (stdlib): Generacion de paquetes AIP/DIPxml.etree (stdlib): Generacion de manifiestos METSIngestService verifica existencia en filesystem y base de datos antes de procesar, evitando SIPs duplicados.IntegrityChecker soporta multiples metodos de almacenamiento de checksums (.checksum.json, manifest.txt, metadata.json).| Area | Hallazgo | Severidad | Impacto |
|---|---|---|---|
| Seguridad | Credenciales en .env en texto plano (SFTP_PASSWORD=12345, DB password=12345) |
CRITICA | Acceso no autorizado en produccion |
| Base de Datos | SQLite como fallback de desarrollo pero PostgreSQL hardcodeado en algunos servicios | MEDIA | Inconsistencia de ambientes |
| Concurrencia | Watcher usa polling secuencial (cada 5s) en lugar de inotify | MEDIA | Latencia en deteccion de nuevos SIPs |
| Error Handling | Excepciones genericas (except Exception) en multiples servicios |
MEDIA | Diagnostico dificil en produccion |
| Testing | No se identifican tests unitarios ni de integracion en el proyecto | CRITICA | Mantenibilidad comprometida |
| Documentacion API | No hay especificacion OpenAPI/Swagger para los endpoints REST | ALTA | Integracion con Nebula dificultada |
| Observabilidad | Logging a archivo plano sin formato estructurado | MEDIA | Monitoring limitado |
| Multi-tenancy | No implementa aislamiento de datos por tenant | ALTA | Incompatible con modelo Nebula |
__pycache__ en el repositorio: Indica que .gitignore no esta correctamente configurado.datavault.db) en el repositorio: Datos de desarrollo committed al VCS.check_project.py, check_oais_status.py, test_imports.py) sin estructura de CLI.| # | Recomendacion | Justificacion |
|---|---|---|
| 1 | Implementar vault de secretos (HashiCorp Vault o Azure Key Vault) | Eliminar credenciales en texto plano del .env |
| 2 | Agregar suite de tests (pytest + fixtures) | Cobertura minima 80% para IngestService y IntegrityChecker |
| 3 | Generar especificacion OpenAPI automaticamente desde FastAPI | FastAPI lo soporta nativamente, es cuestion de exponerlo |
| 4 | Implementar multi-tenancy en el modelo de datos | Requerido para integracion con Nebula (ADR-001 de Nebula) |
| 5 | Migrar watcher a watchdog/inotify | Eliminar polling innecesario, mejorar rendimiento |
| # | Recomendacion | Justificacion |
|---|---|---|
| 6 | Estructurar logging con JSON (structlog o python-json-logger) | Compatibilidad con ELK Stack de Nebula |
| 7 | Unificar modelos a SQLAlchemy (SIP, AIP, DIP como ORM) | Consistencia de modelado y trazabilidad en BD |
| 8 | Implementar health checks (/health endpoint) | Integracion con monitoring Prometheus/Grafana |
| 9 | Agregar rate limiting al API | Prevenir abuso en endpoints de upload |
| 10 | Crear CLI unificado (Click/Typer) para scripts utilitarios | Reemplazar scripts sueltos por comandos estructurados |
DataVault opera como caja negra con contratos API:
Nebula ERP DataVault
| |
|-- POST /api/ingest -------------> | (Iniciar ingesta)
|-- GET /api/oais/status --------> | (Estado del sistema)
|-- POST /api/consulta -----------> | (Solicitar acceso DIP)
|-- GET /api/projects -----------> | (Listar proyectos)
|<- Webhook (estado cambio) -------| (Notificacion asincrona)
A mediano plazo, evaluar:
tenantId de Nebula en cada operacion.Evaluar la migracion parcial del backend a microservicio Java/Spring dentro del ecosistema Simappe, manteniendo los daemons de procesamiento en Python como workers.
Departamento de Arquitectura — Centrica Soluciones
Clasificacion: Uso Interno — Equipo Tecnico