Arquitectura e Integraciones

Libertum es un sistema distribuido: tres aplicaciones web de usuario final, un conjunto de servicios backend, una capa de smart contracts sobre Base Mainnet además de Cardano Mainnet y Preview, y un grupo de integraciones de terceros.

1. La arquitectura a alto nivel

┌─────────────────────────────────────────────────────────────────────┐
│                        CAPA DE USUARIO FINAL                        │
│  Investor / Issuer / AM    Admin Portal     Transfer Agent Portal   │
│              React 18 / TypeScript / Vite — Cloudflare Pages        │
└─────────────────────────┬─────────────────────────┬─────────────────┘
                         │ HTTPS / WSS             │
┌─────────────────────────▼─────────────────────────▼─────────────────┐
│                          CAPA DE SERVICIOS                          │
│       Marketplace · Admin · Transfer Agent · Notification           │
│       Event indexer · Dividend · Bonding/DEX · Cardano              │
│              Node.js / Express / TypeScript — gRPC + Kafka          │
└─────────────────────┬───────────────────────────────┬───────────────┘
                     │                               │
       ┌─────────────▼──────────┐         ┌──────────▼──────────────┐
       │     CAPA DE DATOS      │         │   CAPA DE INTEGRACIÓN   │
       │  MongoDB · Redis ·     │         │  SumSub · Stripe ·      │
       │  PostgreSQL · Kafka    │         │  DocuSign · SendGrid ·  │
       │                        │         │  Twilio · Transak ·     │
       │                        │         │  Bridge · Blockfrost    │
       └────────────────────────┘         └─────────────────────────┘
                                                   │
                               ┌───────────────────▼──────────────────┐
                               │          CAPA DE BLOCKCHAIN          │
                               │  Base Mainnet (8453) ERC-3643 stack  │
                               │  Cardano Mainnet — CIP-20 nativo     │
                               │  Cardano Preview — CIP-113 + CIP-20  │
                               └──────────────────────────────────────┘

2. Aplicaciones frontend

Tres aplicaciones de página única (SPA) en React 18, todas alojadas en Cloudflare Pages.

Marketplace

Interfaz de Investor + Issuer + Asset Management. Es la SPA más grande y con más funcionalidades — combina las tres experiencias principales de la plataforma y enruta según el rol del usuario.

Stack: React 18, TypeScript, Vite, Redux Toolkit + redux-persist, TanStack React Query, RainbowKit + wagmi + viem + ethers v6, Formik + Yup/Zod, React Bootstrap + SCSS, Recharts, Sentry.

Detección de modo: la aplicación inspecciona el hostname de la solicitud y alterna entre tres modos:

• Core — el marketplace propio de Libertum en libertum.io / app.libertum.io.
• Whitelabel de plataforma — marketplace completo en un dominio propio o en un subdominio no reservado.
• Shopfront — página de marca para una sola oferta.

Admin

Administración de la plataforma Libertum. Panel de control, gestión de usuarios, cola de revisión de KYC, aprobación de ofertas, RBAC de subadministradores, configuración de tarifas, historial de transacciones, gestión de agentes de transferencia, tesorería de gas y operaciones multicadena.

Transfer Agent

Cap table, aprobación de whitelist de wallets, registro de transferencias forzadas e historial de transacciones. Interacción directa e intensiva con los contratos a través de ethers.

3. Servicios backend

Un conjunto de servicios en Node.js / Express / TypeScript claramente separados. Cada uno es responsable de un dominio:

Servicio	Dominio
Marketplace	Usuarios, ofertas, órdenes, pagos, mediación de KYC, P2P, NFT, suscripciones, whitelabel, wallets de custodia
Admin	Operaciones administrativas, RBAC de subadministradores, configuración de tarifas, sincronización de planes/módulos, tesorería de gas
Transfer Agent	Consultas al cap table, transferencia forzada, congelar/descongelar, whitelist de wallets
Notification	Correo (SendGrid) + SMS (Twilio) + notificaciones push in-app por WebSocket
Event Indexer	Escucha eventos on-chain de Token Transfer, Mint, Burn, Pause, actualizaciones del Identity Registry, depósitos en Escrow, órdenes del Marketplace y compras/ventas de Bonding
Dividend	Snapshot y distribución de dividendos
Bonding / DEX	Operaciones de curva de bonding y recompensas de staking
Cardano (×2 instancias)	Operaciones CIP-20 + CIP-113 en Cardano. Una instancia por red (mainnet, preview).

4. Capa de datos

• MongoDB — almacén documental principal. Contiene usuarios, ofertas, órdenes, transferencias, dividendos, P2P, colecciones NFT, suscripciones, planes, módulos, registros de KYC, wallets de custodia y el log de auditoría.
• Redis — almacén de sesiones, bloqueos distribuidos y cachés.
• PostgreSQL — almacén de respaldo del indexador de Cardano.
• Kafka — bus de eventos asíncrono.

