> 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/02-technology-stack.md).

# Technology Stack

## 1. Overview

The platform uses a **polyglot-but-centered-on-Java** stack optimized for banking integration, Finacle compatibility, and operational maturity across African markets.

Technology choices are guided by:

* Vendor and ecosystem fit (Finacle, ISO 20022)
* Hiring and support availability in target regions
* Proven high-volume transaction processing patterns
* Kubernetes-native deployment and observability

## 2. Stack Summary

| Layer                  | Technology                                                                                       | Version Policy                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Language (integration) | Java                                                                                             | LTS (21+)                                                          |
| Language (admin UI)    | TypeScript                                                                                       | Latest stable                                                      |
| Integration framework  | Apache Camel                                                                                     | Align with Spring Boot BOM                                         |
| Application framework  | Spring Boot                                                                                      | 3.x                                                                |
| Event streaming        | Apache Kafka                                                                                     | Confluent or Strimzi                                               |
| API gateway            | Kong / Apigee                                                                                    | Bank standard                                                      |
| Database               | **Database-agnostic RDBMS** — PostgreSQL (default), Oracle, SQL Server via `h2h-persistence-spi` | Per bank policy                                                    |
| Cache                  | Redis / Caffeine                                                                                 | In-memory + distributed invalidation                               |
| Search / trace         | OpenSearch                                                                                       | Transaction lookup                                                 |
| Secrets                | HashiCorp Vault                                                                                  | Keys, PGP, API secrets                                             |
| Containers             | Docker (optional)                                                                                | OCI images for Kubernetes profile only                             |
| Orchestration          | Kubernetes / OpenShift **or** standalone JVM / app server                                        | Profile A vs B/C — see [19](/docs/19-cloud-agnostic-deployment.md) |
| Legacy runtime         | Executable JAR, WAR (WebLogic, WebSphere, JBoss)                                                 | Banks without container platform                                   |
| Service mesh           | Istio / Linkerd                                                                                  | mTLS, traffic policy                                               |
| IaC                    | Terraform + Helm                                                                                 | Environment provisioning                                           |
| CI/CD                  | GitHub Actions / Jenkins                                                                         | Per bank standard                                                  |
| Observability          | OpenTelemetry, Prometheus, Grafana, Jaeger                                                       | End-to-end tracing                                                 |
| Identity               | Keycloak                                                                                         | SSO, RBAC, partner portal                                          |
| Workflow (human tasks) | Camunda                                                                                          | Approvals, exceptions                                              |
| Rules engine           | Drools / OPA                                                                                     | Optional policy-as-data                                            |

## 3. Language Selection by Component

### 3.1 Java — Primary Integration Language

**Used for:** Camel routes, Finacle wrappers, file/MQ adapters, transformation engines, config runtime, admin APIs.

**Rationale:**

* Finacle FCJ and FCUBS ecosystems are Java-oriented
* Apache Camel and Spring Boot mature integration patterns
* Strong libraries for SFTP, PGP, ISO 20022, JMS, Kafka
* Aligns with enterprise banking hiring pools

### 3.2 TypeScript — Admin and Partner Portals

**Used for:** Low-code admin SPA, partner self-service portal, mapping designer UI.

**Framework:** React with Next.js (or React + Vite per team preference).

**Rationale:**

* Rich ecosystem for form builders, data grids, and visual mapping tools
* Fast iteration on admin UX without touching integration JARs

### 3.3 Go — Optional Edge Services

**Used for:** High-performance gateway plugins, lightweight SFTP proxies (optional).

**Rationale:**

* Not required for MVP; adopt only if profiling shows Java gateway bottlenecks

## 4. Integration Framework — Apache Camel

Camel is the **orchestration engine** inside the runtime:

| Feature              | Camel Component / Pattern                                                          |
| -------------------- | ---------------------------------------------------------------------------------- |
| SFTP polling         | `camel-ftp`                                                                        |
| Kafka                | `camel-kafka`                                                                      |
| REST APIs            | `camel-platform-http`                                                              |
| Transformation       | `camel-jolt`, `camel-jsonata`, `camel-xslt`                                        |
| Job delay / schedule | `camel-kafka`, `camel-spring-rabbitmq` (delayed messages — **no in-process cron**) |
| Idempotency          | Custom component in `h2h-camel-core`                                               |
| Finacle calls        | Custom `finacle:` component (injects `CoreBankingIntegration`)                     |
| PGP                  | Custom `crypto:` component                                                         |
| Resilience           | Circuit breaker, retry, throttling EIP                                             |

See [Camel Integration Patterns](/docs/08-camel-integration-patterns.md) for detailed usage.

## 5. Application Framework — Spring Boot

Spring Boot provides:

* Dependency injection and auto-configuration for JAR modules
* JPA / JDBC for configuration store access
* Actuator health checks and metrics
* Security integration with Keycloak

