openfintechlab/paytrace-orchestrator repository overview

⁠Overview

paytrace-orchestrator is the Saga coordination and workflow control service for the PayTrace platform. PayTrace is an open-source payment processing solution by OpenFintechLab, designed around microservices, asynchronous processing, auditability, and container-based deployment.

This service is responsible for coordinating payment file processing workflows across PayTrace components. It acts as the central orchestration layer that tracks the progress of file ingestion, row-level processing, payment execution, response generation, and workflow completion.

GitHub Code Repository: https://github.com/openfintechlab/paytrace-orchestrator⁠
Docker Image Repository: openfintechlab/paytrace-orchestrator
Default Branch: main
Visibility: Public
Component Reference: PAYTRC-CORE-002: Saga coordination & workflow control

⁠Purpose

The orchestrator manages the end-to-end lifecycle of a PayTrace payment processing flow. It coordinates distributed steps across multiple microservices and ensures that each stage of the workflow is executed in the correct order.

Typical responsibilities include:

• Coordinating Saga-based payment processing workflows
• Managing workflow state transitions
• Tracking file and row-level processing progress
• Publishing orchestration events to downstream services
• Triggering response file generation once processing is complete
• Supporting failure handling, retries, and controlled compensation logic
• Maintaining audit-friendly workflow visibility

⁠Role in PayTrace Architecture

paytrace-orchestrator works as a core service in the PayTrace microservices ecosystem.

It coordinates with services such as:

• paytrace-file-ingest for file intake and registry creation
• paytrace-payment-processor for payment row execution
• paytrace-response-writer for response file generation
• paytrace-tracker for workflow tracking and operational visibility
• RabbitMQ for asynchronous event communication
• PostgreSQL for workflow, registry, and processing state persistence
• Keycloak for platform-level authentication and authorization

⁠High-Level Workflow

1. A payment file is detected and registered by the file ingestion service.
2. The orchestrator receives or detects the file processing event.
3. File rows are dispatched for payment processing.
4. The orchestrator monitors row completion status.
5. Once all eligible rows are marked as PROCESSED or FAILED, the orchestrator triggers response file generation.
6. The response writer creates the response file and updates the workflow status.
7. Final workflow state is made available for tracking and audit.

⁠Key Capabilities

• Saga-based orchestration
• Event-driven workflow coordination
• File-level and row-level processing control
• Asynchronous service-to-service coordination
• Response generation trigger logic
• Failure-aware workflow handling
• Designed for containerized deployment
• Suitable for local development and future Kubernetes deployment

⁠Docker Image Usage

This Docker image packages the PayTrace Orchestrator service so it can be deployed as part of the PayTrace container ecosystem.

Example image name:

openfintechlab/paytrace-orchestrator

Example run command:
```bash
docker run --name paytrace-orchestrator \
  --network paytrace-network \
  -e DB_HOST=postgres \
  -e DB_PORT=5432 \
  -e DB_NAME=paytrace \
  -e DB_USER=paytrace \
  -e DB_PASSWORD=paytrace \
  -e RABBITMQ_HOST=rabbitmq \
  -e RABBITMQ_PORT=5672 \
  openfintechlab/paytrace-orchestrator:latest

⁠Deployement Context

This image is intended to run with the wider PayTrace platform stack, including database, message broker, identity provider, and other PayTrace services. Recommended supporting containers:

• PostgreSQL
• RabbitMQ
• Keycloak
• paytrace-file-ingest
• paytrace-payment-processor
• paytrace-response-writer
• paytrace-tracker

⁠Configurations

DB_HOST
DB_PORT
DB_NAME
DB_USER
DB_PASSWORD
RABBITMQ_HOST
RABBITMQ_PORT
RABBITMQ_USERNAME
RABBITMQ_PASSWORD
KEYCLOAK_URL
KEYCLOAK_REALM

Exact configuration values may vary depending on the deployment profile.

⁠Source Code

The source code for this Docker image is available in the public GitHub repository:

https://github.com/openfintechlab/paytrace-orchestrator

⁠Status

This repository is part of the PayTrace core platform and represents the orchestration component for distributed payment workflow processing.

The current repository README identifies this service as:

PAYTRC-CORE-002: Saga coordination & workflow control

⁠About OpenFintechLab

OpenFintechLab builds open-source financial technology components focused on payment processing, banking integration, automation, and modern API-first financial platforms.