dbis_core-lite/docs/architecture.md

Architecture Documentation

System Overview

The DBIS Core Lite system is a Tier-1-grade payment processing system that connects an IBM 800 Terminal (web emulator) through core banking to ISO 20022 pacs.008/pacs.009 generation and raw TLS S2S transmission, with full reconciliation and settlement finality.

Architecture Layers

1. Terminal Layer (Web Emulator)

Purpose: Operator interface for payment initiation and monitoring

Components:

• Web-based 3270/TN5250 terminal emulator UI
• Operator authentication
• Payment initiation forms
• Status and reconciliation views

Key Principle: The terminal is never a payment engine - it is an operator interface only.

2. Terminal Access Gateway (TAC)

Purpose: Secure abstraction layer between terminal and services

Components:

• RESTful API endpoints
• Operator authentication (JWT)
• RBAC enforcement (Maker, Checker, Admin)
• Input validation and sanitization

Responsibilities:

• Normalize terminal input
• Enforce RBAC
• Prevent direct system calls
• Pass structured requests to Payments Orchestration Layer

3. Payments Orchestration Layer (POL)

Purpose: Business logic and workflow orchestration

Components:

• Payment state machine
• Dual control (Maker/Checker) enforcement
• Limit checks
• Workflow orchestration

Responsibilities:

• Receive payment intent from TAC
• Enforce dual control
• Trigger compliance screening
• Trigger ledger debit
• Trigger message generation
• Trigger transport delivery

4. Compliance & Sanctions Screening

Purpose: Pre-debit mandatory screening

Components:

• Sanctions list checker (OFAC/EU/UK)
• PEP checker
• Screening engine

Blocking Rule: No ledger debit occurs unless compliance status = PASS

5. Core Banking Ledger Interface

Purpose: Account posting abstraction

Components:

• Ledger adapter pattern
• Mock implementation (for development)
• Transaction posting logic

Responsibilities:

• Atomic transaction posting
• Reserve funds
• Generate internal transaction ID

Blocking Rule: ISO message creation is blocked unless ledger debit is successful

6. ISO 20022 Message Engine

Purpose: Generate ISO 20022 messages

Components:

• pacs.008 generator (Customer Credit Transfer)
• pacs.009 generator (FI-to-FI Transfer)
• UETR generator (UUID v4)
• XML validator

Responsibilities:

• Generate XML messages
• Validate XML structure
• Generate unique UETR per message

7. Raw TLS S2S Transport Layer

Purpose: Secure message delivery

Components:

• TLS client (TLS 1.2/1.3)
• Length-prefix framer (4-byte big-endian)
• Delivery manager (exactly-once)
• Retry manager

Configuration:

• IP: 172.67.157.88
• Port: 443
• SNI: devmindgroup.com
• Framing: 4-byte big-endian length prefix

8. Reconciliation Framework

Purpose: End-to-end transaction matching

Components:

• Multi-layer reconciliation matcher
• Daily reconciliation reports
• Exception handler

Reconciliation Layers:

1. Terminal intent vs ledger debit
2. Ledger debit vs ISO message
3. ISO message vs ACK
4. ACK vs settlement confirmation

9. Settlement Finality

Purpose: Track settlement status

Components:

• Settlement tracker
• Credit confirmation handler

Responsibilities:

• Track settlement status per transaction
• Accept credit confirmations
• Release ledger reserves upon finality
• Mark transactions as SETTLED

10. Audit & Logging

Purpose: Tamper-evident audit trail

Components:

• Structured logger (Winston)
• Audit logger (database)
• Retention manager

Retention: 7-10 years (configurable)

Data Flow

Operator Login
    ↓
Terminal Access Gateway (Authentication & RBAC)
    ↓
Payment Initiation (Maker)
    ↓
Payments Orchestration Layer
    ↓
Dual Control Check (Checker Approval Required)
    ↓
Compliance Screening
    ↓
Ledger Debit & Reserve
    ↓
ISO 20022 Message Generation
    ↓
Raw TLS S2S Transmission
    ↓
ACK/NACK Handling
    ↓
Settlement Finality Confirmation
    ↓
Reconciliation

Security Considerations

1. Authentication: JWT tokens with expiration
2. Authorization: RBAC with Maker/Checker separation
3. TLS: TLS 1.2/1.3 for all external communication
4. mTLS: Client certificates for receiver authentication
5. Input Validation: All inputs validated and sanitized
6. Audit Trail: Tamper-evident logging with checksums

Database Schema

See src/database/schema.sql for complete schema definition.

Key tables:

• operators - Terminal operators
• payments - Payment transactions
• ledger_postings - Core banking ledger records
• iso_messages - Generated ISO 20022 messages
• transport_sessions - TLS connection sessions
• ack_nack_logs - ACK/NACK responses
• settlement_records - Settlement finality tracking
• audit_logs - Tamper-evident audit trail
• reconciliation_runs - Daily reconciliation results

Configuration

See src/config/env.ts and src/config/receiver-config.ts for configuration details.

Environment variables:

• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - JWT signing secret
• RECEIVER_IP - Receiver IP address
• RECEIVER_PORT - Receiver port
• RECEIVER_SNI - Server Name Indication for TLS

Deployment

1. Install dependencies: npm install
2. Setup database: Run src/database/schema.sql
3. Configure environment: Set .env file
4. Build: npm run build
5. Start: npm start

For development: npm run dev