> 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/05-low-code-admin-platform.md).

# Low-Code Admin Platform

## 1. Overview

The low-code admin platform enables **non-developers** and **integration analysts** to onboard partners, configure integrations, manage exceptions, and monitor operations — without writing code or redeploying the integration runtime.

Low-code here means **configuration over code**: admins compose integrations from pre-built capability blocks (step types, transform engines, validation operators) stored and versioned in the database.

## 2. Design Philosophy

| Principle              | Implementation                                                                  |
| ---------------------- | ------------------------------------------------------------------------------- |
| Config over code       | Partner behavior in the relational config store (any supported RDBMS), not Java |
| Composable blocks      | Admins pick step types and mapping engines — not write Camel routes             |
| Safe change management | Draft → test → approve → publish workflow                                       |
| Scope isolation        | Country and partner RBAC on every screen                                        |
| Instant feedback       | Test harness runs transforms and validations before publish                     |
| Auditability           | Every change logged with before/after snapshots                                 |

## 3. What Admins Configure vs What Developers Build

| Admins Configure (Low-Code)                               | Developers Build (JARs)                                           |
| --------------------------------------------------------- | ----------------------------------------------------------------- |
| Partner profiles and channels (SFTP, HTTP, WebSocket, MQ) | SFTP, HTTP, WebSocket, Kafka, Finacle adapters                    |
| Route template step sequences                             | Step type implementations                                         |
| Data mapping specifications                               | JOLT, JSONata, XSLT engines                                       |
| Validation and routing rules                              | Validation engine, rules evaluator                                |
| Cut-off schedules and calendars                           | Cut-off rule evaluation (schedule metadata — not in-process cron) |
| Scheduled operations (jobs)                               | Broker-delayed execution via `h2h-job-scheduler`                  |
| ACK/NACK templates                                        | ACK generation component                                          |
| Reconciliation matching rules                             | Reconciliation pipeline                                           |
| Exception handling policies                               | Retry, DLQ, Camunda integration                                   |

## 4. Admin Platform Architecture

```mermaid
flowchart TB
  subgraph frontend [Admin Frontend - Next.js]
    PartnerUI[Partner Onboarding]
    FlowUI[Flow Designer]
    MapUI[Mapping Editor]
    RulesUI[Rules Console]
    SchedUI[Schedule Manager]
    PublishUI[Publish Center]
    OpsUI[Operations Dashboard]
    ReconUI[Reconciliation Workbench]
  end

  subgraph backend [Admin Backend - h2h-admin-api]
    PartnerAPI[Partner API]
    ConfigAPI[Config API]
    TestAPI[Test Harness API]
    PublishAPI[Publish API]
    OpsAPI[Operations API]
  end

  subgraph services [Shared Services]
  DB[(PostgreSQL)]
  Vault[HashiCorp Vault]
  Camunda[Camunda Workflow]
  Kafka[Kafka Events]
  end

  frontend --> backend
  backend --> DB
  backend --> Vault
  backend --> Camunda
  PublishAPI --> Kafka
```

## 5. Admin Modules

### 5.1 Partner Onboarding Wizard

**Persona:** Partner onboarding officer, country integration admin

**Workflow:**

```mermaid
flowchart LR
  A[Create Partner] --> B[Configure Channel]
  B --> C[Assign Credentials]
  C --> D[Select Message Types]
  D --> E[Assign Route Template]
  E --> F[Configure Mappings]
  F --> G[Test in Sandbox]
  G --> H[Submit for Approval]
  H --> I[Publish to Production]
```

**Screens:**

| Step               | Fields                                                      |
| ------------------ | ----------------------------------------------------------- |
| Partner details    | Name, country, tier, contacts, status                       |
| Channel setup      | SFTP/API/MQ, paths, poll schedule, IP allowlist             |
| Credentials        | Vault reference assignment (upload cert → Vault → link ref) |
| Message types      | Enable BULK\_PAYMENT, COLLECTION, etc.                      |
| Profile assignment | Route template, transforms, rulesets                        |
| Sandbox test       | Upload sample file, view processing result                  |
| Approval           | Supervisor review and publish                               |

