Cartera sin conexión ante todo

Descripción general de la solución

Las aplicaciones tradicionales de billetera y banca suelen depender de una conexión a Internet estable. Cuando los usuarios se encuentran en sistemas de transporte, zonas rurales o lugares con redes móviles poco confiables, es posible que no puedan consultar su saldo, revisar transacciones, gestionar contactos, enviar dinero ni acceder a su billetera cuando más lo necesitan.

Los usuarios necesitan una cartera que siga siendo útil durante breves períodos de desconexión. Los usuarios deberían poder acceder a su cartera y completar tareas financieras sin que una interrupción del servicio temporal de la red les impida hacerlo. Cuando se restablezca la conectividad, la cartera debe sincronizar la cuenta del usuario.

Esta solución direcciona la pérdida de acceso a las funciones esenciales de la billetera cuando la conectividad es limitada. Mantiene los datos de la billetera disponibles cuando el usuario está sin conexión y permite que las interacciones principales, como revisar transacciones, gestionar contactos y enviar dinero, continúen sin requerir una respuesta inmediata de la red. También incluye un asistente de IA que ayuda a los usuarios a acceder a la información de la billetera y preparar acciones de pago tanto en línea como sin conexión. Una vez que se restaura la conectividad, la solución sincroniza los cambios más recientes con el backend. El valor principal es la continuidad: los usuarios pueden gestionar su dinero y recibir asistencia durante interrupciones temporales del servicio de red.

MongoDB proporciona la base de datos flexible para este enfoque. Modela la información de la billetera, incluidos los saldos, las transacciones, los contactos, las solicitudes de pago y las acciones pendientes, en una capa de datos unificada. La capa de datos unificada ayuda a la aplicación a mantener el estado de la billetera necesario durante la desconexión y a conciliar las actualizaciones cuando el usuario se vuelve a conectar. La misma base de datos también proporciona contexto relevante sobre la billetera al asistente de IA, lo que ayuda a admitir estas interacciones tanto en estados conectados como desconectados.

Figura 1. Arquitectura de alto nivel de la solución

Arquitecturas de Referencia

Esta solución utiliza un dispositivo de borde y MongoDB Atlas como componentes principales, integrándolos con un proveedor de servicios de pago externo. Cada componente tiene una función claramente definida en la arquitectura general. El dispositivo de borde admite interacciones sin conexión, MongoDB Atlas proporciona persistencia centralizada y servicios de datos accesibles mediante IA, y el proveedor de servicios de pago gestiona las operaciones de pago reguladas.

Figura 2. Visión general de la arquitectura de referencia

En el borde, la aplicación móvil almacena datos en una base de datos local de ObjectBox y ejecuta Ollama para la inferencia en el dispositivo. Un modelo de Voyage AI se ejecuta junto a él, incrustando notas de transacción en el dispositivo para que la recuperación semántica siga funcionando sin una red. ObjectBox Sync Server refleja el esquema de MongoDB Atlas, por lo que la aplicación lee y guarda las mismas estructuras lógicas en línea y sin conexión.

MongoDB Atlas contiene los datos de la cartera operativa: transacciones, contactos, solicitudes, notificaciones y chats. Las siguientes capacidades de Atlas se basan en esos datos:

• MongoDB Atlas Vector Search: recupera notas de transacciones por significado, utilizando incrustaciones de Voyage AI.

• Búsqueda híbrida en MongoDB Atlas: fusiona los resultados vectoriales con una consulta de búsqueda léxica en un único pipeline $rankFusion. Esta disposición devuelve la transacción correcta para un nombre de comerciante exacto y una descripción vaga.

• Atlas Triggers: reaccionar a cada inserción y actualizar en la colección transactions e inserción de un registro de historial duradero, indexado por la referencia de transferencia de PSP.

• MongoDB MCP servidor: expone herramientas de lectura, permitiendo que el asistente de IA query MongoDB Atlas directamente.

El PSP externo sigue siendo el sistema de registro para la ejecución de pagos y la identidad. Autoriza y liquida transferencias, mientras que la aplicación almacena solo las referencias y los datos de la aplicación necesarios para respaldar la experiencia del usuario.

Esta separación de responsabilidades combina la capacidad de respuesta local, la inteligencia basada en la nube y la ejecución segura de pagos.

Flujo del proceso arquitectónico

Estos flujos de proceso demuestran cómo interactúan los subsistemas para ofrecer resiliencia arquitectónica y asistencia inteligente. El flujo de pago sin conexión garantiza que las operaciones financieras críticas persistan durante la pérdida de conectividad, manteniendo la fiabilidad de la cartera. El flujo asistido por chatbot aprovecha la inteligencia local para simplificar las interacciones, demostrando que una interfaz conversacional puede seguir siendo receptiva sin depender constantemente de la nube. Juntos, estos procesos ofrecen una experiencia de usuario coherente en cualquier entorno de red.

