Visión General de la Arquitectura
Arquitectura del sistema, stack tecnológico, patrones de flujo de datos y organización de módulos para la plataforma logística de grado producción de Certexi.
Última actualización: 2025-02-18
Visión General de la Arquitectura
Certexi es un sistema de seguimiento de flujos de trabajo aduanero de grado producción, habilitado con NFC, construido con Next.js 14, TypeScript y PostgreSQL. Proporciona visibilidad en tiempo real de operaciones aduaneras multi-etapa con verificación criptográfica y pistas de auditoría integrales.
Arquitectura del Sistema
Dashboard en Vivo
Métricas operacionales de un vistazo — unidades de transporte activas, utilización de almacén, rendimiento diario y conteo de incidentes. Todas las métricas se derivan del flujo de eventos.
Dashboard de KPI en vivo con métricas animadas, tendencias de utilización y rendimiento semanal.
Stack Tecnológico
| Capa | Tecnología | Versión |
|---|---|---|
| Runtime | Node.js | 20+ |
| Framework | Next.js | 14.1 |
| Lenguaje | TypeScript | 5.3 |
| Base de datos | PostgreSQL | 15+ |
| ORM | Drizzle | 0.29 |
| Auth | NextAuth.js | 4.24 |
| UI | React + Tailwind CSS + Radix UI | 18.2 |
| Estado | Zustand + React Query | — |
| Testing | Vitest + Playwright | — |
| Contenedor | Docker | 24+ |
| CI/CD | GitHub Actions | — |
Capas de la Aplicación
Capa Cliente
La capa cliente soporta múltiples plataformas a través de un único código base:
- Navegador Web — Experiencia de escritorio completa con React 18 y server components
- PWA Móvil — Aplicación web progresiva instalable con soporte offline y Web NFC
- Escáner NFC — Integración con Web NFC API para escaneo de tags (Android Chrome 89+)
- App de Escritorio — Wrapper Electron para Windows, macOS y Linux
Capa de Aplicación
Construida sobre Next.js 14 con App Router para renderizado híbrido:
- Server Components para cargas iniciales de página y SEO
- Rutas API para endpoints RESTful con validación Zod
- Middleware para autenticación, limitación de tasa y cabeceras de seguridad
- Service Worker para caché offline y sincronización en segundo plano
Capa de Lógica de Negocio
Los servicios centrales manejan todas las operaciones de negocio:
- Gestor de Flujo de Trabajo — Progresión de etapas, reglas de validación, transiciones de estado
- Servicio de Auth — Nextcloud OAuth, sesiones JWT, aplicación de RBAC
- Almacenamiento Offline — Cola de eventos en IndexedDB, resolución de conflictos, coordinación de sincronización
- Limitador de Tasa — Límites por usuario y por IP con ventanas configurables
Capa de Acceso a Datos
Drizzle ORM proporciona acceso tipo-seguro a la base de datos con 15 tablas, 25 índices y migraciones con control de versiones. Las tablas principales incluyen operators, transport_units, events y workflow_stage_history.
Flujo de Datos
Creación de Eventos
Acción del Usuario (Escaneo NFC / Envío de Formulario)
→ Validación en cliente
→ Solicitud API (POST /api/events)
→ Verificación de rate limit + Auth
→ Validación de lógica de negocio
→ Transacción de base de datos (evento + unidad de transporte + log de auditoría)
→ Integraciones externas (prueba Flowhash, credencial NFTC, evidencia Nextcloud)
→ Respuesta + Actualización de UI
Sincronización Offline
Acción del Usuario (offline)
→ Encolar en IndexedDB
→ Interceptar por Service Worker
→ Red restaurada → Sincronización en segundo plano
→ Procesar operaciones encoladas → Actualizar servidor
→ Confirmar sincronización → Eliminar de la cola
Integraciones Externas
| Servicio | Propósito | Protocolo |
|---|---|---|
| Flowhash Core | Pruebas criptográficas de eventos vía SHA-256 y árboles Merkle | REST API |
| NFTC-RWA | Emisión y verificación de credenciales de operadores | REST API |
| Nextcloud | Almacenamiento de archivos de evidencia vía WebDAV, autenticación OAuth | REST + WebDAV |
| Sentry | Rastreo de errores, monitoreo de rendimiento, gestión de releases | SDK |
Arquitectura de Seguridad
- Autenticación: Nextcloud OAuth2 con tokens de sesión JWT en cookies httpOnly
- Autorización: Control de acceso basado en roles (operator, supervisor, admin) — ver RBAC
- Datos en Tránsito: HTTPS/TLS 1.3 obligatorio
- Datos en Reposo: Cifrado de PostgreSQL, cifrado del lado del servidor S3
- Validación de Entrada: Esquemas Zod en todos los endpoints de API
- Seguridad de Archivos: Validación de tipo, límites de tamaño, escaneo de virus ClamAV
Organización de Módulos
certexi/
├── app/ # Next.js App Router
│ ├── (dashboard)/ # Rutas del dashboard
│ ├── scan/ # Escaneo NFC
│ ├── workflow/ # Flujos de trabajo por etapas
│ └── api/ # 100+ rutas API
├── components/ # Componentes React (112+ widgets)
├── lib/ # Lógica de negocio
│ ├── auth/ # RBAC, gestión de sesiones
│ ├── nfc/ # Wrapper de Web NFC API
│ ├── nextcloud/ # Cliente Nextcloud
│ ├── whms/ # Gestión de almacén
│ ├── iot/ # CCTV, detección de movimiento
│ └── offline/ # Almacenamiento offline PWA
└── specs/ # Especificaciones