Data Model
Complete guide to the fourbics Client's data model, entity relationships, and data flow patterns.
This document provides a conceptual overview of the fourbics Client's data model, including entity relationships and how data flows through the system.
Entity Overview
The client manages EBICS-related entities organized in a hierarchical structure:
┌──────────────────────────────────────────────────────────────────────────────┐
│ ENTITY HIERARCHY │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Tenant (Root) │
│ ├── Bank Host (EBICS Server) │
│ │ └── Bank Keys (Bank's Public Keys) │
│ │ │
│ ├── Bank Connection (Connection to Bank) │
│ │ ├── EBICS User (EBICS Identity) │
│ │ │ ├── Key Pairs (User's Cryptographic Keys) │
│ │ │ ├── Permissions (Order Type Permissions) │
│ │ │ └── Transactions (Protocol Transactions) │
│ │ │ ├── Segments (Transaction Segments) │
│ │ │ ├── Files (Associated Files) │
│ │ │ └── Events (Audit Trail) │
│ │ │ │
│ │ └── Accounts (Bank Accounts) │
│ │ │
│ ├── Orders (Business Orders) │
│ │ └── Signatures (Order Signatures) │
│ │ │
│ └── VEU Items (Distributed Signature Items) │
│ └── VEU Signers (Individual Signers) │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Multi-Tenancy
All EBICS entities implement complete tenant isolation:
┌──────────────────────────────────────────────────────────────────────────────┐
│ MULTI-TENANCY MODEL │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ User │
│ ├── Can belong to multiple tenants │
│ ├── Has a current active tenant │
│ ├── Has a role within each tenant (Owner, Admin, Viewer) │
│ └── Can have fine-grained access to specific EBICS users │
│ │
│ Tenant │
│ ├── Contains all EBICS-related data │
│ ├── Complete isolation from other tenants │
│ └── All queries automatically scoped │
│ │
│ 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 │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Core Entities
Bank Host
Represents a bank's EBICS server. Contains:
- Host identifier (provided by bank)
- Server URL
- Protocol version (H003, H004, H005, H006)
- BTF support flag
- Test/production indicator
Relationships:
- Belongs to a Tenant
- Has many Bank Connections
- Has many Bank Keys
Bank Connection
Represents a connection to a specific bank partner. Contains:
- Partner identifier (provided by bank)
- Display name
- Available order types (synced from bank)
Relationships:
- Belongs to a Tenant
- Belongs to a Bank Host
- Has many EBICS Users
- Has many Accounts
EBICS User
Represents an EBICS user identity at a bank. Contains:
- User identifier (provided by bank)
- Optional system identifier
- User status (see below)
- Signature class (E, A, B, T)
- Cached permissions
User Status Values:
| Status | Description |
|---|---|
| NEW | Just created, no keys generated |
| PARTLY_INITIALISED_INI | INI request sent |
| PARTLY_INITIALISED_HIA | HIA request sent |
| INITIALISED | Awaiting bank activation |
| READY | Fully operational |
| SUSPENDED | Temporarily suspended |
| LOCKED | Permanently locked |
Relationships:
- Belongs to a Tenant
- Belongs to a Bank Connection
- Has many Key Pairs
- Has many Permissions
- Has many Transactions
- Has many Orders
Key Pair
Stores a user's cryptographic key pair. Contains:
- Key type (Signature, Authentication, Encryption)
- Key status (Pending, Submitted, Active, Expired, Revoked)
- Public key (plaintext)
- Private key (encrypted)
- Key hash for verification
- Optional certificate information
Key Status Values:
| Status | Description |
|---|---|
| PENDING | Generated, not yet submitted |
| SUBMITTED | Sent to bank |
| ACTIVE | In use |
| EXPIRED | Past validity period |
| REVOKED | Manually revoked |
Bank Key
Stores a bank's public key. Contains:
- Key type (Authentication, Encryption)
- Public key
- Key hash for verification
- Verification status and method
Account
Represents a bank account. Contains:
- IBAN
- Account number (national format)
- Bank code
- Account holder name (from bank)
- Currency
Permission
Defines what order types a user can execute. Contains:
- Order type code
- Optional account restriction
- Authorization level (E, A, B, T)
- Optional amount limits
Transaction Entities
Transaction
Represents an EBICS protocol transaction. Contains:
- Bank-assigned transaction ID
- Direction (Upload, Download)
- Current phase
- Order type or BTF parameters
- Segment tracking
- Recovery information
Transaction Phases:
| Phase | Description |
|---|---|
| INITIALISATION | Phase 1 - Initial request |
| TRANSFER | Phase 2 - Data segments |
| RECEIPT | Phase 3 - Acknowledgment |
| COMPLETED | Successfully finished |
| FAILED | Recoverable failure |
| ABORTED | Unrecoverable failure |
Transaction Segment
Individual segment in a multi-segment transaction. Contains:
- Segment number
- Last segment flag
- Status (Pending, Sent, Received, Acknowledged)
- Checksum for integrity
- Retry count
Transaction Event
Audit trail for transaction state changes. Contains:
- Event type
- Event context data
- Timestamp
- Sequence number
Event Types:
- INITIALISED
- TRANSFER_STARTED
- SEGMENT_SENT
- SEGMENT_RECEIVED
- RECEIPT_SENT
- COMPLETED
- FAILED
- RECOVERY_STARTED
- ABORTED
Order Entities
Order
Represents a business order. Contains:
- Bank-assigned order ID
- Order type
- Status
- Signature requirements
- Content hash and size
Order Status Values:
| Status | Description |
|---|---|
| DRAFT | Being prepared |
| PENDING_SIGNATURE | Awaiting signatures |
| SIGNED | All signatures collected |
| SUBMITTED | Sent to bank |
| PROCESSING | Bank processing |
| COMPLETED | Successfully processed |
| REJECTED | Bank rejected |
| CANCELLED | User cancelled |
Order Signature
Individual signature on an order. Contains:
- Signer information
- Signature class
- Signed hash
- Timestamp
VEU Entities
VEU Item
Distributed Electronic Signature item from bank. Contains:
- Bank's order ID
- Order type
- Signature status (collected vs required)
- Amount and currency
- Originator information
- Expiration time
VEU Status Values:
| Status | Description |
|---|---|
| PENDING | Awaiting signatures |
| SIGNED | Fully signed |
| EXECUTED | Bank executed |
| CANCELLED | Cancelled |
| EXPIRED | Timed out |
VEU Signer
Individual signer on a VEU item. Contains:
- Signer identification
- Authorization level
- Signature timestamp
Entity Relationship Diagram
┌──────────────────────────────────────────────────────────────────────────────┐
│ ENTITY RELATIONSHIP DIAGRAM │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌─────────────────────┐ │
│ │ Tenant │─────────│ Bank Host │ │
│ └────────────┘ 1:N │ └─ Bank Keys │ │
│ │ └─────────────────────┘ │
│ │ 1:N │ │
│ ▼ │ 1:N │
│ ┌─────────────────────┐ ▼ │
│ │ Bank Connection │◄────────┘ │
│ └─────────────────────┘ │
│ │ │
│ ├─────────────────────────────────────┐ │
│ │ 1:N │ 1:N │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ EBICS User │ │ Account │ │
│ └─────────────┘ └─────────────┘ │
│ │ │ │
│ ├──────────────┬──────────────┐ │ │
│ │ 1:N │ 1:N │ 1:N │ │
│ ▼ ▼ ▼ │ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ Key Pair │ │ Order │ │Transaction│ │ │
│ └───────────┘ └───────────┘ └───────────┘ │ │
│ │ │ │ │
│ │ 1:N │ 1:N │ │
│ ▼ ▼ │ │
│ ┌────────────┐ ┌──────────┐ │ │
│ │ Signature │ │ Segment │ │ │
│ └────────────┘ │ File │ │ │
│ │ Event │ │ │
│ └──────────┘ │ │
│ │ │
│ ┌─────────────────────────────────────────┐ │ │
│ │ Permission │◄┘ │
│ │ (links EBICS User ↔ Account) │ │
│ └─────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────┐ │
│ │ VEU Item │ │
│ │ └─ VEU Signer │ │
│ └─────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Data Flow Examples
Payment Order Submission
1. User creates Order (DRAFT)
└─ Specifies order type, content, required signatures
2. System checks Permissions
└─ Validates user can execute this order type
└─ Validates amount within limits (if applicable)
3. First signer adds Signature
└─ Uses their Signature key (Key Pair)
└─ Order status: PENDING_SIGNATURE (if more signatures needed)
4. Additional signers add Signatures (if required)
└─ Order status: SIGNED (when all signatures collected)
5. System creates Transaction (UPLOAD)
└─ Creates File with order content
└─ Initiates EBICS protocol
6. Transaction progresses through phases
└─ INITIALISATION → TRANSFER → COMPLETED
└─ Transaction Events record each state change
7. Order status updated
└─ SUBMITTED → PROCESSING → COMPLETED
Statement Download
1. User requests statement download
└─ Specifies order type and date range
2. System creates Transaction (DOWNLOAD)
└─ Direction: DOWNLOAD
3. Transaction executes
└─ INITIALISATION: Request sent, first segment received
└─ TRANSFER: Remaining segments fetched (if multi-segment)
└─ RECEIPT: Acknowledgment sent
4. Data processed
└─ Decrypted, decompressed
└─ File created with statement content
5. Statement available for viewing/export
Next Steps
- Architecture - Service layer organization
- Protocol - EBICS message structures
- Cryptography - Key management