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`