Arquitectura e Integraciones
Arquitectura e Integraciones
Libertum es un sistema distribuido: tres aplicaciones web de usuario final, un conjunto de servicios backend contenedorizados, una capa de smart contracts sobre varias cadenas EVM y Cardano, y un grupo de integraciones de terceros. Esta página es un panorama de alto nivel; para detalles de integración consulte la sección para desarrolladores.
1. La arquitectura a alto nivel
┌─────────────────────────────────────────────────────────────────────┐
│ CAPA DE USUARIO FINAL │
│ App T-Suite (Marketplace) Consola Admin App Transfer Agent │
│ React 18 / TypeScript / Vite │
└─────────────────────────┬─────────────────────────┬─────────────────┘
│ HTTPS + SSE │
┌─────────────────────────▼─────────────────────────▼─────────────────┐
│ CAPA DE SERVICIOS │
│ Marketplace API · Admin API · Transfer Agent API · Notification │
│ Event service · Dividend service · Cardano service │
│ Node.js / TypeScript — gRPC + Kafka │
└─────────────────────┬───────────────────────────────┬───────────────┘
│ │
┌─────────────▼──────────┐ ┌──────────▼──────────────┐
│ CAPA DE DATOS │ │ CAPA DE INTEGRACIÓN │
│ MongoDB · Redis · │ │ SumSub · Stripe · │
│ blob storage en nube │ │ Bridge.xyz · SendGrid ·│
│ │ │ Gmail · Anthropic · │
│ │ │ proveedores RPC │
└────────────────────────┘ └─────────────────────────┘
│
┌───────────────────▼──────────────────┐
│ CAPA DE BLOCKCHAIN │
│ Mainnets EVM: Base, Ethereum, │
│ Polygon, Arbitrum (ERC-3643 …) │
│ Cardano mainnet — CIP-20 · CIP-113 │
│ Cardano preview — CIP-113 │
│ XRPL mainnet — IC · MPT (XLS-33) │
└──────────────────────────────────────┘2. Aplicaciones frontend
Tres aplicaciones de página única (SPA) en React 18, construidas con TypeScript y Vite.
Marketplace (la app T-Suite)
La aplicación principal en app.libertum.io. Combina las pestañas de persona a las que el usuario tiene derecho: Inversor, Emisor, Asset Management, Distribution Hub, Structuring, Funds y Stablecoin Studio.
Stack: React 18, TypeScript, Vite, Redux Toolkit, TanStack React Query, RainbowKit + wagmi + viem + ethers v6, Formik, React Bootstrap y Tailwind CSS, Recharts, Sentry.
Detección de modo: la aplicación inspecciona el hostname y alterna entre dos modos:
- Core — la app T-Suite propia de Libertum.
- Whitelabel de plataforma — la plataforma con la marca de un tenant en su propio dominio. Cada marketplace de tenant muestra sus propias ofertas más las ofertas alojadas a través del Ecosystem Directory.
El antiguo modo shopfront de una sola oferta está obsoleto.
Admin
La consola SuperAdmin de Libertum: revisión de usuarios y de KYC/KYB, aprobación de ofertas, permisos de subadministradores, tarifas de la plataforma, restricciones por país, planes y módulos, aprobación de retiros y otros controles de la plataforma.
Transfer Agent
Una aplicación web independiente para agentes de transferencias. Se comunica con la Transfer Agent API e interactúa con los contratos de token mediante ethers. Pantallas:
- Dashboard — tarjetas de resumen, gráficos (por ejemplo, valuación de activos y principales titulares) y actividad reciente.
- Cap Table — titulares y saldos por oferta.
- Wallet Whitelist — aprobar o rechazar wallets de inversores por oferta, con la prueba de KYC del inversor disponible para revisión.
- User Details — el perfil y los datos de verificación del inversor detrás de una solicitud de whitelist.
- Transfer Journal — el registro de transferencias de tokens, incluidas las transferencias forzadas.
- Transactions — historial de transacciones.
- Settings — configuración de la cuenta, incluido el cambio de contraseña.
3. Servicios backend
Un conjunto de servicios en Node.js / TypeScript, cada uno responsable de un dominio:
| Servicio | Dominio |
|---|---|
| Marketplace API | La API principal: usuarios, ofertas, órdenes, suscripciones, acuerdos, Custodian Wallet, Distribution Hub, Structuring, Funds, Stablecoin Studio, redenciones, tareas programadas y el flujo de notificaciones en tiempo real |
| Admin API | Operaciones SuperAdmin: tarifas, restricciones por país, aprobaciones |
| Servicio de notificaciones | Correo y notificaciones en tiempo real |
| Event service | Indexador de eventos blockchain: consulta las cadenas de forma programada y publica los eventos en Kafka |
| Servicio de dividendos | Procesamiento de dividendos |
| Transfer Agent API | Consultas al cap table, decisiones de whitelist y acciones del agente de transferencias |
| Servicio de Cardano | Operaciones de tokens CIP-20 y CIP-113, y firma de custodia en Cardano |
La API del marketplace se sirve bajo la ruta base /marketplace/v1. Las rutas autenticadas están bajo /auth/...; algunas rutas públicas están bajo /public/... (por ejemplo, las restricciones por país). Todavía no existe una especificación OpenAPI pública.
4. Capa de datos
- MongoDB — almacén documental principal: usuarios, ofertas, órdenes, transferencias, dividendos, P2P, suscripciones, planes, módulos, registros de KYC, wallets de custodia y registros de auditoría.
- Redis — cachés, tokens de corta duración y bloqueos distribuidos para las tareas programadas.
- Blob storage en la nube — documentos e imágenes cargados.
- Kafka — el bus de eventos asíncrono entre servicios (consulte la sección 7).
5. Modelo de autenticación e identidad
- Inicio de sesión: correo y contraseña.
- Sesiones: tokens JWT de tipo bearer respaldados por una sesión en el servidor por navegador, con un tiempo de inactividad deslizante (60 minutos por defecto); iniciar sesión en otro dominio o dispositivo no termina las demás sesiones.
- Autenticación de dos factores: app autenticadora (TOTP) con códigos de respaldo.
- Acciones sensibles (por ejemplo, retiros de la Custodian Wallet o la firma de un acuerdo) requieren un paso de verificación adicional, como un OTP por correo.
Quién usa qué:
- Inversores (personas e instituciones) y emisores usan la app T-Suite; un usuario puede tener varias personas, y el acceso a cada pestaña de persona depende de la suscripción.
- Los administradores de Libertum usan la consola Admin; los subadministradores solo ven lo que sus permisos permiten.
- Los agentes de transferencias usan la app Transfer Agent.
KYC frente a KYB. Ambos se ejecutan mediante SumSub. 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í usan gRPC para las llamadas internas entre servicios. gRPC conecta los servicios de marketplace, admin, notificaciones y transfer agent — por ejemplo, consultas de usuario y de KYC, acciones de aprobación y la lectura o marcado de notificaciones in-app.
7. Comunicación asincrónica: Kafka
Los eventos asíncronos fluyen a través de topics de Kafka, de modo que productores y consumidores quedan débilmente acoplados.
| Grupo de topics | Productor | Consumidor | Ejemplos |
|---|---|---|---|
| Topics de notificaciones | Marketplace API y otros servicios | Servicio de notificaciones | Notificaciones in-app, disparadores de envío de correo |
| Topics de actualización de producto | Event service, Admin API | Marketplace API | Eventos on-chain (acuñaciones, transferencias, actividad de escrow), decisiones de aprobación |
8. Tareas programadas
El trabajo programado se ejecuta con node-cron dentro de la API del marketplace — alrededor de dos docenas de tareas. Cada tarea toma un bloqueo basado en Redis para que solo una instancia la ejecute a la vez. Algunos ejemplos: gestión de dividendos, expiración de órdenes sin pagar y de órdenes P2P, apertura de los listados Coming Soon a su hora de lanzamiento, procesamiento de redenciones, expiración de solicitudes de hosting, el resumen de notificaciones de la plataforma, la facturación mensual del uso de IA, la expiración del acceso por suscripción y el motor de operación simulada.
Por separado, el event service consulta cada cadena soportada de forma programada y publica en Kafka lo que encuentra.
9. Integraciones de terceros
| Servicio | Se usa para |
|---|---|
| SumSub | Verificación de identidad KYC y KYB |
| Stripe | Pagos con tarjeta, facturación de suscripciones y Stripe Connect para los pagos a emisores |
| Bridge.xyz | Rampa de entrada y salida de fiat de T-Pay (disponibilidad limitada) |
| SendGrid | Correo transaccional |
| Gmail (OAuth de solo lectura) | Conexión de la bandeja de entrada del Distribution Hub |
| Modelos Claude de Anthropic | Libby AI y Structuring |
| Blob storage en la nube | Carga de documentos e imágenes |
| Proveedores RPC comerciales | Acceso a cadenas EVM, con conmutación por error |
| Blockfrost | Datos de la cadena Cardano |
| WalletConnect / RainbowKit | Conexión de wallets externas |
| Cloudflare | Dominios propios para tenants whitelabel (Cloudflare for SaaS) |
| Sentry | Seguimiento de errores |
También se puede pagar por transferencia bancaria; en USDC o USDT a través del contrato Escrow en las cadenas EVM; en RLUSD o USDC en el XRP Ledger (verificados on-ledger — USDT no se acepta en XRPL, ya que allí no existe Tether nativo); y desde el saldo de custodia del inversor, con las comisiones de red patrocinadas para el inversor y facturadas al emisor de la oferta.
10. Notificaciones y plantillas de correo
El correo lo envía el servicio de notificaciones. Las plantillas cubren órdenes, decisiones de whitelist de wallets, dividendos, órdenes P2P, invitaciones y eventos de la plataforma. Los colores de marca y el logo se configuran por tenant en las instancias whitelabel.
Las notificaciones en tiempo real en el navegador usan un flujo de Server-Sent Events. Para abrir el flujo, la app solicita primero un ticket de flujo de un solo uso y corta duración y se conecta con él, de modo que el token de acceso nunca aparece en la URL del flujo.
11. Postura de producción
- Los frontends son aplicaciones de página única compiladas de forma estática.
- Los servicios backend se ejecutan como servicios contenedorizados.
- Los endpoints de administración se llaman de servidor a servidor a través de un proxy de administración y cada solicitud va firmada (HMAC).
- El acceso RPC usa proveedores comerciales con conmutación por error.
- Observabilidad mediante Sentry por servicio, logs de aplicación y monitoreo on-chain (el propio event service es un punto de monitoreo).
12. Componentes del backend
La API del marketplace está organizada en componentes. Los principales:
| Componente | Qué hace |
|---|---|
| structuring | Proyectos de Structuring, intake, investigación con IA, generación de documentos, revisión legal de invitados y creación del borrador de oferta |
| aiUsage | Medición del uso de IA por titular y por producto, crédito incluido y facturación del excedente |
| sseNotifications | El flujo de notificaciones por Server-Sent Events y sus tickets de flujo de un solo uso |
| custodianWallet | Wallets gestionadas por la plataforma: depósitos, direcciones de retiro guardadas, retiros y sus controles |
| gasTreasury | Estimaciones de tarifas de red, saldos prepagados de gas y cobros de gas de las transacciones de custodia |
| bridge | Rampa de entrada y salida de fiat de T-Pay a través de Bridge.xyz |
| governance | Propuestas de gobernanza y votación de inversores |
| p2p | El mercado secundario P2P: listados, órdenes y sus tarifas |
| hosting | Solicitudes de hosting entre marketplaces y la bandeja de hosting |
| investorStatements | El resumen de estados de cuenta del inversor y su feed de transacciones |
| agreements | Plantillas de acuerdos, firma electrónica con OTP y la pista de auditoría por acuerdo |
| redemption | Ventanas de redención, solicitudes, cuentas de pago y liquidación |
| distributionHub | CRM del Distribution Hub, descubrimiento de inversores, matching, campañas y Libby AI |
| countryRestrictions | La lista gris y la lista negra de países de toda la plataforma |
| feeConfig | Tarifas predeterminadas de la plataforma y excepciones por emisor y por oferta |
Componentes de XRPL
Estado: Disponible — XRPL está disponible en mainnet y es seleccionable en el Tokenization Wizard (XRPL Issued Currency y MPT XLS-33).
Otros tres componentes dan soporte a las ofertas en XRPL:
| Componente | Qué hace |
|---|---|
| xrplPlatform | Las cuentas de plataforma de Libertum en XRPL |
| xrplCredentialIssuer | Emisión de credenciales on-ledger (XRPL Credentials) y autorización de trust lines |
| xrplReserve | Gestión de la reserva de las cuentas XRPL |