Carreira offline-first

Visão Geral da Solução

Aplicativos tradicionais de carteira e serviços bancários geralmente dependem de uma conexão estável com a internet. Quando os usuários estão em sistemas de trânsito, áreas rurais ou locais com redes móveis instáveis, eles podem não conseguir visualizar seu saldo, revisar transações, gerenciar contatos, enviar dinheiro e acessar sua carteira quando mais precisam.

Os usuários precisam de uma Carteiro que permaneça útil durante breves períodos de desconexão. Os usuários devem ser capazes de acessar suas contas e concluir tarefas financeiros sem serem bloqueados por uma interrupção temporária da rede . Quando a conectividade retornar, a pasta deverá sincronizar a conta do usuário.

Esta solução aborda a perda de acesso a funções essenciais da carteira quando a conectividade é limitada. Ela mantém os dados da carteira disponíveis quando o usuário está offline e permite que as principais interações, como revisar transações, gerenciar contatos e enviar dinheiro, continuem sem exigir uma resposta imediata da rede. Ela também inclui um assistente de IA que ajuda os usuários a acessar informações da carteira e preparar ações de pagamento, tanto online quanto offline. Assim que a conectividade é restaurada, a solução sincroniza as alterações mais recentes com o backend. O valor principal é a continuidade: os usuários podem gerenciar seu dinheiro e receber assistência durante interrupções temporárias de rede.

O MongoDB oferece uma base de dados flexível para essa abordagem. Ele modela as informações da carteira, incluindo saldos, transações, contatos, solicitações de pagamento e ações pendentes, em uma camada de dados unificada. A camada de dados unificada ajuda o aplicativo a manter o estado da carteira necessário durante a desconexão e a reconciliar as atualizações quando o usuário se reconecta. A mesma base de dados também fornece contexto relevante da carteira para o assistente de IA, ajudando-o a dar suporte a essas interações em estados conectados e desconectados.

figura 1. Arquitetura de alto nível da solução

Arquiteturas de referência

Essa solução usa um dispositivo de borda e o MongoDB Atlas como componentes principais, integrando-os a um PSP externo. Cada componente tem uma função bem definida na arquitetura geral. O dispositivo de borda oferece suporte a interações offline-first, o MongoDB Atlas fornece persistência centralizada e serviços de dados acessíveis por IA, e o PSP lida com operações de pagamento regulamentadas.

figura 2. Visão geral da arquitetura de referência

Na borda, o aplicação móvel armazena dados em um banco de dados ObjectBox local e executa o Ollama para inferência no dispositivo. Um modelo de IA Voyage é executado junto com ele, incorporando notas de transação no dispositivo para que a memória semântica continue funcionando sem uma rede. O servidor de sincronização do ObjectBox espelha o esquema do MongoDB Atlas , portanto, o aplicação lê e grava as mesmas estruturas lógicas online e offline.

O MongoDB Atlas contém os dados operacionais da Carteiro: transações, contatos, solicitações, notificações e chats. Os seguintes recursos do Atlas se baseiam nesses dados:

• MongoDB Atlas Vector Search: recupera notas de transação por significado, usando incorporações Voyage AI.

• Pesquisa Híbrida no MongoDB Atlas: funde os resultados vetoriais com uma query de pesquisa lexical em um único $rankFusion pipeline . Este acordo retorna a transação correta para um nome de fornecedor exato e uma descrição vaga.

• Atlas Triggers: reaja a cada inserção e atualização na transactions coleção e atualize um registro de histórico durável, digitado pela referência de transferência do PSP.

• Servidor MongoDB MCP: expõe ferramentas de leitura, permitindo que o assistente de IA consulte diretamente o MongoDB Atlas .

O PSP externo continua sendo o sistema de registro para execução e identidade do pagamento. Ele autoriza e estabelece transferências, enquanto o aplicativo armazena apenas as referências e dados do aplicação necessários para oferecer suporte à experiência do usuário.

Essa separação de responsabilidades combina capacidade de resposta local, inteligência baseada em nuvem e execução segura de pagamentos.

Fluxo de processo arquitetural