Flujo de pago sin conexión

Este flujo garantiza la fiabilidad financiera al desacoplar la interacción del usuario de la disponibilidad de la red en tiempo real. Al poner en cola las transacciones localmente, el sistema mantiene una experiencia de pago sin interrupciones incluso en entornos restringidos, sincronizándose con la plataforma central solo cuando se produce la restauración de la conectividad.

Figura 3. Secuencia de pago sin conexión

La aplicación sigue funcionando cuando el dispositivo pierde la conectividad. En un flujo de pago sin conexión:

1. El usuario inicia un pago.

2. La aplicación valida la cantidad frente al último saldo sincronizado almacenado en ObjectBox.

3. La transacción se pone en cola localmente con un estado de local_pending.

4. Cuando se restablezca la conectividad, la aplicación detecta la reconexión y recupera todas las transacciones pendientes.

5. Cada transacción pendiente se envía al PSP para su liquidación.

6. Después de la liquidación, la aplicación almacena la referencia PSP y marca la transacción como liquidada.

7. El servidor de sincronización de ObjectBox propaga el estado actualizado de la transacción a MongoDB Atlas.

Este patrón preserva la continuidad de la aplicación durante la pérdida de conectividad, al tiempo que garantiza que la liquidación de pagos se realice únicamente a través del PSP externo.

Flujo de pago asistido por chatbot

Este flujo conversacional utiliza IA local basada en el borde para proporcionar asistencia inteligente sin depender de una conexión persistente a la nube. Procesa la intención del usuario localmente, lo que permite la redacción de pagos y la resolución de contactos, y luego ejecuta de forma segura las transacciones confirmadas cuando el sistema se vuelve a conectar.

Figura 5. Secuencia de pago asistida por chatbot

La solución construye el asistente de IA en un agente de LangGraph. El flujo de trabajo para el bot de chat funciona de la siguiente manera:

1. El usuario envía una solicitud como Enviar 20 a Luis para la cena.

2. El agente resuelve el contacto previsto:

   • Cuando está en linea, realiza queries a MongoDB Atlas a través del servidor MCP de MongoDB.

   • Cuando está fuera de línea, resuelve el contacto directamente desde ObjectBox.

3. El agente prepara el pago y presenta una tarjeta de confirmación al usuario.

4. Los fondos no se mueven hasta que el usuario confirma explícitamente la transacción.

5. Tras la confirmación, ejecuta las siguientes acciones:

   • En modo en linea, la aplicación envía la transferencia al PSP y guarda un registro de enriquecimiento en MongoDB Atlas.

   • En modo sin conexión, la aplicación pone en cola la transacción localmente para su reproducción posterior.

6. El usuario recibe una notificación una vez que se ha enviado el pago o se ha puesto en cola.

Este modelo de interacción combina la iniciación de pagos en lenguaje natural con la aprobación explícita del usuario, al tiempo que conserva los mismos límites de ejecución en linea y fuera de línea definidos por la arquitectura central.

Enfoque de modelo de datos

Esta solución utiliza un modelo de documentos duplicados. Este patrón de diseño mantiene las mismas entidades de billetera y estructuras de documentos en MongoDB Atlas y en el almacenamiento ObjectBox del dispositivo. El modelo admite una billetera sin conexión basada en un PSP externo compatible con BIAN.

El PSP sigue siendo el sistema de registro para la ejecución de pagos y la identidad, mientras que la aplicación almacena referencias y enriquecimiento a nivel de aplicación para respaldar la experiencia del usuario. Este enriquecimiento incluye notas, incrustaciones semánticas y sincronización o estado del ciclo de vida. El uso del mismo esquema lógico en MongoDB Atlas y ObjectBox permite que la aplicación funcione de forma coherente tanto en linea como sin conexión.

Las colecciones a continuación muestran cómo esta solución modela los datos de su aplicación para respaldar la experiencia de pago sin conexión.

Cada colección, excepto walletTransactionsHistory, refleja la base de datos ObjectBox. MongoDB Atlas almacena los datos del historial y alimenta los índices de vectores y texto necesarios para la búsqueda híbrida.

A continuación, encontrará el modelo orientado a documentos para una transacción de cartera, almacenado en la colección walletTransactions. Representa un pago único enviado o recibido a través del PSP externo. El documento captura los datos operativos necesarios para rastrear la transferencia y los datos de enriquecimiento (incrustaciones, estado de sincronización) necesarios para potenciar la búsqueda, la reproducción sin conexión y el asistente de IA.

