Login

Architecture

Technical architecture reference for OMNYTH Payment Hub.

System Overview

OMNYTH is a modular monolith built with Spring Boot 3 and Java 21. The 28 Maven submodules map to distinct payment domain concerns and are designed to be extracted into microservices independently. All modules share three core artifacts: domain model, REST API, and infrastructure.

Component Architecture

Key components:

  • Experience API — versioned entry point for external integrations. Masks sensitive fields, validates input, and delegates to the flow engine.
  • Flow Engine — step-by-step execution runtime. Selects flows by payment type and country, executes steps in order, handles branching and retry.
  • Step Executors — one per step type: VALIDATION, SCREENING, FRAUD_CHECK, FEE_CALCULATION, ROUTING_DECISION, GATEWAY_SUBMISSION, SERVICE_CALL, APPROVAL_WORKFLOW, NOTIFICATION.
  • Integration Fabric — dynamic HTTP executor with circuit breaker, retry, and resilience policies. Calls configured service registry entries.
  • Scheme Adapters — rail-specific execution adapters for SWIFT, ACH, SEPA, TARGET2.
  • Security Framework — field-level encryption, signing, and HMAC verification. Policy-driven and runtime-configurable.

Flow Execution Model

Flow selection uses a priority cascade: country+paymentType+channel+rail, then progressively broader matches down to paymentType only. The first matching published flow wins.

Steps are linked by edges — each step's output determines the next step via labeled transitions (success, failure, retry). Edge targets are step order indices, not positions in an array, so flows can branch non-linearly.

Loop protection limits total step executions to 100 per flow run, and each individual step to 10 executions, preventing infinite retry loops.

Security Architecture

Security policies are attached to service integrations. A policy defines which operations are active (encryption, signing, HMAC) and references key aliases — never raw key material.

Key providers (keystore, HSM) resolve aliases at runtime. The application never stores keys in the database. Crypto operations are logged in an immutable audit trail with input hashes (SHA-256) — plaintext is never persisted.

Observability Pipeline

OMNYTH exports Prometheus metrics from every service call, step execution, and flow run. Structured logs go to Loki. Grafana dashboards visualize throughput, latency, success rates, and provider health.

Every payment step produces a log entry with payment ID, step type, duration, input hash, and output summary — enabling full reconstruction of any payment's execution path from audit logs alone.

Database

PostgreSQL stores payments, flow definitions, and configuration. MongoDB stores audit logs and reporting data. Schema migrations are managed exclusively by Flyway — no DDL auto-generation.

Deployment

All services run as Docker containers on a single DigitalOcean droplet behind nginx. Separate subdomains for each concern: platform UI, API, authentication, and monitoring. TLS is handled at the nginx layer via Let's Encrypt certificates.