> 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/22-use-cases-and-solutions.md).

# Use Cases and Solutions Guide

## 1. Overview

This document maps **real H2H platform use cases** to the **problem**, **solution**, **modules involved**, and **documentation** that defines the fix. Use it as a practical index when onboarding stakeholders, writing proposals, or planning implementation.

**How to read each entry:**

| Field               | Meaning                             |
| ------------------- | ----------------------------------- |
| **Challenge**       | What the bank or partner needs      |
| **Solution**        | How the platform addresses it       |
| **Key modules**     | JARs / services involved            |
| **Runtime change?** | Whether a redeploy is needed        |
| **Docs**            | Where the design is fully explained |

***

## 2. Use Case Index

| #     | Use case                                           | Section                                         |
| ----- | -------------------------------------------------- | ----------------------------------------------- |
| UC-01 | Bulk salary payments via SFTP                      | [§3.1](#uc-01-bulk-salary-payments-via-sftp)    |
| UC-02 | Real-time vendor payment via API                   | [§3.2](#uc-02-real-time-vendor-payment-via-api) |
| UC-03 | Utility / bill collections                         | [§3.3](#uc-03-utility--bill-collections)        |
| UC-04 | Automated MT940 / ISO 20022 statements             | [§3.4](#uc-04-automated-statement-delivery)     |
| UC-05 | New corporate partner onboarding                   | [§3.5](#uc-05-new-corporate-partner-onboarding) |
| UC-06 | Roll out H2H to a second country                   | [§3.6](#uc-06-roll-out-to-a-second-country)     |
| UC-07 | Partner switches from SFTP to signed URL delivery  | [§3.7](#uc-07-signed-url-file-delivery)         |
| UC-08 | Country-specific regulatory field on every payment | [§3.8](#uc-08-custom-regulatory-field)          |
| UC-09 | Failed payment investigation and reprocess         | [§3.9](#uc-09-failed-payment-reprocess)         |
| UC-10 | Notify corporate ERP when payment posts            | [§3.10](#uc-10-erp-notification-after-payment)  |
| UC-11 | End-of-day reconciliation                          | [§3.11](#uc-11-end-of-day-reconciliation)       |
| UC-12 | Deploy on Oracle DB instead of PostgreSQL          | [§3.12](#uc-12-oracle-database-deployment)      |
| UC-13 | Deploy on AWS vs on-prem OpenShift                 | [§3.13](#uc-13-cloud-vs-on-prem-deployment)     |
| UC-14 | Custom validation without code deploy              | [§3.14](#uc-14-custom-validation-script)        |
| UC-15 | SLA breach alerting for slow processing            | [§3.15](#uc-15-sla-breach-alerting)             |
| UC-16 | SFTP certificate expiring soon                     | [§3.16](#uc-16-certificate-expiry-management)   |
| UC-17 | Duplicate file uploaded by partner                 | [§3.17](#uc-17-duplicate-file-detection)        |
| UC-18 | Large payment sent to manual approval              | [§3.18](#uc-18-manual-approval-workflow)        |
| UC-19 | Split file gateway and payment runtime             | [§3.19](#uc-19-split-services-deployment)       |
| UC-20 | Fintech partner API with HMAC signing              | [§3.20](#uc-20-fintech-api-with-hmac-signing)   |
| UC-21 | Update Finacle posting logic only                  | [§3.21](#uc-21-update-finacle-wrapper-only)     |
| UC-22 | Admin changes mapping without downtime             | [§3.22](#uc-22-mapping-change-without-downtime) |

***

## 3. Use Cases

### UC-01: Bulk salary payments via SFTP

|                     |                                                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Corporate client uploads encrypted CSV with thousands of salary payments; bank must decrypt, validate, post to Finacle, and return ACK — STP. |
| **Solution**        | SFTP poll → PGP decrypt → transform to canonical → idempotency check → split batch → Finacle post → generate ACK → deliver to partner outbox. |
| **Key modules**     | `h2h-file-management`, `h2h-security`, `h2h-payments-routes`, `h2h-finacle-wrapper`, `h2h-transform-core`, `h2h-ack-nack`, `h2h-camel-core`   |
| **Runtime change?** | **No** — partner profile, mapping, and route template published via admin.                                                                    |
| **Config**          | `integration_profile`, `route_template` BULK\_PAYMENT\_STP\_V1, `transform_spec`, `channel_config` (SFTP paths)                               |

**Flow:**

```mermaid
sequenceDiagram
  participant Corp as Corporate ERP
  participant SFTP as SFTP / File Mgmt
  participant Camel as Payment Route
  participant Finacle
  participant ACK as ACK Delivery

  Corp->>SFTP: Upload PAY_*.csv.pgp
  SFTP->>Camel: file-mgmt:poll → VERIFIED
  Camel->>Camel: decrypt, transform, idempotency
  Camel->>Finacle: post payments (split/stream)
  Finacle-->>Camel: success
  Camel->>ACK: ACK file → partner outbox
```

| Doc                                                                           | What it explains                        |
| ----------------------------------------------------------------------------- | --------------------------------------- |
| [01 Architecture Overview](/docs/01-architecture-overview.md)                 | STP lifecycle, layered design           |
| [08 Camel Integration Patterns](/docs/08-camel-integration-patterns.md)       | Route skeleton, splitter, idempotency   |
| [15 File Management System](/docs/15-file-management-system.md)               | SFTP poll, staging, guaranteed delivery |
| [16 Security Library](/docs/16-security-library.md)                           | PGP decrypt                             |
| [04 Database-Driven Configuration](/docs/04-database-driven-configuration.md) | Partner profile, route template         |

***

### UC-02: Real-time vendor payment via API

|                     |                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Fintech needs synchronous REST payment with idempotency key; immediate accept/reject response.                                      |
| **Solution**        | API gateway → Camel HTTP route → same pipeline as files → sync response with correlation ID; duplicate key returns previous result. |
| **Key modules**     | API gateway (Kong), `h2h-payments-routes`, `h2h-camel-core` (idempotency), `h2h-context`                                            |
| **Runtime change?** | **No** — API product and limits configured in admin.                                                                                |

| Doc                                                                     | What it explains                           |
| ----------------------------------------------------------------------- | ------------------------------------------ |
| [08 Camel Integration Patterns](/docs/08-camel-integration-patterns.md) | Correlation ID, idempotent receiver        |
| [18 Execution Context](/docs/18-execution-context.md)                   | `X-Correlation-Id`, idempotency in context |
| [05 Low-Code Admin Platform](/docs/05-low-code-admin-platform.md)       | API product catalog                        |
| [47 Gateway Entry Points](/docs/47-gateway-entrypoints.md)              | HTTP sync ingress                          |
| [10 Implementation Roadmap](/docs/10-implementation-roadmap.md)         | Phase 3 API channel                        |

***

### UC-02b: Real-time payment status via WebSocket

|                     |                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Fintech needs live payment status without polling HTTP; bank must push ACK when batch completes.                                                                           |
| **Solution**        | `channel_config` (`WEBSOCKET`) + `websocket_subscription` for `PAYMENT_POSTED`, `PAYMENT_FAILED` → partner receives push on WSS. Payment still submitted via HTTP or SFTP. |
| **Key modules**     | `h2h-websocket-ingress`, `h2h-event-extensions`, `h2h-security`                                                                                                            |
| **Runtime change?** | **No** — subscriptions configured in admin.                                                                                                                                |

| Doc                                                                 | What it explains                  |
| ------------------------------------------------------------------- | --------------------------------- |
| [47 Gateway Entry Points](/docs/47-gateway-entrypoints.md)          | WebSocket channel + subscriptions |
| [46 Database-Driven Events](/docs/46-database-driven-events.md)     | `event_code` push binding         |
| [39 API Gateway Architecture](/docs/39-api-gateway-architecture.md) | WSS security                      |

***

### UC-03: Utility / bill collections

|                     |                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Challenge**       | Inbound collection files from utility companies; validate debits and post collections to Finacle.                        |
| **Solution**        | Enable `h2h-collections-routes` module; assign collection route template and ISO/csv transform via integration profile.  |
| **Key modules**     | `h2h-collections-routes`, `h2h-transform-iso20022`, `h2h-finacle-wrapper`                                                |
| **Runtime change?** | **No** for config; **Yes** if collections module not yet in runtime `pom.xml` (one-time module enable + rolling deploy). |

| Doc                                                                 | What it explains          |
| ------------------------------------------------------------------- | ------------------------- |
| [01 Architecture Overview](/docs/01-architecture-overview.md)       | Collections use case      |
| [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.md) | Enable collections module |
| [10 Implementation Roadmap](/docs/10-implementation-roadmap.md)     | Phase 4 collections       |

***

### UC-04: Automated statement delivery

|                     |                                                                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Deliver MT940 or ISO 20022 camt.053 to corporate client daily after EOD.                                                                                                        |
| **Solution**        | Broker-delayed job (`job_def`) publishes to `h2h.jobs.execute` → statement route → Finacle inquiry → MT940 transform → deliver via SFTP or signed URL. Survives runtime outage. |
| **Key modules**     | `h2h-statements-routes`, `h2h-transform-mt940`, `h2h-job-scheduler`, `h2h-file-management`                                                                                      |
| **Runtime change?** | **No** — job definition and schedule published in admin.                                                                                                                        |

| Doc                                                                     | What it explains                          |
| ----------------------------------------------------------------------- | ----------------------------------------- |
| [15 File Management System](/docs/15-file-management-system.md)         | Outbound delivery, signed URL             |
| [14 Extensibility Framework](/docs/14-extensibility-framework.md)       | Broker-delayed scheduled jobs (`job_def`) |
| [08 Camel Integration Patterns](/docs/08-camel-integration-patterns.md) | Polling consumer, scheduling              |

***

### UC-05: New corporate partner onboarding

|                     |                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Onboard ACME Corp in 2 weeks without developer writing custom Java; test in sandbox then go live.       |
| **Solution**        | Partner wizard → channel config → assign route template + mappings → sandbox test → supervisor publish. |
| **Key modules**     | `h2h-admin-api`, `h2h-config-store`, `h2h-extension-kernel`                                             |
| **Runtime change?** | **No**                                                                                                  |

| Doc                                                                           | What it explains                                |
| ----------------------------------------------------------------------------- | ----------------------------------------------- |
| [05 Low-Code Admin Platform](/docs/05-low-code-admin-platform.md)             | Onboarding wizard, test harness, publish center |
| [06 Personas and RBAC](/docs/06-personas-and-rbac.md)                         | Onboarding officer vs supervisor roles          |
| [04 Database-Driven Configuration](/docs/04-database-driven-configuration.md) | Draft → publish workflow                        |
| [07 Multi-Country Deployment](/docs/07-multi-country-deployment.md)           | 4–6 week country onboarding target              |

***

### UC-06: Roll out to a second country

|                     |                                                                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Challenge**       | Nigeria is live; deploy same platform to Ghana with local holidays, CSV format, and Finacle endpoints — no code fork.                                        |
| **Solution**        | Import Ghana **country pack** (transforms, rules, calendars) → configure regional Finacle endpoints → enable country in Helm values → onboard pilot partner. |
| **Key modules**     | Same JARs everywhere; Ghana-specific rows in config DB                                                                                                       |
| **Runtime change?** | **No** for behavior; **Yes** for regional K8s infra if new cluster (Terraform + Helm).                                                                       |

| Doc                                                                               | What it explains                        |
| --------------------------------------------------------------------------------- | --------------------------------------- |
| [07 Multi-Country Deployment](/docs/07-multi-country-deployment.md)               | Country packs, regional topology        |
| [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md) | COUNTRY scope customization inheritance |
| [19 Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md)             | Regional Helm values                    |

***

### UC-07: Signed URL file delivery

|                     |                                                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Partner cannot use SFTP; wants HTTPS upload/download with time-limited links.                                                                      |
| **Solution**        | Publish `CustomizationProfile` with `deliveryMethod: SIGNED_URL`; API issues pre-signed PUT; partner uploads direct to S3; ACK via pre-signed GET. |
| **Key modules**     | `h2h-file-management` (`SignedUrlService`), `h2h-security`                                                                                         |
| **Runtime change?** | **No**                                                                                                                                             |

| Doc                                                                               | What it explains                             |
| --------------------------------------------------------------------------------- | -------------------------------------------- |
| [15 File Management System](/docs/15-file-management-system.md)                   | §6 Signed URL delivery, security controls    |
| [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md) | `FileManagementCustomization.deliveryMethod` |
| [16 Security Library](/docs/16-security-library.md)                               | HMAC alternative for API channel             |

***

### UC-08: Custom regulatory field

|                     |                                                                                                                                                      |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | CBN requires reporting reference on every Nigeria payment; field must appear in transform, Finacle post, logs, and ACK filename.                     |
| **Solution**        | Define `NG_CBN_REF` in `custom_attribute_def` → include in `CustomizationProfile` → available as `${custom.NG_CBN_REF}` everywhere via `H2hContext`. |
| **Key modules**     | `h2h-extension-kernel`, `h2h-context`, all libraries via cross-propagation                                                                           |
| **Runtime change?** | **No**                                                                                                                                               |

| Doc                                                                               | What it explains                         |
| --------------------------------------------------------------------------------- | ---------------------------------------- |
| [14 Extensibility Framework](/docs/14-extensibility-framework.md)                 | Custom attributes (EAV)                  |
| [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md) | §6.3 Custom attributes end-to-end flow   |
| [18 Execution Context](/docs/18-execution-context.md)                             | Custom attributes on context             |
| [17 Monitoring and Logging](/docs/17-monitoring-and-logging.md)                   | Additional log fields from customization |

***

### UC-09: Failed payment reprocess

|                     |                                                                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Finacle timeout caused 50 failed payments; ops must retry without duplicating successful ones.                                         |
| **Solution**        | Ops dashboard searches by `correlationId` / batch → retry single or bulk (supervisor approval) → idempotency prevents duplicate posts. |
| **Key modules**     | `h2h-admin-api`, `h2h-camel-core`, `h2h-observability`                                                                                 |
| **Runtime change?** | **No**                                                                                                                                 |

| Doc                                                                     | What it explains                   |
| ----------------------------------------------------------------------- | ---------------------------------- |
| [05 Low-Code Admin Platform](/docs/05-low-code-admin-platform.md)       | Operations dashboard, failed queue |
| [08 Camel Integration Patterns](/docs/08-camel-integration-patterns.md) | Idempotent receiver, DLQ           |
| [17 Monitoring and Logging](/docs/17-monitoring-and-logging.md)         | Transaction search, alerts         |
| [06 Personas and RBAC](/docs/06-personas-and-rbac.md)                   | OPS\_NOC permissions               |

***

### UC-10: ERP notification after payment

|                     |                                                                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Corporate ERP must receive HTTP callback when batch completes posting.                                                                                              |
| **Solution**        | Publish `event_subscription` for `event_code: PAYMENT_POSTED` → `handler_type: WEBHOOK` → partner ERP URL. Topic resolved from `event_channel_def`. No code deploy. |
| **Key modules**     | `h2h-event-extensions`, `h2h-webhook-dispatcher`, `h2h-observability`                                                                                               |
| **Runtime change?** | **No**                                                                                                                                                              |

| Doc                                                                                     | What it explains              |
| --------------------------------------------------------------------------------------- | ----------------------------- |
| [21 Event-Driven Runtime Extensibility](/docs/21-event-driven-runtime-extensibility.md) | Event subscriptions, webhooks |
| [14 Extensibility Framework](/docs/14-extensibility-framework.md)                       | Webhook subscriptions table   |
| [18 Execution Context](/docs/18-execution-context.md)                                   | `correlationId` on events     |

***

### UC-11: End-of-day reconciliation

|                     |                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Match bank postings against partner confirmation file; flag exceptions for analyst.                                       |
| **Solution**        | EOD job aggregates payments → recon engine matches on configurable keys → exceptions in workbench → analyst manual match. |
| **Key modules**     | `h2h-reconciliation`, `h2h-job-scheduler`, `h2h-admin-api`                                                                |
| **Runtime change?** | **No** for rules; recon **matching keys** in `recon_config` DB.                                                           |

| Doc                                                               | What it explains                |
| ----------------------------------------------------------------- | ------------------------------- |
| [05 Low-Code Admin Platform](/docs/05-low-code-admin-platform.md) | Reconciliation workbench        |
| [14 Extensibility Framework](/docs/14-extensibility-framework.md) | SQL task jobs for EOD aggregate |
| [01 Architecture Overview](/docs/01-architecture-overview.md)     | Reconciliation use case         |

***

### UC-12: Oracle database deployment

|                     |                                                                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Bank policy mandates Oracle; platform was developed against PostgreSQL.                                                       |
| **Solution**        | Set `h2h.persistence.vendor: oracle`; Flyway runs `oracle/` migrations; JPA dialect + `JsonColumnMapper` SPI — **same JARs**. |
| **Key modules**     | `h2h-persistence-spi`, `h2h-config-store`                                                                                     |
| **Runtime change?** | **No** code change; **Yes** env/Helm config + DBA migration run.                                                              |

| Doc                                                                           | What it explains                 |
| ----------------------------------------------------------------------------- | -------------------------------- |
| [14 Extensibility Framework](/docs/14-extensibility-framework.md)             | §6 Database-agnostic persistence |
| [45 Database-Agnostic Persistence](/docs/45-database-agnostic-persistence.md) | Full portability architecture    |
| [19 Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md)         | JDBC config per environment      |

***

### UC-13: Cloud vs on-prem deployment

|                     |                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Finacle on-prem; archive on AWS S3; platform must run hybrid.                                                                    |
| **Solution**        | Runtime on-prem K8s/OpenShift near Finacle; S3-compatible endpoint for archive; same Helm chart, different `values-hybrid.yaml`. |
| **Key modules**     | All — identical images                                                                                                           |
| **Runtime change?** | **No** application change                                                                                                        |

| Doc                                                                   | What it explains            |
| --------------------------------------------------------------------- | --------------------------- |
| [19 Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md) | §16 Hybrid deployment model |
| [07 Multi-Country Deployment](/docs/07-multi-country-deployment.md)   | Regional assignment         |
| [15 File Management System](/docs/15-file-management-system.md)       | S3/MinIO `FileStore` SPI    |

***

### UC-14: Custom validation script

|                     |                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Partner CSV has non-standard rule: "narration must contain cost center code pattern CC-####" — not in rule grid.                 |
| **Solution**        | Create Groovy `script_def` → attach to route as `SCRIPT_EXECUTE` step or `hook` at `camel.pre_step` → test in sandbox → publish. |
| **Key modules**     | `h2h-script-engine`, `h2h-extension-kernel` (HookExecutor)                                                                       |
| **Runtime change?** | **No**                                                                                                                           |

| Doc                                                                               | What it explains             |
| --------------------------------------------------------------------------------- | ---------------------------- |
| [14 Extensibility Framework](/docs/14-extensibility-framework.md)                 | §4 Logical operation scripts |
| [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md) | Hooks catalog                |
| [09 Security and Compliance](/docs/09-security-and-compliance.md)                 | Script sandbox limits        |

***

### UC-15: SLA breach alerting

|                     |                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Challenge**       | SLA requires bulk file processed within 5 minutes; ops must be alerted on breach.                                              |
| **Solution**        | Set `observability.slaMaxProcessingMs` in partner `CustomizationProfile` → `SlaMonitor` emits `h2h.sla.breach` → Alertmanager. |
| **Key modules**     | `h2h-observability`                                                                                                            |
| **Runtime change?** | **No**                                                                                                                         |

| Doc                                                                                     | What it explains             |
| --------------------------------------------------------------------------------------- | ---------------------------- |
| [17 Monitoring and Logging](/docs/17-monitoring-and-logging.md)                         | §9 SLA monitoring            |
| [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md)       | `ObservabilityCustomization` |
| [21 Event-Driven Runtime Extensibility](/docs/21-event-driven-runtime-extensibility.md) | Alert events on Kafka        |

***

### UC-16: Certificate expiry management

|                     |                                                                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Partner SFTP certificate expires in 30 days; prevent silent connection failures.                                                                                    |
| **Solution**        | Broker-delayed job publishes cert-expiry check → `CertificateService.daysUntilExpiry()` → alert → security officer rotates cert in Vault → update `credential_ref`. |
| **Key modules**     | `h2h-security`, `h2h-job-scheduler`                                                                                                                                 |
| **Runtime change?** | **No**                                                                                                                                                              |

| Doc                                                               | What it explains               |
| ----------------------------------------------------------------- | ------------------------------ |
| [16 Security Library](/docs/16-security-library.md)               | §8 Certificate lifecycle       |
| [09 Security and Compliance](/docs/09-security-and-compliance.md) | Certificate and key management |

***

### UC-17: Duplicate file detection

|                     |                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Partner accidentally uploads same payment file twice; must not double-pay.                                                   |
| **Solution**        | `IdempotencyProcessor` checks partner + filename + checksum + hash window → status `DUPLICATE` → skip Finacle → audit event. |
| **Key modules**     | `h2h-camel-core`, `h2h-file-management` (checksum in `file_registry`)                                                        |
| **Runtime change?** | **No** — duplicate window in `CamelCustomization` profile.                                                                   |

| Doc                                                                     | What it explains         |
| ----------------------------------------------------------------------- | ------------------------ |
| [08 Camel Integration Patterns](/docs/08-camel-integration-patterns.md) | Idempotent receiver      |
| [15 File Management System](/docs/15-file-management-system.md)         | §7.2 Inbound idempotency |
| [13 Design Patterns](/docs/13-design-patterns.md)                       | Idempotent receiver EIP  |

***

### UC-18: Manual approval workflow

|                     |                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Payments above ₦50M must be held for supervisor approval before Finacle post.                                              |
| **Solution**        | `routing_rule` in DB: IF amount > threshold THEN `MANUAL_REVIEW` → Camunda human task → on approve, requeue to processing. |
| **Key modules**     | `h2h-camel-core`, Camunda, `h2h-admin-api`                                                                                 |
| **Runtime change?** | **No** for threshold change; rule published in admin.                                                                      |

| Doc                                                                           | What it explains                |
| ----------------------------------------------------------------------------- | ------------------------------- |
| [04 Database-Driven Configuration](/docs/04-database-driven-configuration.md) | Routing rules                   |
| [05 Low-Code Admin Platform](/docs/05-low-code-admin-platform.md)             | Camunda approval workflows      |
| [13 Design Patterns](/docs/13-design-patterns.md)                             | Saga (optional) for human tasks |

***

### UC-19: Split services deployment

|                     |                                                                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | High SFTP volume isolated from payment processing; separate scaling and blast radius.                                                                     |
| **Solution**        | Deploy `h2h-file-gateway` (file-management JARs) and `h2h-payments-runtime` (routes + Finacle); coordinate via Kafka + `file_registry` + `correlationId`. |
| **Key modules**     | `h2h-file-management`, `h2h-payments-routes`, Kafka                                                                                                       |
| **Runtime change?** | **Yes** — second deployable image (one-time); behavior still config-driven.                                                                               |

| Doc                                                                                     | What it explains                     |
| --------------------------------------------------------------------------------------- | ------------------------------------ |
| [21 Event-Driven Runtime Extensibility](/docs/21-event-driven-runtime-extensibility.md) | §6 Composable services               |
| [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.md)                     | Compose different runtimes from JARs |
| [19 Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md)                   | Multiple deployments in K8s          |

***

### UC-20: Fintech API with HMAC signing

|                     |                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Fintech must sign every API request; bank verifies authenticity and prevents replay.                                         |
| **Solution**        | `SignatureService.verifyHmac()` at gateway/Camel → `replayWindowMinutes` in `SecurityCustomization` → reject stale requests. |
| **Key modules**     | `h2h-security`, API gateway                                                                                                  |
| **Runtime change?** | **No** — signing key ref and algorithm per partner in customization profile.                                                 |

| Doc                                                                               | What it explains        |
| --------------------------------------------------------------------------------- | ----------------------- |
| [16 Security Library](/docs/16-security-library.md)                               | §6 HMAC signing         |
| [09 Security and Compliance](/docs/09-security-and-compliance.md)                 | API security            |
| [20 Universal Library Extensibility](/docs/20-universal-library-extensibility.md) | `SecurityCustomization` |

***

### UC-21: Update Finacle wrapper only

|                     |                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Finacle FCUBS patch requires new payment operation mapping; payment routes unchanged.                                                                            |
| **Solution**        | Bump `h2h-finacle-wrapper` version in BOM → rebuild runtime image → rolling deploy. Payment routes depend on `CoreBankingIntegration` interface — **unchanged**. |
| **Key modules**     | `h2h-finacle-wrapper` only (`h2h-core-banking-api` interface stable)                                                                                             |
| **Runtime change?** | **Yes** — JAR rolling deploy (\~minutes); not a code fork.                                                                                                       |

| Doc                                                                         | What it explains                |
| --------------------------------------------------------------------------- | ------------------------------- |
| [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.md)         | §8 Versioning, surgical updates |
| [43 Core Banking Integration API](/docs/43-core-banking-integration-api.md) | Interface vs Finacle adapter    |

***

### UC-22: Mapping change without downtime

|                     |                                                                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Challenge**       | Partner changes CSV column layout; bank must update mapping without stopping the platform.                                                                  |
| **Solution**        | Edit `transform_spec` in admin → test harness with sample file → supervisor publish → `CONFIG_PUBLISHED` → cache invalidation → next file uses new mapping. |
| **Key modules**     | `h2h-config-runtime`, `h2h-transform-core`                                                                                                                  |
| **Runtime change?** | **No** — zero downtime                                                                                                                                      |

| Doc                                                                                     | What it explains              |
| --------------------------------------------------------------------------------------- | ----------------------------- |
| [04 Database-Driven Configuration](/docs/04-database-driven-configuration.md)           | Publish workflow, cache-aside |
| [05 Low-Code Admin Platform](/docs/05-low-code-admin-platform.md)                       | Mapping editor, test harness  |
| [21 Event-Driven Runtime Extensibility](/docs/21-event-driven-runtime-extensibility.md) | `CONFIG_PUBLISHED` event      |

***

## 4. Solution Pattern Summary

| Pattern                                | Use cases                     | Runtime redeploy? |
| -------------------------------------- | ----------------------------- | ----------------- |
| **Database config publish**            | UC-01, 05, 06, 08, 14, 18, 22 | No                |
| **CustomizationProfile**               | UC-07, 08, 15, 20             | No                |
| **Event subscription / webhook**       | UC-10                         | No                |
| **Scheduled operation (broker delay)** | UC-04, 11, 16                 | No                |
| **Composable JAR / module enable**     | UC-03, 19, 21                 | Rolling deploy    |
| **Infrastructure / Helm**              | UC-12, 13, 19                 | Env config        |
| **Idempotency + events**               | UC-02, 09, 17                 | No                |

***

## 5. Documentation Map by Stakeholder

| Stakeholder               | Start here           | Then read                                                                                                                                           |
| ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Business / product**    | This doc (use cases) | [01](/docs/01-architecture-overview.md), [44](/docs/44-program-cost-and-staffing.md)                                                                |
| **Integration analyst**   | UC-05, UC-22         | [04](/docs/04-database-driven-configuration.md), [05](/docs/05-low-code-admin-platform.md)                                                          |
| **Integration developer** | UC-14, UC-21         | [03](/docs/03-modular-jar-architecture.md), [08](/docs/08-camel-integration-patterns.md), [14](/docs/14-extensibility-framework.md)                 |
| **Architect**             | UC-06, UC-19         | [03](/docs/03-modular-jar-architecture.md), [20](/docs/20-universal-library-extensibility.md), [21](/docs/21-event-driven-runtime-extensibility.md) |
| **DevOps**                | UC-12, UC-13         | [19](/docs/19-cloud-agnostic-deployment.md), [07](/docs/07-multi-country-deployment.md)                                                             |
| **Security**              | UC-16, UC-20         | [09](/docs/09-security-and-compliance.md), [16](/docs/16-security-library.md)                                                                       |
| **Operations / NOC**      | UC-09, UC-15, UC-17  | [05](/docs/05-low-code-admin-platform.md), [17](/docs/17-monitoring-and-logging.md)                                                                 |
| **Compliance / audit**    | UC-01, UC-11         | [09](/docs/09-security-and-compliance.md), [17](/docs/17-monitoring-and-logging.md)                                                                 |

***

## 6. RFP Requirement Traceability

| RFP requirement                      | Use cases                                                                             | Primary docs                                                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standardized H2H across countries    | UC-01, UC-06                                                                          | [01](/docs/01-architecture-overview.md), [07](/docs/07-multi-country-deployment.md)                                                                           |
| File, HTTP, WebSocket, MQ interfaces | UC-01, UC-02, UC-10                                                                   | [15](/docs/15-file-management-system.md), [28](/docs/28-mq-jms-adapter.md), [39](/docs/39-api-gateway-architecture.md), [47](/docs/47-gateway-entrypoints.md) |
| Finacle integration                  | [23](/docs/23-finacle-integration.md), [43](/docs/43-core-banking-integration-api.md) |                                                                                                                                                               |
| PGP / secure file transfer           | UC-01, UC-07                                                                          | [16](/docs/16-security-library.md), [15](/docs/15-file-management-system.md)                                                                                  |
| ISO 20022 / MT940                    | UC-04                                                                                 | [24](/docs/24-transformation-and-messaging.md)                                                                                                                |
| High-volume STP                      | UC-01, UC-17                                                                          | [08](/docs/08-camel-integration-patterns.md), [32](/docs/32-performance-and-capacity.md)                                                                      |
| Multi-country deployment             | UC-06, UC-13                                                                          | [07](/docs/07-multi-country-deployment.md), [19](/docs/19-cloud-agnostic-deployment.md), [38](/docs/38-deployment-topology.md)                                |
| Monitoring and audit                 | UC-09, UC-15                                                                          | [17](/docs/17-monitoring-and-logging.md), [34](/docs/34-operations-architecture.md)                                                                           |
| Reconciliation                       | UC-11                                                                                 | [26](/docs/26-reconciliation.md)                                                                                                                              |
| Partner onboarding speed             | UC-05                                                                                 | [05](/docs/05-low-code-admin-platform.md), [37](/docs/37-partner-portal.md)                                                                                   |
| Extensibility without redeploy       | UC-08, UC-14, UC-22                                                                   | [14](/docs/14-extensibility-framework.md), [20](/docs/20-universal-library-extensibility.md), [21](/docs/21-event-driven-runtime-extensibility.md)            |
| Treasury / FX                        | —                                                                                     | [27](/docs/27-treasury-interfaces.md)                                                                                                                         |
| Training & handover                  | —                                                                                     | [41](/docs/41-training-and-handover.md)                                                                                                                       |
| Architecture completeness            | All                                                                                   | [42](/docs/42-architecture-sign-off.md)                                                                                                                       |
| Program budget & staffing            | —                                                                                     | [44](/docs/44-program-cost-and-staffing.md)                                                                                                                   |

***

## 7. Related Documents

* [Architecture Overview](/docs/01-architecture-overview.md)
* [Implementation Roadmap](/docs/10-implementation-roadmap.md)
* [Architecture Sign-Off](/docs/42-architecture-sign-off.md)
* [44 Program Cost and Staffing](/docs/44-program-cost-and-staffing.md)
* [Glossary](/docs/12-glossary.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/22-use-cases-and-solutions.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.