Banking GraphQL Server Proxy

A GraphQL server for banking operations built with GraphQL Yoga 5.x, following enterprise-grade patterns and best practices.

Tech Stack

• Runtime: Node.js 22
• Language: TypeScript 5.3+
• GraphQL Server: GraphQL Yoga 5.x
• Schema Tools: @graphql-tools/schema
• Development: tsx with hot reload

Quick Start

Install dependencies:

npm install

Run in development mode:

npm run dev

Build for production:

npm run build

Start production server:

npm start

Development

The server will start on port 4000 by default. You can access:

• GraphiQL Interface: http://localhost:4000/graphql
• GraphQL Endpoint: http://localhost:4000/graphql
• Health Check: http://localhost:4000/_healthcheck

GraphQL Schema

The banking schema is defined explicitly in schema.graphql with comprehensive type definitions extracted from banking-schema.json:

Important: The BankingBalance type includes all 32 fields from the original schema, including:

• Float balances: totalBalance, realBalance, lockedRealBalance, vaultBalance, cashierBalance
• Money objects: totalBalanceMoney, realBalanceMoney, lockedRealBalanceMoney, etc.
• lockedMethodBalances: Array of BankingMethodBalance for locked funds by payment method

Queries

• banking - Root entry point for all banking operations

Mutations (14 operations)

• bankingCancelWithdraw - Cancel a pending withdrawal
• bankingSubmitWithdraw - Submit withdrawal request
• bankingSubmitCryptoWithdraw - Submit cryptocurrency withdrawal
• bankingSubmitExchangeTransfer - Exchange between currencies
• bankingStartPaymentSession - Start payment session
• bankingSubmitFiatDeposit - Submit fiat deposit
• bankingSubmitFiatWithdraw - Submit fiat withdrawal
• bankingDeleteFiatAccount - Delete fiat account
• bankingSubmitPaymentProof - Submit payment proof
• bankingGetEncryptionScriptUrl - Get encryption script URL
• bankingBitlipaTopup - Bitlipa topup operation
• bankingLabTransferOut - Lab transfer out
• bankingSubmitVaultDeposit - Submit vault deposit
• bankingSubmitVaultWithdraw - Submit vault withdrawal

Subscriptions (5 real-time events)

• bankingMyDepositAdded - New deposit notification
• bankingMyDepositChanged - Deposit update notification
• bankingMyWithdrawAdded - New withdrawal notification
• bankingMyWithdrawChanged - Withdrawal update notification
• sportsbetNewGraphqlUpdateStatsWithdraws - Withdrawal stats update

Relay-Style Pagination

This service implements Relay-style cursor-based pagination for ALL list fields following the Relay Cursor Connections Specification.

Paginated Fields

All of these fields return Connection types with edges and nodes:

• myBalances → BankingBalanceConnection
• myAllBalances → BankingBalanceConnection
• myDeposits → BankingDepositConnection
• myWithdraws → BankingWithdrawConnection
• myTransactions → BankingTransactionConnection

Pagination Arguments

All paginated fields support these arguments:

• first: Int - Get first N items (forward pagination)
• after: String - Cursor to start from (forward pagination)
• last: Int - Get last N items (backward pagination)
• before: String - Cursor to end at (backward pagination)

Connection Response Structure

type Connection {
  edges: [Edge!]!      # List of edges containing cursor + node
  pageInfo: PageInfo!  # Pagination metadata
  totalCount: Int!     # Total number of items
}

type Edge {
  cursor: String!      # Opaque cursor for this item
  node: Item!          # The actual data item
}

type PageInfo {
  hasNextPage: Boolean!        # More items after endCursor?
  hasPreviousPage: Boolean!    # More items before startCursor?
  startCursor: String          # Cursor of first edge
  endCursor: String            # Cursor of last edge
}

Example Query (Basic)

query GetBanking {
  banking {
    id
    myBalances {
      currency
      available
      locked
      total
    }
    depositAndWithdrawLimits {
      minDeposit
      maxDeposit
      minWithdraw
      maxWithdraw
    }
    canUserWithdraw
    hasAnyTransactions
  }
}

Example Query (With Pagination)

query GetBankingWithPagination {
  banking {
    id

    # Get first 5 balances with edges and nodes
    myBalances(first: 5) {
      edges {
        cursor
        node {
          id
          currency
          totalBalance
          realBalance
          lockedRealBalance

          # Money objects
          totalBalanceMoney {
            amount
            currency
          }

          # Locked method balances
          lockedMethodBalances {
            method
            money {
              amount
              currency
            }
            targetCurrency
          }
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
    }

    # Get first 10 deposits
    myDeposits(first: 10) {
      edges {
        cursor
        node {
          id
          amount
          currency
          status
          createTime
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      totalCount
    }
  }
}

# Get next page using endCursor from previous query
query GetNextPage {
  banking {
    myDeposits(first: 10, after: "YXJyYXljb25uZWN0aW9uOjk=") {
      edges {
        cursor
        node {
          id
          amount
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Example Mutation

mutation SubmitWithdraw {
  bankingSubmitWithdraw(amount: 100.50, currency: "USD") {
    withdrawId
    success
    message
  }
}

Architecture

This project follows the patterns documented in PROJECT_GUIDELINES.md:

Code Style

• ✅ Arrow functions only - All functions use arrow syntax
• ✅ Async/await - No promise chains, consistent async patterns
• ✅ No errors field in responses - GraphQL framework handles errors
• ✅ Type safety - Full TypeScript types throughout

Project Structure

src/
├── index.ts              # Server entry point with GraphQL Yoga
├── resolvers.ts          # GraphQL resolvers (queries & mutations)
├── mocks.ts              # Mock data generators
└── utils/
    └── context.ts        # GraphQL context extraction

Key Features

• GraphQL Yoga 5.x - Modern, lightweight GraphQL server
• Type-safe resolvers - Full TypeScript support
• Health check endpoint - For load balancers and orchestrators
• Graceful shutdown - Handles SIGTERM/SIGINT signals
• CORS enabled - Configured for cross-origin requests
• GraphiQL interface - Built-in GraphQL playground

Environment Variables

Optional:

• SERVICE_PORT - Server port (default: 4000)

NPM Scripts

• npm run dev - Start development server with tsx hot reload
• npm run build - Compile TypeScript to JavaScript
• npm run compile - Alias for build
• npm start - Run compiled server
• npm run typecheck - Run TypeScript type checking

Guidelines

This codebase follows strict architectural guidelines:

1. Read PROJECT_GUIDELINES.md before making changes
2. Read AGENTS.md for functional programming patterns
3. Use arrow functions exclusively
4. Never include errors field in resolver responses
5. Use async/await throughout
6. Follow emoji logging conventions (🚀 ✅ 🔄 ❌ ⚠️)

Current Status

This is a working mock implementation. All mutations and queries return mock data. To integrate with a real banking backend:

1. Replace mock responses in src/mocks.ts with actual API calls
2. Add authentication/authorization logic in src/utils/context.ts
3. Implement caching layer (Redis recommended per PROJECT_GUIDELINES.md)
4. Add proper error handling and validation
5. Configure environment variables for external APIs

License

ISC