Each capability JAR exposes `@AutoConfiguration` classes activated by properties (e.g. `h2h.modules.payments.enabled=true`).

## 6. Messaging — Apache Kafka / RabbitMQ

Kafka and RabbitMQ serve as the **event backbone**. **Topic and queue names are not hardcoded in application code** — they are defined in `event_channel_def` and resolved by `EventChannelResolver`. See [46 Database-Driven Events](/docs/46-database-driven-events.md).

| Logical `event_code`                 | Typical use           |
| ------------------------------------ | --------------------- |
| `PAYMENT_RECEIVED`, `PAYMENT_POSTED` | Transaction lifecycle |
| `AUDIT_EVENT`                        | Audit stream          |
| `CONFIG_PUBLISHED`                   | Config invalidation   |
| `JOB_SCHEDULE`, `JOB_EXECUTE`        | Broker-delayed jobs   |
| `DLQ_MESSAGE`                        | Dead letter           |
| `RECON_EXCEPTION`                    | Reconciliation        |

**Guarantees:** At-least-once delivery with idempotent consumers. Critical flows use transactional producers where required.

**Deployment:** Strimzi operator on Kubernetes or Confluent Platform per bank infrastructure standards.

### 6.1 Delayed Scheduling (Kafka and RabbitMQ)

Scheduled operations (EOD recon, statement generation, certificate expiry checks, etc.) use **broker-held delayed messages** — **not** in-process cron, Quartz, or `@Scheduled` timers.

| Broker       | Delay mechanism                                                                                               | Role                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| **RabbitMQ** | `x-delayed-message` exchange plugin; header `x-delay` (ms)                                                    | Preferred for precise, per-job delays |
| **Kafka**    | `h2h.jobs.schedule` topic + `executeAt` timestamp; `DelayedJobRelay` publishes to `h2h.jobs.execute` when due | Default when RabbitMQ is not deployed |

**Why broker delay (not cron):**

* Messages are **durable** in the broker — if the runtime is down at fire time, delivery occurs when consumers return (no missed tick).
* **No clustered Quartz** or pod-local timers — schedule state lives in the message + `job_schedule_state` table.
* HA via competing consumers on `h2h.jobs.execute`; idempotent `job_id` + `schedule_version` prevents duplicate runs.

**Module:** `h2h-job-scheduler` — `ScheduleBootstrap`, `DelayedJobPublisher`, `JobExecutor` (see [Extensibility Framework](/docs/14-extensibility-framework.md) §5).

**Topics / queues:**

| Name                | Purpose                                                     |
| ------------------- | ----------------------------------------------------------- |
| `h2h.jobs.schedule` | Kafka: schedule commands with `executeAt`                   |
| `h2h.jobs.execute`  | Job execution queue (Kafka topic or RabbitMQ queue)         |
| `h2h.jobs.delayed`  | RabbitMQ delayed exchange (when RabbitMQ backbone selected) |

Cut-off windows (`cutoff_schedule`) and SFTP poll intervals remain **configuration metadata** — they are not in-process cron jobs.

## 7. Data Stores

### 7.1 Relational Database — Configuration and Operational Data (vendor-agnostic)

All application persistence goes through **`h2h-persistence-spi`**. The bank deploys one supported RDBMS; **the same JARs** run on any supported vendor.

| Data                                  | Store                      |
| ------------------------------------- | -------------------------- |
| Partner profiles                      | RDBMS (config schema)      |
| Route templates, transforms, rules    | RDBMS                      |
| Config versions and audit             | RDBMS                      |
| Idempotency keys (optional)           | RDBMS or Redis             |
| Transaction metadata index            | RDBMS                      |
| File registry, payment batches, recon | RDBMS (transaction schema) |

| Vendor         | Role                                                  |
| -------------- | ----------------------------------------------------- |
| **PostgreSQL** | Default for development, CI, and reference production |
| **Oracle**     | Enterprise banking deployments                        |
| **SQL Server** | Alternative per bank infrastructure policy            |

See [45 Database-Agnostic Persistence](/docs/45-database-agnostic-persistence.md).

### 7.2 Object Storage — File Staging

MinIO or S3-compatible storage for:

* Inbound/outbound file archives
* Large file staging before processing
* Compliance retention

### 7.3 OpenSearch — Search and Analytics

* Full-text transaction search for operations
* Log aggregation (optional if centralized logging exists)

## 8. API Gateway

| Function                    | Implementation           |
| --------------------------- | ------------------------ |
| External REST/SOAP exposure | Kong or Apigee           |
| Authentication              | API keys, OAuth2, mTLS   |
| Rate limiting               | Per partner tier         |
| Request logging             | Correlation ID injection |

Internal Camel routes handle business logic; the gateway handles perimeter concerns only.

## 9. Security Infrastructure