Esses fluxos de processo demonstram como os subsistemas interagem para fornecer resiliência arquitetônica e assistência inteligente. O fluxo de pagamentos offline garante que as operações bancárias críticas persistam durante a perda de conectividade, mantendo a confiabilidade da loja online. O fluxo assistido pelo chatbot aproveita a inteligência local para simplificar as interações, demonstrando que uma interface de conversação pode permanecer responsiva sem a dependência constante da nuvem. Juntos, esses processos oferecem uma experiência de usuário consistente em qualquer ambiente de rede.

Fluxo de pagamento offline

Esse fluxo garante a confiabilidade financeira ao desacoplar a interação do usuário da disponibilidade da rede em tempo real. Ao enfileirar transações localmente, o sistema mantém uma experiência de pagamento contínua mesmo em ambientes restritos, sincronizando com a plataforma central somente quando a conectividade é restaurada.

figura 3. Sequência de pagamento offline

O aplicativo continua funcionando quando o dispositivo perde a conectividade. Em um fluxo de pagamento offline:

1. O usuário inicia um pagamento.

2. O aplicação valida o valor em relação ao último saldo sincronizado armazenado no ObjectBox.

3. A transação é enfileirada localmente com um status local_pending.

4. Quando a conectividade retorna, o aplicação detecta a reconexão e recupera todas as transações pendentes.

5. Cada transação pendente é enviada ao PSP para liquidação.

6. Após a cobrança, o aplicação armazena a referência do PSP e marca a transação como paga.

7. O Servidor de Sincronização do ObjectBox propaga o estado da transação atualizado para o MongoDB Atlas.

Esse padrão preserva a continuação do aplicação durante a perda de conectividade, garantindo que a resolução de pagamentos ocorra somente por meio do PSP externo.

Fluxo de pagamento assistido por chatbot

Esse fluxo de conversação usa IA local baseada na borda para fornecer assistência inteligente sem depender de uma conexão persistente com a nuvem. Ele processa a intenção do usuário localmente, permitindo o rascunho do pagamento e a resolução do contato, e, em seguida, executa com segurança as transações confirmadas quando o sistema se reconecta.

figura 5. Sequência de pagamento assistida por chatbot

A solução constrói o assistente de IA em um agente LangGraph. O fluxo de trabalho do bot de chat funciona da seguinte forma:

1. O usuário envia uma solicitação como Enviar para 20 o Luan para o restaurante.

2. O agente resolve o contato pretendido:

   • Quando online, ele consulta o MongoDB Atlas por meio do servidor MongoDB MCP.

   • Quando offline, resolve o contato diretamente do ObjectBox.

3. O agente rascunhos o pagamento e apresenta um cartão de confirmação ao usuário.

4. Os recursos não são movidos até que o usuário confirme explicitamente a transação.

5. Após a confirmação, ele executa as seguintes ações:

   • No modo online, o aplicativo envia a transferência para o PSP e grava um registro de enriquecimento no MongoDB Atlas.

   • No modo offline, o aplicação enfileira a transação localmente para reprodução posterior.

6. O usuário recebe uma notificação quando o pagamento é enviado ou colocado em fila.

Esse modelo de interação combina a iniciação de pagamento em linguagem natural com a aprovação explícita do usuário, preservando os mesmos limites de execução online e offline definidos pela arquitetura principal.

Abordagem do modelo de dados

Esta solução usa um modelo de documento espelhado. Esse padrão de design mantém as mesmas entidades de logo e estruturas de documento no MongoDB Atlas e no armazenamento ObjectBox no dispositivo. O modelo suporta uma coleção offline construída sobre um PSP externo compatível com Bian.

O PSP continua sendo o sistema de registro para execução e identidade do pagamento, enquanto o aplicação armazena referências e enriquecimento no nível do aplicação para oferecer suporte à experiência do usuário. Esse enriquecimento inclui anotações, incorporações semânticas e estado de sincronização ou ciclo de vida. Usar o mesmo esquema lógico no MongoDB Atlas e no ObjectBox permite que o aplicação funcione consistentemente online e offline.

