오프라인 우선 월렛

솔루션 개요

기존의 월렛과 은행 앱은 안정적인 인터넷 연결에 의존하는 경우가 많습니다. 사용자가 대중 교통 시스템, 교외 지역 또는 모바일 네트워크가 불안정한 장소에 있는 경우 가장 필요할 때 잔액 확인, 거래 검토 , 연락처 관리 , 송금, 월렛에 액세스 하지 못할 수 있습니다.

사용자는 연결이 끊긴 짧은 기간 동안 유용하게 사용할 수 있는 월렛이 필요합니다. 사용자는 일시적인 네트워크 중단으로 인해 차단되지 않고 월렛에 액세스 하고 금융 작업을 완료할 수 있어야 합니다. 연결이 돌아오면 월렛은 사용자의 계정을 동기화해야 합니다.

이 솔루션은 연결이 제한될 때 필수 월렛 기능에 액세스 없는 문제를 해결합니다. 사용자가 오프라인 상태일 때에도 월렛 데이터를 계속 사용할 수 있으며, 즉각적인 네트워크 응답 없이 트랜잭션 검토, 연락처 관리, 송금과 같은 핵심 상호 작용을 계속할 수 있습니다. 또한 사용자가 온라인 과 오프라인에서 지갑 정보 액세스 하고 결제 조치를 준비하는 데 도움이 되는 AI 비서가 포함되어 있습니다. 연결이 복원되면 솔루션은 최신 변경 사항을 백엔드 와 동기화합니다. 핵심 가치는 연속성입니다. 즉, 사용자는 일시적인 네트워크 중단 시에도 자금을 관리 하고 지원을 받을 수 있습니다.

MongoDB 이러한 접근 방식을 위한 유연한 데이터 기반을 제공합니다. 잔액, 트랜잭션, 연락처, 결제 요청, 보류 중인 조치 등의 월렛 정보를 통합 데이터 계층에서 모델링합니다. 통합 데이터 계층은 애플리케이션 연결 해제 중에 필요한 월렛 상태 유지하고 사용자가 다시 연결할 때 업데이트를 조정하는 데 도움이 됩니다. 또한 동일한 데이터 기반이 AI 어시스턴트에 관련 월렛 컨텍스트를 제공하여 연결된 상태와 연결이 끊긴 상태 모두에서 이러한 상호 작용을 지원 데 도움이 됩니다.

그림 1. 솔루션의 상위 수준 아키텍처

참조 아키텍처

This solution uses an edge device and MongoDB Atlas as its core components, integrating them with an external PSP. Each component has a clearly defined role in the overall architecture. The edge device supports offline-first interactions, MongoDB Atlas provides centralized persistence and AI-accessible data services, and the PSP handles regulated payment operations.

그림 2. 참조 아키텍처 개요

엣지에서 모바일 애플리케이션 로컬 ObjectBox 데이터베이스 에 데이터를 저장하고 온디바이스 추론을 위해 Ollama를 실행합니다. 이와 함께 실행되는 Voyage AI 모델은 장치에 트랜잭션 메모를 포함하므로 네트워크 없이도 시맨틱 리콜이 계속 작동합니다. ObjectBox Sync 서버는 MongoDB Atlas 스키마 미러링하므로 애플리케이션 이 온라인 과 오프라인에서 동일한 논리적 구조를 읽고 씁니다.

MongoDB Atlas 트랜잭션, 연락처, 요청, 알림, 채팅 등 운영 중인 월렛 데이터를 보유합니다. 해당 데이터 위에는 다음과 같은 Atlas 기능이 있습니다.

• MongoDB Atlas Vector Search: Voyage AI 임베딩을 사용하여 의미별로 트랜잭션 메모를 검색합니다.

• Hybrid Search in MongoDB Atlas: fuses the vector results with a lexical search query in a single $rankFusion pipeline. This arrangement returns the right transaction for an exact merchant name and a vague description.

• Atlas Triggers: react to every insert and update on the transactions collection and upsert a durable history record, keyed by the PSP transfer reference.

• MongoDB MCP 서버: 읽기 도구를 노출하여 AI 어시스턴트가 MongoDB Atlas 직접 쿼리 수 있도록 합니다.

외부 PSP는 결제 실행 및 신원을 위한 기록 시스템으로 남아 있습니다. 앱 사용자 경험을 지원 데 필요한 참고 자료와 애플리케이션 데이터만 저장하는 반면, 전송을 승인하고 정산합니다.

이러한 책임 분리는 로컬 대응력, 클라우드 기반 인텔리전스 및 안전한 결제 실행을 결합합니다.