### 5.2 Flow Designer

**Persona:** Integration analyst, integration developer

Visual composer for route templates. Admins drag **registered step types** into a sequence:

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ PGP Decrypt  │───▶│  Transform   │───▶│   Validate   │
└──────────────┘    └──────────────┘    └──────────────┘
                                              │
┌──────────────┐    ┌──────────────┐    ┌──────▼───────┐
│ Deliver ACK  │◀───│ Generate ACK │◀───│ Finacle Post │
└──────────────┘    └──────────────┘    └──────────────┘
```

**Features:**

* Step palette sourced from `StepRegistry` (only valid step codes)
* Per-step configuration panel (JSON schema driven)
* Error handling selector per step (RETRY / DLQ / MANUAL)
* Template versioning and cloning
* Cannot add steps that don't exist in JARs

### 5.3 Mapping Editor

**Persona:** Integration analyst

Visual and text editor for transformation specifications:

| Feature                       | Description                                          |
| ----------------------------- | ---------------------------------------------------- |
| Source/target format selector | CSV, ISO20022, XML, JSON, CANONICAL                  |
| Engine selector               | JOLT, JSONata, XSLT                                  |
| Visual field mapper           | Drag source fields to target fields (generates JOLT) |
| Code view                     | Edit raw spec for advanced users                     |
| Sample tester                 | Upload sample input, run transform, view output      |
| Diff view                     | Compare output to expected output                    |

### 5.4 Rules Console

**Persona:** Business operations, integration analyst

| Rule Type        | UI                                                   |
| ---------------- | ---------------------------------------------------- |
| Validation rules | Field, operator, value, error code grid              |
| Routing rules    | Condition builder (IF amount > X THEN manual review) |
| Limit policies   | Daily max, per-transaction max, velocity rules       |

Rules support **priority ordering** and **effective date ranges**.

### 5.5 Schedule Manager

**Persona:** Country integration admin

* **Job schedules:** schedule expression builder (cron notation for computing next fire time), timezone, `schedule_type` (CRON / INTERVAL / ONE\_TIME), delay backbone (Kafka / RabbitMQ)
* Holiday calendar management per country
* Cut-off time configuration per partner/product (evaluated at transaction time — not a cron job)
* Action on miss: reject, queue for next business day

Published jobs are enqueued as **delayed broker messages** — delivery is guaranteed even if the runtime was down at the planned fire time.

### 5.6 Publish Center

**Persona:** Integration supervisor, platform super admin

| Feature                 | Description                               |
| ----------------------- | ----------------------------------------- |
| Pending approvals queue | All configs awaiting approval             |
| Diff viewer             | Side-by-side before/after for each change |
| Publish action          | Approve → PUBLISHED → cache invalidation  |
| Rollback                | Select historical version → republish     |
| Audit log               | Searchable history of all config changes  |

### 5.7 Operations Dashboard

**Persona:** NOC, operations team

| Feature                  | Description                                |
| ------------------------ | ------------------------------------------ |
| Live transaction feed    | Real-time processing status                |
| Partner health           | Per-partner success/failure rates          |
| SLA monitoring           | Processing time against thresholds         |
| Alert console            | Active alerts, acknowledge, escalate       |
| Failed transaction queue | Retry, reprocess, send to manual review    |
| DLQ browser              | Inspect and reprocess dead-letter messages |

### 5.8 Reconciliation Workbench

**Persona:** Reconciliation analyst

| Feature           | Description                     |
| ----------------- | ------------------------------- |
| Unmatched items   | Transactions pending match      |
| Match suggestions | System-proposed matches         |
| Manual match      | Analyst links items             |
| Exception buckets | Categorized unmatched items     |
| Export            | Generate reconciliation reports |

### 5.9 Partner Self-Service Portal

**Persona:** Corporate client (external)

Separate portal with limited access:

| Feature            | Description                          |
| ------------------ | ------------------------------------ |
| Transaction status | Search by reference, date, amount    |
| File upload status | Inbound file processing state        |
| API documentation  | Swagger/OpenAPI per partner products |
| Sandbox access     | Test credentials and sample files    |
| Download centre    | Statements, ACK files                |

## 6. Test Harness

Before any config is published, the test harness validates:

```mermaid
flowchart LR
  Input[Sample Input] --> Transform[Apply Transform]
  Transform --> Validate[Apply Rules]
  Validate --> Simulate[Simulate Route Steps]
  Simulate --> Output[Expected Output]
  Output --> Compare{Match?}
  Compare -->|Yes| Pass[Ready to Publish]
  Compare -->|No| Fail[Show Diff]
