225 lines
5.4 KiB
Markdown
225 lines
5.4 KiB
Markdown
# 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`
|