Bank Integration Adapters

Relevant source files

The following files were used as context for generating this wiki page:

• BANK_INTEGRATION_GUIDE.md
• backend/app/integrations/kraken_example.py
• frontend/lib/actions/csv-import.ts
• README.md
• frontend/scripts/import-revolut-csv.ts
• backend/app/integrations/base.py

Introduction

Bank Integration Adapters in this application facilitate the programmatic and manual ingestion of financial data from various institutions. By utilizing an adapter pattern, the system decouples the specific API or file format logic of a financial provider from the core synchronization and persistence services. This architecture allows the platform to support a wide range of integration types, including real-time API sync (e.g., Plaid, TrueLayer), exchange-specific adapters (e.g., Kraken), and manual file-based imports (e.g., Revolut CSV).

Sources: BANK_INTEGRATION_GUIDE.md:3-8, README.md:105-115

Architecture Overview

The integration system is built on a modular architecture where different "adapters" implement a common interface or follow a standard processing pipeline. This ensures that regardless of the source, the data is normalized before being passed to the SyncService for deduplication, categorization, and storage.

Integration Patterns

The system supports three primary modes of data integration:

1. API-Based Adapters: Programmatic connections using third-party aggregators like Plaid and TrueLayer.
2. Direct Exchange Adapters: Custom implementations for specific platforms like Kraken.
3. CSV Import Adapters: Flexible file processing for banks that do not offer public APIs, such as Revolut.

Sources: BANK_INTEGRATION_GUIDE.md:12-25, BANK_INTEGRATION_GUIDE.md:115-125

Implementation Details

The BankAdapter Interface

To add a new programmatic integration, a new class must be created in backend/app/integrations/ that inherits from the BankAdapter base class. This ensures a consistent contract for fetching accounts and transactions.

from app.integrations.base import BankAdapter

class MyBankAdapter(BankAdapter):
    def fetch_accounts(self) -> List[AccountData]:
        # Implement account fetching logic
        pass
    
    def fetch_transactions(self, account_external_id, start_date, end_date):
        # Implement transaction fetching logic
        pass

Sources: BANK_INTEGRATION_GUIDE.md:115-128, backend/app/integrations/base.py

Automated CSV Processing

For manual imports, the application utilizes an AI-assisted column mapping system. This system analyzes CSV headers and sample rows using OpenAI to automatically identify fields like dates, amounts, and merchants.

Field	Description
date	Transaction date (supports multiple formats like ISO, DD-MM-YYYY, etc.)
amount	Numerical value of the transaction
description	Narrative or description provided by the bank
merchant	Identified merchant name
fee	Additional charges deducted from the balance
state	Current status (e.g., COMPLETED, PENDING)

Sources: frontend/lib/actions/csv-import.ts:35-50, frontend/lib/actions/csv-import.ts:165-200

Transaction Normalization and Deduplication

A critical component of the integration adapters is the generation of a deterministic external_id. This ID is used to prevent the import of duplicate transactions during subsequent syncs. For CSV imports, the ID is typically a hash of the account ID, date, amount, description, and merchant.

Sources: frontend/lib/actions/csv-import.ts:643-660, frontend/scripts/import-revolut-csv.ts:250-260

Specific Integrations

Kraken Adapter

The Kraken integration demonstrates handling for specialized assets. It manages tiered rate limits through a "leaky bucket" system and fetches data in 3-month windows to accommodate API constraints. It processes various ledger types, including trades, staking, and transfers.

Sources: backend/app/integrations/kraken_example.py:15-30, backend/app/integrations/kraken_example.py:100-115

Revolut Integration

Revolut data is primarily handled via CSV imports. The system includes pre-defined patterns to automatically categorize Revolut transactions into groups such as "Groceries," "Transportation," and "Subscriptions."

Sources: frontend/lib/actions/csv-import.ts:910-945, frontend/scripts/import-revolut-csv.ts:150-170

Configuration and Security

API-based adapters require secure handling of credentials and tokens.

Configuration	Usage
access_token	Securely stored (encrypted) for persistent bank connections
INTERNAL_AUTH_SECRET	Used for signed requests between frontend and backend
PLAID_ENVIRONMENT	Defines the environment (sandbox, production)
OPENAI_API_KEY	Enables AI-powered column mapping and categorization

Sources: BANK_INTEGRATION_GUIDE.md:145-155, README.md:275-290

Summary

The Bank Integration Adapters provide a flexible and scalable way to aggregate financial data. By supporting both programmatic APIs (Plaid, TrueLayer, Kraken) and sophisticated CSV processing, the application ensures comprehensive coverage across different types of financial institutions while maintaining data integrity through deterministic deduplication and standardized normalization logic.

Sources: BANK_INTEGRATION_GUIDE.md:175-185, README.md:40-55