| Concern               | Tool                                 |
| --------------------- | ------------------------------------ |
| Secrets management    | HashiCorp Vault                      |
| PGP keys              | Vault transit or dedicated key store |
| TLS certificates      | cert-manager on Kubernetes           |
| Identity and RBAC     | Keycloak                             |
| Policy enforcement    | OPA (optional)                       |
| mTLS between services | Istio / Linkerd                      |

## 10. Observability

| Signal              | Tool                                 |
| ------------------- | ------------------------------------ |
| Metrics             | Prometheus + Micrometer              |
| Dashboards          | Grafana                              |
| Distributed tracing | OpenTelemetry → Jaeger               |
| Structured logging  | JSON logs with correlation ID        |
| Alerting            | Alertmanager / PagerDuty integration |

**Mandatory trace context:** Every inbound message receives `X-Correlation-Id` (or generates one) propagated through Camel exchanges, Kafka headers, and Finacle calls.

## 11. Low-Code and Workflow

| Capability                       | Tool                                                        |
| -------------------------------- | ----------------------------------------------------------- |
| Admin UI                         | Next.js / React                                             |
| Human approval workflows         | Camunda                                                     |
| Email / SMS / push notifications | `h2h-notification-*` SPI (SES, Twilio, Africa's Talking, …) |
| Business rules (optional)        | Drools decision tables                                      |
| Policy rules (optional)          | Open Policy Agent                                           |
| Dashboards                       | Grafana + custom ops portal                                 |

## 12. Build and Artifact Management

| Tool                         | Purpose                                 |
| ---------------------------- | --------------------------------------- |
| Maven                        | Multi-module build, JAR publishing      |
| Internal Nexus / Artifactory | JAR artifact repository                 |
| `h2h-bom`                    | Bill of Materials for version alignment |
| Docker                       | Runtime image packaging                 |
| Helm                         | Kubernetes deployment charts            |

## 13. Testing Tools

| Layer              | Tool                                           |
| ------------------ | ---------------------------------------------- |
| Unit tests         | JUnit 5, Mockito                               |
| Camel route tests  | Camel Test Kit                                 |
| Integration tests  | Testcontainers (PostgreSQL, Kafka, SFTP)       |
| Contract tests     | Spring Cloud Contract or Pact                  |
| Architecture tests | ArchUnit (enforce no hardcoded partner config) |
| Load tests         | Gatling or k6                                  |

## 14. Build vs Buy Considerations

| Component                     | Recommendation                                                          |
| ----------------------------- | ----------------------------------------------------------------------- |
| Integration engine            | **Build** on Apache Camel (full control, Finacle fit)                   |
| API gateway                   | **Buy/deploy** Kong or Apigee                                           |
| Identity                      | **Deploy** Keycloak                                                     |
| ESB suite (MuleSoft, IBM ACE) | **Not recommended** as primary — adds cost, less modular JAR control    |
| iPaaS low-code                | **Not recommended** for payment hot path — use DB-driven config instead |

## 15. Version Management

All internal JAR versions are managed through `h2h-bom`:

```xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.heirs.h2h</groupId>
      <artifactId>h2h-bom</artifactId>
      <version>1.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```

Runtime `pom.xml` imports the BOM and declares only required capability modules.

## 16. Extensibility Stack

| Capability                  | Technology                                                                  |
| --------------------------- | --------------------------------------------------------------------------- |
| Custom metadata             | EAV + JSON extension entities (config DB)                                   |
| Scripts                     | Groovy / GraalVM JS / JSONata via `h2h-script-engine`                       |
| Scheduled jobs              | Broker delay (Kafka / RabbitMQ) via `h2h-job-scheduler` — **no cron**       |
| Database portability        | JPA + jOOQ via `h2h-persistence-spi` — **application is database-agnostic** |
| Plugins                     | Java SPI + Spring auto-config (`h2h-extension-api`)                         |
| Webhooks                    | Kafka → HTTP dispatcher (`h2h-webhook-dispatcher`)                          |
| File management             | SFTP + S3 via `h2h-file-management` (`FileStore` SPI)                       |
| Execution context           | `H2hContext` via `h2h-context`                                              |
| Observability               | OpenTelemetry + Micrometer via `h2h-observability`                          |
| Cross-library customization | `CustomizationProfile` via `h2h-extension-kernel`                           |

See [Extensibility Framework](/docs/14-extensibility-framework.md), [Universal Library Extensibility](/docs/20-universal-library-extensibility.md), [File Management System](/docs/15-file-management-system.md), [Security Library](/docs/16-security-library.md), [Monitoring and Logging](/docs/17-monitoring-and-logging.md), [Execution Context](/docs/18-execution-context.md), and [Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md) for full details.

## 17. Related Documents

* [Modular JAR Architecture](/docs/03-modular-jar-architecture.md)
* [Repository Structure](/docs/11-repository-structure.md)
* [Security and Compliance](/docs/09-security-and-compliance.md)
* [Extensibility Framework](/docs/14-extensibility-framework.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/02-technology-stack.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.