# RTGS System to DBIS Nostro/Vostro API Mapping

## Overview

This document provides patterns for mapping local RTGS (Real-Time Gross Settlement) systems to the DBIS Nostro/Vostro API.

## Common RTGS Patterns

### Pattern 1: REST API Integration

Many modern RTGS systems expose REST APIs:

```typescript
// RTGS API call
const rtgsTransfer = {
  fromAccount: "ACC123",
  toAccount: "ACC456",
  amount: 1000.00,
  currency: "USD",
  valueDate: "2024-01-15",
  reference: "REF123"
};

// Map to DBIS API
const dbisTransfer = {
  fromAccountId: rtgsTransfer.fromAccount,
  toAccountId: rtgsTransfer.toAccount,
  amount: rtgsTransfer.amount.toString(),
  currency: rtgsTransfer.currency,
  valueDate: rtgsTransfer.valueDate,
  reference: rtgsTransfer.reference
};
```

### Pattern 2: Database Integration

For RTGS systems with direct database access:

```sql
-- RTGS Database Query
SELECT 
  transaction_id,
  debit_account,
  credit_account,
  amount,
  currency,
  value_date,
  reference
FROM rtgs_transactions
WHERE status = 'PENDING';

-- Map to DBIS API request
```

### Pattern 3: Message Queue Integration

For RTGS systems using message queues (Kafka, RabbitMQ, etc.):

```typescript
// Consume from RTGS queue
consumer.on('message', (rtgsMessage) => {
  const transfer = mapRtgstoDbis(rtgsMessage);
  await nostroVostroService.createTransfer(transfer);
});
```

## Generic RTGS Adapter Template

```typescript
import { BasePluginAdapter } from './generic-adapter';

export class GenericRtgAdapter extends BasePluginAdapter {
  constructor(config: Record<string, unknown> = {}) {
    super('GenericRTGS', '1.0.0', config);
  }

  mapTransfer(internalData: unknown): TransferCreateRequest {
    const rtgsTx = internalData as {
      fromAccount: string;
      toAccount: string;
      amount: number;
      currency: string;
      valueDate: string;
      reference?: string;
    };

    return {
      fromAccountId: rtgsTx.fromAccount,
      toAccountId: rtgsTx.toAccount,
      amount: rtgsTx.amount.toString(),
      currency: rtgsTx.currency,
      valueDate: rtgsTx.valueDate,
      reference: rtgsTx.reference,
      metadata: {
        source: 'RTGS',
        rtgsSystem: this.config.rtgsSystemName,
      },
    };
  }

  // Implement other methods based on RTGS system capabilities
}
```

## Account Mapping

RTGS accounts typically map directly:

```typescript
mapAccount(internalData: unknown): AccountCreateRequest {
  const rtgsAccount = internalData as {
    accountNumber: string;
    customerId: string;
    correspondentId: string;
    currency: string;
    accountType: 'NOSTRO' | 'VOSTRO';
  };

  return {
    ownerParticipantId: rtgsAccount.customerId,
    counterpartyParticipantId: rtgsAccount.correspondentId,
    ibanOrLocalAccount: rtgsAccount.accountNumber,
    currency: rtgsAccount.currency,
    accountType: rtgsAccount.accountType,
  };
}
```

## Reconciliation

RTGS reconciliation typically involves:

1. **Statement Comparison**: Compare RTGS statements with DBIS transactions
2. **Balance Matching**: Match opening/closing balances
3. **Transaction Matching**: Match individual transactions by reference

```typescript
async reconcile(accountId: string, asOfDate: Date): Promise<{matched: number; breaks: unknown[]}> {
  // Get RTGS statement
  const rtgsStatement = await this.getRtgStatement(accountId, asOfDate);
  
  // Get DBIS transactions
  const dbisTransactions = await nostroVostroService.listTransfers({
    fromAccountId: accountId,
    valueDate: asOfDate,
  });

  // Match transactions
  const matched = this.matchTransactions(rtgsStatement, dbisTransactions);
  const breaks = this.findBreaks(rtgsStatement, dbisTransactions);

  return { matched, breaks };
}
```

## Best Practices

1. **Idempotency**: Use RTGS transaction IDs as idempotency keys
2. **Error Handling**: Map RTGS error codes to DBIS error codes
3. **Retry Logic**: Implement retry for transient RTGS failures
4. **Monitoring**: Monitor RTGS integration health
5. **Audit Trail**: Log all RTGS interactions

## Common RTGS Systems

### Fedwire (US)
- Format: Proprietary
- Integration: SWIFT or direct API

### TARGET2 (EU)
- Format: ISO 20022
- Integration: See ISO 20022 mapping guide

### CHAPS (UK)
- Format: SWIFT MT
- Integration: See SWIFT mapping guide

### CHIPS (US)
- Format: Proprietary
- Integration: Direct API or database

## Implementation Checklist

- [ ] Understand RTGS system architecture
- [ ] Identify integration method (API, DB, MQ)
- [ ] Map RTGS data structures to DBIS
- [ ] Implement adapter class
- [ ] Test with sandbox RTGS environment
- [ ] Implement error handling
- [ ] Set up monitoring
- [ ] Document RTGS-specific mappings