5. Modelo de autenticación e identidad

Basado en JWT con rotación de refresh tokens. La autenticación de dos factores (2FA) protege las operaciones sensibles.

Ciclo de vida del token:

1. El usuario inicia sesión (correo + contraseña); el marketplace valida las credenciales.
2. Se emite un OTP (por correo o SMS). El usuario lo envía dentro de un plazo de 5 minutos.
3. Si el 2FA está activado, se solicita un desafío TOTP / OTP por correo / OTP por SMS.
4. Se emite un JWT (vigencia de 1 hora). Se emite un refresh token (vigencia de 7 días).
5. El frontend almacena ambos y envía el JWT en cada solicitud.
6. Al expirar, el frontend usa el refresh token para obtener un JWT nuevo.
7. Tiempo de inactividad: 30 minutos (marketplace), 60 minutos (admin).

Roles:

• Investor — pantallas de inversionista del Marketplace
• Institution — pantallas de inversionista del Marketplace (variante de inversionista institucional)
• Issuer — pantallas de emisor del Marketplace (además de las de inversionista)
• Admin — acceso completo al Admin Portal
• SubAdmin — subconjunto del Admin Portal filtrado por permisos RBAC
• TransferAgent — Transfer Agent Portal

KYC frente a KYB. Ambos se ejecutan mediante SumSub. Estados: NOT_STARTED → IN_PROGRESS → PENDING → APPROVED / REJECTED / RESUBMIT. El KYC aplica a personas físicas; el KYB, a entidades.

6. Comunicación sincrónica: gRPC

Los servicios que necesitan respuestas sincrónicas entre sí utilizan gRPC. Algunos ejemplos:

• Marketplace ↔ Admin: getUser, approveKyc, approveWhitelist, approveIssuer, rejectOffering.
• Marketplace ↔ Notification: ListNotifications, MarkSeen, MarkAllSeen.
• Marketplace ↔ Bonding: GetStakingTransactions, GetUserStakingSummary.

7. Comunicación asincrónica: Kafka

Los eventos asíncronos fluyen a través de topics de Kafka. Productores y consumidores están débilmente acoplados.

Topic	Productor	Consumidor	Ejemplos
Cron-to-user	Event indexer, servicio de dividendos	Marketplace	OrderCreated, TokensMinted, DividendDistributed, NAVUpdated
Admin-to-user	Admin	Marketplace	KYC aprobado/rechazado, oferta aprobada/rechazada
Realtime notifications	Marketplace	Notification	Notificaciones in-app
Realtime email	Marketplace	Notification	Disparadores de envío de correo
Realtime socket	Marketplace	Notification	Eventos push por WebSocket

8. Tareas programadas

Tarea	Frecuencia	Servicio
Snapshot y envío de dividendos	Frecuente (menos de un minuto)	Marketplace / servicio de dividendos
Verificación de expiración de órdenes P2P	Cada 2 minutos (órdenes que superan su ventana de pago de 20 minutos)	Marketplace
Recompensas mensuales de staking	Mensual	Bonding / DEX

9. Integraciones de terceros

Servicio	Se usa para
SumSub	Verificación de identidad KYC + KYB
Stripe	Pagos con tarjeta + Connect para pagos a emisores + facturación de suscripciones
DocuSign	Firmas electrónicas en documentos legales
Transak	Rampa de entrada y salida de fiat
Bridge	Conversión entre stablecoin y fiat
SendGrid	Correo transaccional
Twilio	OTP por SMS
Azure Blob Storage	Carga de documentos e imágenes
Blockfrost	RPC e indexación de Cardano
Sentry	Seguimiento de errores
WalletConnect / Thirdweb	Experiencia de uso de wallets

10. Notificaciones y plantillas de correo

El correo se envía mediante SendGrid; los SMS mediante Twilio; las notificaciones in-app por WebSocket. Existen plantillas de correo para: orden creada/acuñada/cancelada/rechazada, whitelist de wallet enviada/aprobada/rechazada, dividendo distribuido, orden P2P creada/pago confirmado/tokens liberados/cancelada/expirada e invitación a inversionistas. Los colores de marca y el logo se configuran por tenant en las instancias whitelabel.

11. Postura de producción

• Los frontends se compilan de forma estática y se sirven a través de la CDN global de Cloudflare.
• Los backends están contenedorizados, con escalado horizontal donde se justifica.
• Todos los secretos externos residen en un gestor de secretos administrado, no en archivos de entorno.
• Observabilidad mediante Sentry por servicio, logs de aplicación, monitoreo on-chain (el propio event indexer es un punto de monitoreo) y los paneles de los proveedores.