{
   "_id": {
      "$oid": "unique_id"
   },
   "leafyPayTransferReference": "string",
   "ownerPartyRef": "string",
   "counterpartyArrangementReference": "string",
   "amount": "number",
   "currency": "string",
   "note": "string",
   "noteEmbedding": [
      "number",
      "..."
   ],
   "direction": "sent | received",
   "leafyPayStatus": "pending | settled | failed | exception",
   "localSyncStatus": "local_pending | synced",
   "createdAt": {
      "$date": "ISODate"
   },
   "settledAt": {
      "$date": "ISODate"
   }
}

Este modelo unifica el contexto operativo y el enriquecimiento, simplificando la implementación en entornos de nube y dispositivos. La aplicación renderiza la actividad pendiente, reproduce las escrituras sin conexión y admite la recuperación de transacciones asistida por IA mediante una única lectura. Puede realizar estas operaciones, porque el estado de sincronización (localSyncStatus), el estado de liquidación (leafyPayStatus) y el vector de búsqueda semántica (noteEmbedding) residen en el mismo documento.

La ejecución financiera confidencial permanece en el PSP, mientras que MongoDB Atlas y ObjectBox solo almacenan los datos de la aplicación de cartera necesarios para la capacidad de respuesta, la búsqueda y la experiencia del usuario. En un sistema de producción, puede ampliar estas colecciones con una validación más estricta, controles de acceso y registros de auditoría.

Compilar la solución

Implemente la solución en dos etapas para ejecutarla localmente. Primero, inicie el PSP, que gestiona el SSO, el consentimiento y la ejecución de pagos. Luego, inicie Leafy Wallet, que ejecuta la interfaz de usuario de la aplicación, los servicios de backend, ObjectBox, Ollama, Voyage AI y los componentes de sincronización.

Para la implementación local, clona ambos repositorios uno al lado del otro:

• Leafy Wallet

• La plataforma de pagos

Sigue las instrucciones en GitHub LOCAL DEMPOYMENT

git clone https://github.com/mongodb-industry-solutions/leafy-wallet.git
git clone https://github.com/mongodb-industry-solutions/sec-fsi-pci-dss.git

#frontend
CLIENT_ID=<id>
CLIENT_SECRET=<secret>
PSP_BASE_URL=http://host.docker.internal:8081
PSP_FRONTEND_URL=http://localhost:8083
APP_BASE_URL=http://localhost:8080
REDIRECT_URI=http://localhost:8080/api/auth/callback
LOOKUP_DIGEST_KEY=<key>
#backend
MONGODB_URI="<your-atlas-connection-string>"
DATABASE_NAME="<db-name>"
APP_NAME=leafy-wallet-backend
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
LOOKUP_DIGEST_KEY="<key>"

cd sec-fsi-pci-dss
npm run setup:db
npm run setup:seed
npm run dev

cd leafy-wallet/backend
uv run python scripts/create_vector_index.py
cd ..
docker compose up -d --build

Lecciones clave

• Mantenga la funcionalidad de la cartera utilizable cuando se pierde la conectividad: Trate el acceso a la red como una mejora en lugar de un requisito. Un almacenamiento local respaldado por MongoDB Atlas mantiene los saldos, las transacciones, los contactos, las solicitudes y los flujos de chat disponibles durante desconexiones cortas, y luego se reconcilia una vez que el dispositivo vuelve a estar en linea.

• Mantenga el contexto de la aplicación en MongoDB Atlas y deje la liquidación al PSP: Atlas almacena los alias, las notas, el estado de sincronización y las incrustaciones que dan forma a la experiencia del usuario, mientras que el proveedor de pagos sigue siendo el sistema de registro para la identidad, la autorización y la liquidación. Esta división mantiene flexible la capa de experiencia sin incorporar la ejecución regulada.

• Lea y guarde el mismo modelo de datos lógico en el dispositivo y en la nube: refleje las estructuras de colección de MongoDB Atlas en un almacén incrustado y sincronice los cambios en segundo plano. Los esquemas idénticos en ambos lados remueven la capa de traducción que suelen necesitar las funcionalidades sin conexión, por lo que el código de la aplicación no se ramifica según la conectividad.

• Mantenga el contexto operativo y el enriquecimiento juntos en el modelo orientado a documentos: Almacenar los detalles de transferencia, las notas, el estado de sincronizar y las incrustaciones en el mismo documento para simplificar las lecturas, admitir actualizar atómicas y facilitar los datos para experiencias asistidas por IA.

• Combine la capacidad de respuesta local con la inteligencia en la nube: MongoDB Atlas Vector Search, el MongoDB MCP Server y el almacenamiento en el dispositivo permiten a los asistentes gestionar la detección de transacciones en lenguaje natural y la elaboración de pagos. Los usuarios obtienen el mismo comportamiento independientemente de si el dispositivo está en linea o no.

Autores

• Felipe Trejos, MongoDB

• Miguel Aréjula Aísa, MongoDB

Obtén más información

• Orquestación de pagos con IA agéntica

• Modernización de la banca central con MongoDB y BIAN

• Acelerador de solución de modernización de pagos