> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/01-architecture-overview.md).

# Architecture Overview

## 1. Introduction

The Bank operates across **20+ African countries** with a standardized **Finacle** core banking system. Corporate and institutional clients require direct system-to-system integration for automated financial operations — payments, collections, statements, reconciliation, and treasury reporting.

This document defines the target architecture for the **Heirs H2H Integration Platform**: a standardized, scalable, and secure framework that replaces fragmented file drops, ad-hoc APIs, and manual processes with **straight-through processing (STP)** across all markets.

## 2. Strategic Objectives

| Objective                | Description                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| Standardization          | One H2H capability deployed consistently across all Finacle markets                |
| Partner enablement       | Fast, repeatable onboarding for corporates, fintechs, and ecosystem partners       |
| High-volume processing   | Bulk payments, collections, and statements at scale                                |
| STP                      | End-to-end automation with minimal manual intervention                             |
| Security & compliance    | Encryption, access control, and immutable audit                                    |
| Operational resilience   | High availability, guaranteed delivery, exception management                       |
| Centralized governance   | Global policies with distributed regional execution                                |
| **Database portability** | Same JARs on PostgreSQL, Oracle, or SQL Server — bank chooses RDBMS at deploy time |

## 3. Challenges Addressed

* Lack of a standardized H2H framework across countries
* Fragmented integration approaches (files, APIs, manual processes)
* Slow partner onboarding dependent on centralized engineering teams
* Limited scalability for bulk and high-volume transaction processing
* Inconsistent security, monitoring, and reconciliation
* Difficulty evolving integrations without full application redeployments

## 4. Solution Scope

The platform covers end-to-end H2H integration:

| Capability               | Description                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------- |
| H2H Gateway              | Secure entry via **SFTP**, **HTTP** (REST/SOAP), **WebSocket**, and **message queues** |
| Integration layer        | Routing, transformation, orchestration (Apache Camel)                                  |
| Finacle adapters         | Native FCJ and FCUBS integration behind a unified abstraction                          |
| Secure file transfer     | SFTP with PGP encryption/decryption                                                    |
| Messaging backbone       | Event streaming and queues (Apache Kafka)                                              |
| Monitoring & audit       | Transaction lifecycle tracking, SLA monitoring                                         |
| Reconciliation           | Settlement matching and exception handling                                             |
| Multi-country deployment | Active-active regional architecture on Kubernetes                                      |

## 5. Layered Architecture

```mermaid
flowchart TB
  subgraph client [Client Layer]
    ERP[ERP Systems - SAP Oracle]
    Fintech[Fintech Partners]
    Corporate[Corporate Systems]
  end

  subgraph gateway [H2H Gateway Layer]
    SFTP[SFTP / PGP]
    HTTP[HTTP REST SOAP]
    WS[WebSocket]
    MQ[MQ / Kafka Ingress]
  end

  subgraph integration [Integration Layer]
    Camel[Apache Camel Runtime]
    Transform[Transformation Engine]
    Rules[Validation and Routing Rules]
    Events[Event Bus]
  end

  subgraph processing [Processing Layer]
    Validate[Payment Validation]
    Enrich[Enrichment]
    Idem[Idempotency and Dedup]
  end

  subgraph core [Core Banking Layer]
    Finacle[Finacle FCJ / FCUBS]
  end

  subgraph control [Control and Monitoring Layer]
    Admin[Low-Code Admin Portal]
    Config[Database-Driven Config]
    Monitor[Dashboards and Alerts]
    Recon[Reconciliation Workbench]
    Audit[Audit and Trace]
  end

  client --> gateway
  gateway --> integration
  integration --> processing
  processing --> core
  control --> integration
  integration --> Audit
```

### 5.1 Client Layer

External systems that initiate or consume H2H interactions:

* ERP systems (SAP, Oracle, Microsoft Dynamics)
* Corporate treasury and payroll systems
* Fintech and payment service providers
* Government and utility collection interfaces

### 5.2 H2H Gateway Layer