As collections abaixo mostram como esta solução modela seus dados de aplicação para suportar a experiência de pagamento offline.

Cada coleção, exceto walletTransactionsHistory, espelha o banco de dados do ObjectBox. O MongoDB Atlas mantém os dados de histórico e alimenta os índices vetoriais e de texto necessários para a pesquisa híbrida.

Abaixo, você encontra o modelo de documento para uma transação de carteiro, armazenado na coleção walletTransactions. Representa um único pagamento enviado ou recebido através do PSP externo. O documento captura os dados operacionais necessários para rastrear a transferência e os dados de enriquecimento (incorporações, estado de sincronização) necessários para alimentar a pesquisa, a repetição offline e o assistente 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"
   }
}

Esse modelo unifica o contexto operacional e o enriquecimento, simplificando a implantação em ambientes de nuvem e dispositivos. O aplicação renderiza atividades pendentes, reproduz gravações offline e suporta recuperação de transações assistida por IA usando uma única leitura. Você pode executar estas operações, pois o estado de sincronização (localSyncStatus), estado de resolução (leafyPayStatus) e vetor de pesquisa semântica (noteEmbedding) residem no mesmo documento.

A execução financeira sensível permanece no PSP, enquanto o MongoDB Atlas e o ObjectBox armazenam apenas os dados do aplicação de identidade necessários para capacidade de resposta, pesquisa e experiência do usuário. Em um sistema de produção, você pode estender essas collections com validação, controles de acesso e faixas de auditar mais rigorosos.

Construir a solução

Implemente a solução em duas etapas para executá-la localmente. Primeiro, inicie o PSP, que lida com SSO, consenso e execução de pagamento. Em seguida, inicie o Leafy Charts, que executa a interface do usuário do aplicação , serviços de backend, ObjectBox, Ollama, Voyage AI e componentes de sincronização.

Para implantação local, clone ambos os repositórios lado a lado:

• Careira Frondosa

• A plataforma de pagamento

Siga as instruções na Implantação local do GitHub

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

Principais Aprendizados

• Mantenha os recursos da agenda utilizáveis quando a conectividade cair: Trate o acesso à rede como um aprimoramento e não como um requisito. Um armazenamento local apoiado pelo MongoDB Atlas mantém saldos, transações, contatos, solicitações e fluxos de chat disponíveis durante desconexões curtas e, em seguida, se reconcilia quando o dispositivo está online novamente.

• Mantenha o contexto do aplicação no MongoDB Atlas e deixe a definição para o PSP: o Atlas armazena os aliases, as anotações, o estado de sincronização e as incorporações que moldam a experiência do usuário, enquanto o provedor de pagamento mantém o sistema de registro para identidade, autorização e resolução. Essa divisão mantém a camada de experiência flexível sem puxar a execução regulamentada para ela.

• Leia e grave o mesmo modelo de dados lógico no dispositivo e na nuvem: espelhe estruturas de coleção do MongoDB Atlas em um armazenamento incorporado e sincronize alterações em segundo plano. Esquemas idênticos em ambos os lados removem a camada de tradução que os recursos offline normalmente exigem, de modo que o código do aplicativo não se ramifica com base na conectividade.

• Mantenha o contexto operacional e o enriquecimento juntos no modelo de documento : armazene detalhes de transferência, anotações, estado de sincronização e incorporações no mesmo documento para simplificar leituras, oferecer suporte a atualizações atômicas e facilitar os dados para experiências assistidas por IA.

• Combine a capacidade de resposta local com a inteligência de nuvem: o MongoDB Atlas Vector Search, o servidor MongoDB MCP e o armazenamento no dispositivo permitem que os assistentes lidam com a descoberta de transações e o esquema de pagamentos em linguagem natural. Os usuários obtêm o mesmo comportamento se o dispositivo estiver online ou não.

Autores

• Felipe Trejos, MongoDB

• Miguel Aréjula Aísa, MongoDB

Saiba mais

• Orquestração de pagamentos com IA agêntica

• Modernização do Core Banking com MongoDB e BIAN

• Solução para acelerar a modernização de pagamentos