Internal Architecture
Deep dive into the fourbics Client's internal architecture, service layers, and design patterns.
The fourbics Client follows a clean layered architecture designed for security, maintainability, and EBICS protocol compliance.
Layered Architecture
The client organizes functionality into distinct layers, each with specific responsibilities:
┌──────────────────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ User Interface & API Endpoints │
├──────────────────────────────────────────────────────────────────────────────┤
│ SERVICE LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Order │ │ Key │ │ VEU │ │ Admin │ │
│ │ Services │ │ Management │ │ Services │ │ Services │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
├──────────────────────────────────────────────────────────────────────────────┤
│ PROTOCOL LAYER │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Protocol Handlers (H003, H004, H005, H006) │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ XML │ │ XML │ │ Transaction │ │ Segment │ │
│ │ Builders │ │ Parsers │ │ Manager │ │ Manager │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
├──────────────────────────────────────────────────────────────────────────────┤
│ CRYPTOGRAPHIC LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Signature │ │ Encryption │ │ Hash │ │ Auth │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
├──────────────────────────────────────────────────────────────────────────────┤
│ INFRASTRUCTURE LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ HTTP │ │ TLS │ │ Storage │ │ Audit │ │
│ │ Client │ │ Validation │ │ Service │ │ Logger │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
├──────────────────────────────────────────────────────────────────────────────┤
│ DATA LAYER │
│ Entities & Persistence │
└──────────────────────────────────────────────────────────────────────────────┘
Layer Responsibilities
| Layer | Responsibility |
|---|---|
| Presentation | User interface components, API endpoints, request handling |
| Service | Business logic orchestration, workflow coordination |
| Protocol | EBICS protocol implementation, XML message handling |
| Cryptographic | Key management, signing, encryption, hashing |
| Infrastructure | HTTP communication, TLS, file storage, logging |
| Data | Entity management, persistence, multi-tenancy |
Protocol Handler Pattern
The client uses version-specific protocol handlers to support all EBICS versions while maintaining clean separation:
ProtocolVersionFactory
│
├─→ H006 Handler (EBICS V3.0.2)
│ └─ BTF support, A006 signatures, latest security
│
├─→ H005 Handler (EBICS V3.0)
│ └─ BTF support, A006 signatures
│
├─→ H004 Handler (EBICS V2.5)
│ └─ Legacy FUL/FDL, A005 signatures
│
└─→ H003 Handler (EBICS V2.4)
└─ Legacy FUL/FDL, A005 signatures, different namespace
Each handler implements the same interface, providing methods for:
- Key Management: INI, HIA, HPB, H3K requests
- Business Transactions: Upload and download initialization, transfer requests
- Admin Operations: HAA, HPD, HKD, HTD requests
- VEU Operations: Overview, detail, signature, and cancel requests
Transaction Flow
Upload Transaction (BTU/FUL)
┌──────────────────────────────────────────────────────────────────────────────┐
│ UPLOAD TRANSACTION FLOW │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. ORDER PREPARATION │
│ ─────────────────── │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Validate │ → │ Compress │ → │ Sign │ → │ Encrypt │ │
│ │ XML │ │ (DEFLATE)│ │ (A005/6) │ │(AES+RSA) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ 2. PHASE 1: INITIALIZATION │
│ ────────────────────────── │
│ Client Bank │
│ │ │ │
│ │ Initialization Request │ │
│ │ ├─ Order Type & BTF Parameters │ │
│ │ ├─ Encrypted Order Data │ │
│ │ ├─ Encrypted Signature │ │
│ │ └─ Authentication Signature │ │
│ │ ─────────────────────────────────>│ │
│ │ │ │
│ │ Response │ │
│ │ ├─ Transaction ID │ │
│ │ ├─ Number of Segments │ │
│ │ └─ Return Code │ │
│ │ <─────────────────────────────────│ │
│ │
│ 3. PHASE 2: TRANSFER (if multi-segment) │
│ ─────────────────────────────────────── │
│ │ │ │
│ │ Transfer Request (segment 2..N) │ │
│ │ ─────────────────────────────────>│ │
│ │ │ │
│ │ Acknowledgment │ │
│ │ <─────────────────────────────────│ │
│ │
│ 4. RESULT │
│ ──────── │
│ Order submitted to bank for processing │
│ May enter VEU queue if signature class requires co-signature │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Download Transaction (BTD/FDL)
┌──────────────────────────────────────────────────────────────────────────────┐
│ DOWNLOAD TRANSACTION FLOW │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. PHASE 1: INITIALIZATION │
│ ────────────────────────── │
│ Client Bank │
│ │ │ │
│ │ Initialization Request │ │
│ │ ├─ Order Type & BTF Parameters │ │
│ │ ├─ Date Range (optional) │ │
│ │ └─ Authentication Signature │ │
│ │ ─────────────────────────────────>│ │
│ │ │ │
│ │ Response │ │
│ │ ├─ Transaction ID │ │
│ │ ├─ Number of Segments │ │
│ │ ├─ First Data Segment │ │
│ │ └─ Return Code │ │
│ │ <─────────────────────────────────│ │
│ │
│ 2. PHASE 2: TRANSFER (if multi-segment) │
│ ─────────────────────────────────────── │
│ │ │ │
│ │ Transfer Request (segment 2..N) │ │
│ │ ─────────────────────────────────>│ │
│ │ │ │
│ │ Data Segment │ │
│ │ <─────────────────────────────────│ │
│ │
│ 3. PHASE 3: RECEIPT │
│ ────────────────── │
│ │ │ │
│ │ Receipt (positive/negative) │ │
│ │ ─────────────────────────────────>│ │
│ │ │ │
│ │ Final Response │ │
│ │ <─────────────────────────────────│ │
│ │
│ 4. DATA PROCESSING │
│ ───────────────── │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Decrypt │ → │Decompress│ → │ Verify │ → │ Parse │ │
│ │(AES+RSA) │ │ (DEFLATE)│ │ Sig │ │ XML │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Segment Management
EBICS limits each segment to 1 MB (1,048,576 bytes). Large orders are automatically split into multiple segments:
Large Order Data (e.g., 3.5 MB)
│
▼
┌────────────────────────────────────────────────────────────────┐
│ Segment Manager │
├────────────────────────────────────────────────────────────────┤
│ │
│ Split into segments: │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────┐ │
│ │ Segment 1 │ │ Segment 2 │ │ Segment 3 │ │ Seg 4 │ │
│ │ 1 MB │ │ 1 MB │ │ 1 MB │ │ 0.5MB │ │
│ │ last=false │ │ last=false │ │ last=false │ │last=T │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────┘ │
│ │
│ Each segment is tracked with: │
│ - Segment number (1-based) │
│ - Last segment flag │
│ - Status (pending, sent, acknowledged) │
│ - Checksum for integrity verification │
│ - Retry count for recovery │
│ │
└────────────────────────────────────────────────────────────────┘
Transaction State Machine
Transactions progress through well-defined states:
┌──────────────────────────────────────────────────────────────────────────────┐
│ TRANSACTION STATE MACHINE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ │
│ │ DRAFT │ │
│ └────┬────┘ │
│ │ submit │
│ ▼ │
│ ┌─────────────────┐ │
│ │ INITIALISATION │ │
│ └────────┬────────┘ │
│ │ │
│ ┌─────────────┼─────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ TRANSFER │ │ FAILED │ │ ABORTED │ │
│ └────┬─────┘ └──────────┘ └──────────┘ │
│ │ ▲ │
│ │ │ recovery failed │
│ │ │ │
│ ▼ │ │
│ ┌──────────┐ │ │
│ │ RECEIPT │────────┘ │
│ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │COMPLETED │ │
│ └──────────┘ │
│ │
│ Recovery: Failed transactions can be recovered up to a configurable │
│ maximum number of attempts. Unrecoverable transactions are marked ABORTED. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Multi-Tenancy
The client implements complete tenant isolation:
┌──────────────────────────────────────────────────────────────────────────────┐
│ MULTI-TENANCY MODEL │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Tenant (Organization) │
│ ├── Bank Hosts (EBICS servers) │
│ ├── Bank Connections (partner relationships) │
│ ├── EBICS Users (identities at banks) │
│ ├── Key Pairs (cryptographic keys) │
│ ├── Orders (business transactions) │
│ ├── Transactions (protocol transactions) │
│ └── All other EBICS-related data │
│ │
│ Isolation Guarantees: │
│ • All queries automatically scoped to current tenant │
│ • New records automatically assigned to current tenant │
│ • Cross-tenant data access prevented at the data layer │
│ • Fine-grained access control within tenants │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Error Handling & Recovery
Retry Strategy
The client implements exponential backoff with jitter for transient failures:
Attempt 1: Immediate
Attempt 2: 1 second + random jitter
Attempt 3: 2 seconds + random jitter
Attempt 4: 4 seconds + random jitter
Attempt 5: 8 seconds + random jitter
... up to maximum delay (60 seconds)
Transaction Recovery
Failed transactions can be recovered if the bank supports it:
- Check recovery support via HPD (bank parameters)
- Resume from last successful segment using stored Transaction ID
- Track recovery attempts (configurable maximum)
- Mark as ABORTED if recovery fails after maximum attempts
Audit Trail
Every significant action is recorded for compliance and debugging:
- Transaction Events: State changes, segment transfers, completions, failures
- Key Operations: Generation, submission, activation, revocation
- Order Actions: Creation, signing, submission, status changes
- Security Events: Authentication attempts, permission checks
Next Steps
- Protocol Details - Deep dive into EBICS protocol versions
- Cryptography - Cryptographic operations explained
- Data Model - Entity relationships and data flow