아키텍처 프로세스 흐름

이러한 프로세스 흐름은 하위 시스템이 상호 작용 아키텍처 복원력과 지능형 지원을 제공하는 방법을 보여줍니다. 오프라인 결제 흐름은 연결이 끊어지는 동안에도 중요한 금융 작업이 지속되도록 하여 월렛의 안정성을 유지합니다. 챗봇 지원 플로우는 로컬 인텔리전스를 활용하여 상호 작용을 간소화하여 대화형 인터페이스가 지속적인 cloud 의존 없이도 응답성을 유지할 수 있음을 보여줍니다. 이러한 프로세스를 함께 사용하면 모든 네트워크 환경에서 일관적인 사용자 경험을 제공할 수 있습니다.

오프라인 결제 흐름

이 흐름은 사용자 상호 작용과 실시간 네트워크 가용성을 분리하여 재정적 안정성을 보장합니다. 시스템은 로컬에서 트랜잭션을 대기열에 추가하여 제한된 환경에서도 원활한 결제 경험을 유지하고 연결이 복원될 때만 중앙 플랫폼과 동기화합니다.

그림 3. 오프라인 결제 순서

기기의 연결이 끊어져도 앱 계속 작동합니다. 오프라인 결제 흐름에서:

1. 사용자가 결제를 시작합니다.

2. 애플리케이션 ObjectBox에 저장된 마지막으로 동기화된 잔액과 비교하여 금액의 유효성을 검사합니다.

3. The transaction is queued locally with a local_pending status.

4. 연결이 반환되면 애플리케이션 재연결을 감지하고 보류 중인 모든 트랜잭션을 검색합니다.

5. 보류 중인 각 트랜잭션 결제를 위해 PSP에 제출됩니다.

6. 결제 후 애플리케이션 PSP 참조를 저장하고 트랜잭션 을 결제됨으로 표시합니다.

7. ObjectBox Sync 서버는 업데이트된 트랜잭션 상태 MongoDB Atlas 에 전파합니다.

이 패턴 연결이 끊어지는 동안 애플리케이션 연속성을 유지하면서 외부 PSP를 통해서만 결제가 이루어지도록 합니다.

챗봇 지원 결제 흐름

이 대화 흐름은 로컬 엣지 기반 AI 사용하여 지속적인 cloud 연결에 의존하지 않고 지능형 지원을 제공합니다. 로컬에서 사용자 의도를 처리하여 결제 초안 작성 및 문의 해결을 가능하게 한 다음, 시스템이 다시 연결되면 확인된 트랜잭션을 안전하게 실행합니다.

그림 5. 챗봇 지원 결제 순서

이 솔루션은 LangGraph 에이전트 에 AI 도우미를 구축합니다. 챗봇의 워크플로는 다음과 같이 작동합니다.

1. 사용자가 을(를) 20 저녁 식사를 위해 Luis에게 전송하는 등의 요청 보냅니다.

2. 에이전트 의도한 문의 다음과 같이 해결합니다.

   • 온라인 일 때 MongoDB MCP 서버를 통해 MongoDB Atlas 쿼리합니다.

   • 오프라인 상태에서는 ObjectBox에서 직접 문의 확인합니다.

3. 에이전트 결제 초안을 작성하고 사용자에게 확인 카드를 제시합니다.

4. 사용자가 명시적으로 트랜잭션 확인할 때까지 자금은 이동하지 않습니다.

5. 확인 후 다음 조치를 실행합니다.

   • 온라인 모드 에서 애플리케이션 전송을 PSP에 제출하고 보강 기록 MongoDB Atlas 에 씁니다.

   • 오프라인 모드 에서는 애플리케이션 이 나중에 재생할 수 있도록 로컬에서 트랜잭션 을 대기열에 추가합니다.

6. 결제가 전송되거나 대기열에 추가되면 사용자에게 알림이 전송됩니다.

이 상호 작용 모델은 핵심 아키텍처에서 정의한 것과 동일한 온라인 및 오프라인 실행 경계를 유지하면서 자연어 결제 시작과 명시적인 사용자 승인을 결합합니다.

데이터 모델 접근 방식

This solution uses a mirrored document model. This design pattern maintains the same wallet entities and document structures across MongoDB Atlas and the on-device ObjectBox store. The model supports an offline wallet built on top of a BIAN compliant external PSP.