Protocol termination and perimeter security. Gateways are **thin and stateless**:

* Authenticate and authorize inbound connections
* Enforce rate limits and IP allowlists
* Decrypt PGP payloads (or delegate to integration layer)
* Route to the appropriate integration pipeline
* Terminate TLS and manage API keys / mTLS certificates

### 5.3 Integration Layer

The **Apache Camel** runtime orchestrates message flows:

* Ingest files, API requests, and queue messages
* Resolve partner configuration from the database
* Transform between formats (ISO 20022, MT940, CSV, XML, JSON)
* Apply validation and business routing rules
* Guarantee delivery with retries and dead-letter handling
* Emit audit and lifecycle events

### 5.4 Processing Layer

Business logic execution before core banking posting:

* Payment validation and enrichment
* Duplicate detection and idempotency
* Cut-off and calendar enforcement
* Exception classification (retryable vs manual)

### 5.5 Core Banking Layer

Core banking access is built on **`h2h-core-banking-api`** — a **vendor-neutral base library** (interface + canonical DTOs + provider SPI). **Finacle is one CBS provider type** that implements this contract; other core banking systems extend the same base library without changing payment or collection routes.

| Layer                 | Module                 | Role                                                          |
| --------------------- | ---------------------- | ------------------------------------------------------------- |
| **Base library**      | `h2h-core-banking-api` | `CoreBankingIntegration` — stable CBS contract for all routes |
| **Provider: Finacle** | `h2h-finacle-wrapper`  | `FinacleCoreBankingIntegration` — FCJ/FCUBS (Heirs default)   |
| **Provider: other**   | `h2h-cbs-{vendor}`     | Optional adapters for non-Finacle or mock/simulator           |

Route modules depend on the **base library only** — not Finacle SDK types. Provider selection is database-driven (`core_banking_provider_def`).

See [43 Core Banking Integration API](/docs/43-core-banking-integration-api.md).

### 5.6 Control and Monitoring Layer

Separate from the transaction hot path:

* Low-code admin portal for partner onboarding and configuration
* **Relational config store** (PostgreSQL, Oracle, or SQL Server) with draft/publish workflow — see [45 Database-Agnostic Persistence](/docs/45-database-agnostic-persistence.md)
* Operations dashboards (Grafana) and alerting
* Reconciliation workbench for analysts
* Immutable audit logs for compliance

## 6. Integration Modes

| Mode                      | Protocols                             | Use Cases                                                     |
| ------------------------- | ------------------------------------- | ------------------------------------------------------------- |
| File-based                | SFTP, PGP-encrypted files, signed URL | Bulk salary, vendor payments, large batch files               |
| **HTTP (sync)**           | REST/JSON, SOAP/XML                   | Real-time payments, status inquiry, synchronous accept/reject |
| **WebSocket (real-time)** | WSS + `h2h.v1` subprotocol            | Live payment status, ACK push, exception alerts               |
| Message-based             | Kafka, JMS/MQ, IBM MQ                 | Event-driven flows, async high-throughput pipelines           |

All modes converge into the same **canonical internal message model** before Finacle posting. See [47 Gateway Entry Points](/docs/47-gateway-entrypoints.md).

## 7. Core Capabilities

### 7.1 Message Transformation

Support for industry-standard and custom formats:

* ISO 20022 (pain, pacs, camt)
* SWIFT MT940 / MT942 (statements)
* CSV, fixed-width, XML, JSON
* Bank-internal canonical models

Transform **engines** live in JARs; transform **specifications** live in the database.

### 7.2 Reliability

* Guaranteed delivery with configurable retry policies
* Idempotency keys and duplicate detection windows
* Dead-letter queues for poison messages
* Asynchronous and batch processing with streaming splits

### 7.3 Traceability

Every transaction receives a **correlation ID** propagated across:

* Gateway ingress
* Camel exchanges
* Kafka events
* Finacle requests/responses
* ACK/NACK generation
* Audit store

