Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
224
docs/architecture.md
Normal file
224
docs/architecture.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user