PSP는 결제 실행 및 신원을 위한 기록 시스템으로 유지되는 반면, 애플리케이션 사용자 경험을 지원 위해 참조 및 애플리케이션 레벨 인리치먼트를 저장합니다. 이 보강에는 메모, 시맨틱 임베딩, 동기화 또는 수명 주기 상태 포함됩니다. MongoDB Atlas 와 ObjectBox에서 동일한 논리적 스키마 사용하면 애플리케이션 온라인 과 오프라인 모두에서 일관되게 작동할 수 있습니다.

아래 컬렉션은 이 솔루션이 오프라인 결제 경험을 지원 위해 애플리케이션 데이터를 모델링하는 방법을 보여줍니다.

Every collection except walletTransactionsHistory mirrors the ObjectBox database. MongoDB Atlas holds the history data and powers the vector and text indexes required for hybrid search.

Below, you find the document model for a wallet transaction, stored in the walletTransactions collection. It represents a single payment sent or received through the external PSP. The document captures the operational data needed to track the transfer and the enrichment data (embeddings, sync state) needed to power search, offline replay, and the AI assistant.

{
   "_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"
   }
}

This model unifies operational context and enrichment, simplifying deployment across cloud and device environments. The application renders pending activity, replays offline writes, and supports AI-assisted transaction retrieval using a single read. You can perform these operations, because the sync state (localSyncStatus), settlement state (leafyPayStatus), and semantic search vector (noteEmbedding) live in the same document.

민감한 금융 실행은 PSP에 남아 있는 반면, MongoDB Atlas 와 ObjectBox는 응답성, 검색 및 사용자 경험에 필요한 월렛 애플리케이션 데이터만 저장 . 프로덕션 시스템에서는 더 엄격한 유효성 검사, 액세스 제어 및 감사 추적을 통해 이러한 컬렉션을 확장할 수 있습니다.

솔루션 빌드

솔루션을 두 단계로 배포하여 로컬에서 실행 . 먼저 SSO, 동의 및 결제 실행을 처리하는 PSP를 시작합니다. 그런 다음 애플리케이션 UI, 백엔드 서비스, ObjectBox, Ollama, Voyage AI 및 동기화 구성 요소를 실행하는 Leafy 월렛을 시작합니다.

로컬 배포서버 의 경우 두 리포지토리를 나란히 복제합니다.

• Leafy 월렛

• 결제 플랫폼

Follow the instructions in the GitHub LOCAL DEPLOYMENT

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

주요 학습 사항

• 연결이 끊어져도 월렛 기능을 계속 사용할 수 있도록 유지: 네트워크 액세스 요구 사항이 아닌 개선 사항으로 처리합니다. MongoDB Atlas 가 지원하는 로컬 저장 는 잠시 연결이 끊기는 동안 잔액, 트랜잭션, 연락처, 요청 및 채팅 흐름을 사용할 수 있도록 유지했다가 기기가 다시 온라인 되면 조정됩니다.

• MongoDB Atlas 에서 애플리케이션 컨텍스트를 유지하고 결제는 PSP에 맡깁니다. Atlas 사용자 경험을 형성하는 별칭, 메모, 동기화 상태 및 임베딩을 저장하는 반면 결제 제공자 ID, 권한 부여 및 결제를 위한 기록 시스템을 유지합니다. 이 분할 규제된 실행을 가져오지 않고도 경험 계층을 유연하게 유지합니다.

• 기기와 cloud 에서 동일한 논리적 데이터 모델 읽고 쓰기 (write) . MongoDB Atlas 컬렉션 구조를 내장된 저장 에 미러링하고 변경 사항을 배경 에서 동기화 . 양쪽의 동일한 스키마는 오프라인 기능에 일반적으로 필요한 변환 계층을 제거 애플리케이션 코드가 연결 시 분기되지 않습니다.

• 문서 모델 에서 운영 컨텍스트와 인리치먼트를 함께 유지 : 전송 세부 정보, 메모, 동기화 상태 및 임베딩을 동일한 문서 에 저장하여 읽기를 간소화하고, 원자적 업데이트를 지원 , AI 지원 환경을 위한 데이터를 더 쉽게 만듭니다.

• 로컬 반응성과 cloud 인텔리전스 결합: MongoDB Atlas Vector Search, MongoDB MCP 서버, 온디바이스 저장 통해 어시스턴트가 자연어 트랜잭션 검색 및 결제 초안을 처리하다 할 수 있습니다. 사용자는 장치가 온라인 인지 여부에 관계없이 동일한 동작을 얻습니다.

작성자

• Felipe Trejos, MongoDB

• Miguel Aréjula Aísa, MongoDB

자세히 알아보기

• 에이전틱 AI 기반 결제 오케스트레이션

• MongoDB 및 BIAN을 사용한 코어 뱅킹 현대화

• 결제 현대화 솔루션 가속기