### 7.4 Core Banking Integration

* `CoreBankingIntegration` interface (`h2h-core-banking-api`) — stable contract for all route modules
* Finacle adapter (`FinacleCoreBankingIntegration`) injected into `h2h-finacle-wrapper`
* Native FCJ API and FCUBS Web Services integration (Finacle-specific)
* Connection pooling and circuit breakers
* Extensible via `CoreBankingOperationProvider` SPI and alternate CBS adapter JARs

See [43 Core Banking Integration API](/docs/43-core-banking-integration-api.md).

## 8. Deployment Architecture

| Requirement       | Approach                                   |
| ----------------- | ------------------------------------------ |
| High availability | Active-active regional deployment          |
| Scalability       | Horizontal pod autoscaling on Kubernetes   |
| Hybrid deployment | Cloud and on-premises support              |
| Containerization  | Docker images on Kubernetes / OpenShift    |
| Configuration     | Externalized to database; secrets in Vault |

See [Multi-Country Deployment](/docs/07-multi-country-deployment.md) for regional topology.

## 9. Primary Use Cases

| Category           | Capabilities                                       |
| ------------------ | -------------------------------------------------- |
| Corporate Payments | Bulk salary, vendor payments, intra-bank transfers |
| Collections        | Bills, taxes, utilities, direct debits             |
| Statements         | Automated MT940 / ISO 20022 statement delivery     |
| Reconciliation     | Settlement matching, exception resolution          |
| Treasury           | Liquidity and FX reporting interfaces              |

## 10. Transaction Lifecycle

```mermaid
stateDiagram-v2
  [*] --> Ingested: File API or MQ received
  Ingested --> Validated: Schema and rules pass
  Validated --> Transformed: Mapped to canonical
  Transformed --> IdempotencyCheck: Duplicate check
  IdempotencyCheck --> Processing: New transaction
  IdempotencyCheck --> Duplicate: Rejected duplicate
  Processing --> Posted: Finacle success
  Processing --> Failed: Finacle error
  Failed --> Retry: Retryable error
  Failed --> Exception: Manual review
  Retry --> Processing: Retry attempt
  Posted --> Acknowledged: ACK sent to partner
  Exception --> Reprocessing: Ops action
  Reprocessing --> Processing
  Acknowledged --> [*]
  Duplicate --> [*]
```

## 11. Architectural Principles

### 11.1 Modular Composition

Capabilities are delivered as **versioned JAR modules** composed into a thin runtime shell. Update a wrapper JAR without rewriting the entire application.

### 11.2 Database-Driven Configuration

No hardcoded partner, country, or routing configuration. Admins manage behavior through the low-code portal; runtime resolves config at execution time.

### 11.3 Separation of Concerns

| Concern           | Owner                                                    |
| ----------------- | -------------------------------------------------------- |
| Protocol handling | Gateway and adapter JARs                                 |
| Orchestration     | Camel route JARs                                         |
| Business rules    | Database + rules engine                                  |
| Core banking      | `CoreBankingIntegration` interface + Finacle wrapper JAR |
| Governance        | Admin portal + audit                                     |

### 11.4 Fail-Safe Defaults

* Reject on validation failure (no silent drops)
* Idempotent processing by default
* All configuration changes require publish approval
* Secrets never stored in the configuration database

## 12. Non-Goals (Initial Phases)

* Replacing Finacle as the system of record
* Building a generic enterprise iPaaS for non-banking use cases
* Hot-pluggable production JAR loading without pod restart (deferred; rolling deploy is sufficient)

## 13. Related Documents

* [Technology Stack](/docs/02-technology-stack.md)
* [Modular JAR Architecture](/docs/03-modular-jar-architecture.md)
* [Database-Driven Configuration](/docs/04-database-driven-configuration.md)
* [Camel Integration Patterns](/docs/08-camel-integration-patterns.md)
* [Implementation Roadmap](/docs/10-implementation-roadmap.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://host2host.onibonje.com/docs/01-architecture-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.