> 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/38-deployment-topology.md).

# Deployment Topology

## 1. Overview

Defines **what gets deployed**, **default vs optional split**, and **how services acknowledge each other**. Complements [Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md) and [Event-Driven Runtime Extensibility](/docs/21-event-driven-runtime-extensibility.md).

***

## 2. Decision: Default Topology

**Default: Modular monolith** — one `h2h-runtime` per region.

| Choice                      | Selected    | Rationale                                       |
| --------------------------- | ----------- | ----------------------------------------------- |
| Microservices per partner   | No          | Not scalable operationally                      |
| Microservices per country   | No          | Config handles country differences              |
| **Composable JAR monolith** | **Yes**     | STP, single Camel context, simpler transactions |
| Separate control plane      | Yes         | Admin API/UI always separate                    |
| Optional edge split         | When needed | File gateway at scale                           |

***

## 3. Deployable Units

```mermaid
flowchart TB
  subgraph required [Required Deployables]
    RT[h2h-runtime]
    ADMIN[h2h-admin-api]
    UI[h2h-admin-ui]
  end

  subgraph optional [Optional Deployables]
    FG[h2h-file-gateway]
    EW[h2h-event-worker]
    WH[h2h-webhook-dispatcher]
    PP[h2h-partner-portal]
  end

  subgraph infra [Infrastructure]
    GW[API Gateway - HTTP]
    WSG[WebSocket Gateway]
    SFTP[SFTP Gateway]
    K[Kafka]
    DB[(RDBMS)]
    V[Vault]
  end

  GW --> RT
  WSG --> RT
  SFTP --> FG
  FG --> RT
  RT --> K
  RT --> DB
  ADMIN --> DB
  EW --> K
  WH --> K
```

| Unit                 | JARs                                                                             | Default?    |
| -------------------- | -------------------------------------------------------------------------------- | ----------- |
| `h2h-runtime`        | routes, finacle, file-mgmt, camel-core, security, context, observability, config | Yes         |
| `h2h-admin-api`      | admin-api, config-store, extension-kernel                                        | Yes         |
| `h2h-admin-ui`       | Next.js                                                                          | Yes         |
| `h2h-file-gateway`   | file-management, security                                                        | Optional    |
| `h2h-event-worker`   | event-extensions, script-engine, webhook-dispatcher                              | Optional    |
| `h2h-partner-portal` | Next.js                                                                          | Phase 5     |
| API Gateway          | Kong/Apigee                                                                      | Yes (infra) |

***

## 4. When to Split

| Trigger                     | Split              | Keep monolith       |
| --------------------------- | ------------------ | ------------------- |
| SFTP volume > 10K files/day | file-gateway       |                     |
| Webhook fan-out > 1K/min    | event-worker       |                     |
| Finacle latency sensitive   |                    | Yes — co-locate     |
| Team ownership boundaries   | event-worker       | payments in runtime |
| Regulatory isolation        | separate namespace | same image          |
| MVP / pilot                 |                    | **Yes**             |

***

## 5. Inter-Service Acknowledgement

| Mechanism         | Purpose                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `correlationId`   | Same identity across services                                          |
| `file_registry`   | File state (shared DB or sync)                                         |
| Kafka events      | `PAYMENT_POSTED`, `FILE_DELIVERED` (`event_code` → DB-resolved topics) |
| Health checks     | `/actuator/health/readiness`                                           |
| Delivery receipts | File gateway → runtime                                                 |

**No synchronous admin calls on hot path.**

***

## 6. Deployment Targets (Kubernetes and Legacy)

### 6.1 Profile A — Kubernetes (recommended)

```
h2h-production/
├── h2h-runtime          (3+ replicas, HPA)
├── h2h-admin-api        (2 replicas)
├── h2h-admin-ui         (2 replicas)
├── h2h-event-worker     (optional, 2 replicas)
└── h2h-file-gateway     (optional, 2 replicas)

h2h-infra/
├── postgresql / kafka / vault / minio / otel-collector
```

### 6.2 Profile B/C — Legacy data centre (no Kubernetes)

| Unit            | Legacy deployment                                                        |
| --------------- | ------------------------------------------------------------------------ |
| `h2h-runtime`   | 1–2 VMs: executable JAR + systemd **or** WAR on WebLogic/WebSphere/JBoss |
| `h2h-admin-api` | Separate JAR/WAR instance or co-deployed (small banks)                   |
| `h2h-admin-ui`  | Static nginx on VM **or** existing bank portal server                    |
| Kafka / DB      | Bank-managed cluster — same JDBC/Kafka protocol as cloud                 |

**Typical pattern:** `h2h-runtime` on the **same network segment as Finacle** (Profile B/C) minimises latency; admin UI may sit in a less restricted zone.

***

## 7. Network Zones

| Zone         | Components                                      |
| ------------ | ----------------------------------------------- |
| DMZ          | SFTP gateway, API gateway                       |
| App          | runtime, admin, event-worker                    |
| Data         | PostgreSQL, Kafka, Vault, MinIO                 |
| Core banking | Finacle CBS provider endpoint (on-prem typical) |

Applies to all deployment profiles — implemented as K8s namespaces (Profile A) or VLAN/LB segments (Profiles B/C).

***

## 8. Scaling Model

| Component    | Scale trigger                  |
| ------------ | ------------------------------ |
| h2h-runtime  | CPU > 70%, payment queue depth |
| file-gateway | SFTP connection count          |
| event-worker | Kafka consumer lag             |
| admin-api    | Independent of payment volume  |

***

## 9. Related Documents

* [19 Cloud-Agnostic Deployment](/docs/19-cloud-agnostic-deployment.md)
* [07 Multi-Country Deployment](/docs/07-multi-country-deployment.md)
* [21 Event-Driven Runtime Extensibility](/docs/21-event-driven-runtime-extensibility.md)
* [03 Modular JAR Architecture](/docs/03-modular-jar-architecture.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/38-deployment-topology.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.