```

**Test types:**

| Test                  | Scope                                         |
| --------------------- | --------------------------------------------- |
| Transform test        | Mapping spec only                             |
| Validation test       | Rules against sample data                     |
| End-to-end simulation | Full route template (Finacle mocked)          |
| ACK generation test   | Verify ACK format matches partner expectation |

Tests run in **sandbox environment** — never against production Finacle.

## 7. Approval Workflows (Maker–Checker)

All approvals use **`h2h-workflow`** + Camunda. Policies and step definitions live in the database — see [40 Workflow Architecture](/docs/40-workflow-architecture.md).

| Workflow            | Maker                           | Checker(s)                                  | Levels      |
| ------------------- | ------------------------------- | ------------------------------------------- | ----------- |
| Config change       | Integration analyst / developer | Integration supervisor                      | 1 (default) |
| Partner go-live     | Onboarding officer              | Supervisor → country admin                  | 2           |
| Large limit change  | Integration analyst             | Supervisor → country admin → platform admin | 3           |
| Production rollback | Integration analyst             | Integration supervisor                      | 1           |
| Bulk reprocess      | NOC                             | Ops supervisor → integration supervisor     | 2           |
| Large payment hold  | System (routing rule)           | Ops supervisor                              | 1           |

Maker cannot approve their own submission (four-eyes enforced in `MakerCheckerDelegate`).

## 8. UI Technology

| Component      | Technology                                       |
| -------------- | ------------------------------------------------ |
| Framework      | Next.js (React)                                  |
| UI library     | Tailwind CSS + shadcn/ui (or bank design system) |
| Forms          | React Hook Form + Zod validation                 |
| Data grids     | TanStack Table                                   |
| Flow designer  | React Flow                                       |
| Mapping editor | Custom builder + Monaco Editor (code view)       |
| Charts         | Recharts or Grafana embedded                     |
| Auth           | Keycloak OIDC integration                        |

## 9. Admin API Design

RESTful APIs in `h2h-admin-api` JAR:

| Endpoint Group       | Examples                       |
| -------------------- | ------------------------------ |
| `/api/v1/partners`   | CRUD partners                  |
| `/api/v1/channels`   | Channel config                 |
| `/api/v1/profiles`   | Integration profiles           |
| `/api/v1/templates`  | Route templates and steps      |
| `/api/v1/transforms` | Transform specs                |
| `/api/v1/rules`      | Validation and routing rules   |
| `/api/v1/schedules`  | Cut-off and calendars          |
| `/api/v1/publish`    | Submit, approve, rollback      |
| `/api/v1/test`       | Test harness execution         |
| `/api/v1/operations` | Transaction search, retry, DLQ |
| `/api/v1/recon`      | Reconciliation operations      |

All mutations on draft entities. Publish endpoint transitions to `PUBLISHED`.

## 10. Separation from Transaction Path

The admin platform is **not in the hot path**:

* Admin API runs as a separate deployment (or separate module with distinct scaling)
* Transaction processing never calls admin APIs synchronously
* Config changes propagate via database + Kafka cache invalidation
* Admin downtime does not stop transaction processing

## 11. Related Documents

* [Database-Driven Configuration](/docs/04-database-driven-configuration.md)
* [Personas and RBAC](/docs/06-personas-and-rbac.md)
* [Security and Compliance](/docs/09-security-and-compliance.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/05-low-code-admin-platform.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.