moov-io/achgateway

Purpose and runtime

ACH Gateway is a Go service that accepts ACH files over HTTP and Kafka, queues and transforms them, then uploads optimized files to an ODFI at configured cutoff times. It also retrieves and processes inbound ODFI files (returns, reconciliations, corrections, prenotes). The executable entry point is cmd/achgateway/main.go; service assembly and HTTP serving are centered in internal/server.go and internal/environment.go.

Service configuration and tenancy

Configuration defines storage, database, inbound/outbound transport, schedules, events, notifications, encryption, and shard mappings. Shards isolate tenant/file-processing scope and map requests or Kafka records to processing configuration. Core paths: configs/config.default.yml, internal/service/model_config.go, internal/shards/service_shard_mapping.go. Persistent shard and file metadata is supported through MySQL or Google Cloud Spanner migrations in migrations/001_shard_mappings.up.mysql.sql, migrations/002_files.up.spanner.sql.

File ingestion boundary

Public ingestion accepts Nacha ACH or Moov ACH JSON files under shard-scoped HTTP APIs, validates/normalizes them, and places accepted files into repository-backed pending storage. Kafka can provide the same asynchronous input channel. Relevant paths: internal/incoming/web/api_files.go, internal/pipeline/file_receiver.go, internal/kafka/kafka.go. This boundary separates caller-facing receipt from deferred cutoff-time delivery.

Outbound pipeline

The pipeline coordinates pending-file discovery, aggregation/merging, cutoff execution, formatting, transformation, and transfer. At cutoff, eligible shard files are merged where configured, rendered as Nacha or encoded/encrypted output, then sent through a selected transfer agent. Main orchestration paths: internal/pipeline/pipeline.go, internal/pipeline/merging.go, internal/pipeline/aggregate.go. Scheduling is implemented in internal/schedule/cutoff.go and manually triggerable through internal/pipeline/manual_cutoff_times.go.

Storage, security, and delivery adapters

Storage is abstracted behind blob/filesystem implementations and may encrypt persisted data. Before upload, files can be transformed with GPG; destination delivery supports FTP and SFTP, including retry and network-security handling. Paths: internal/storage/storage.go, internal/transform/gpg.go, internal/upload/ftp.go, internal/upload/sftp.go. These adapters are the primary boundaries to local/blob storage, cryptographic key material, and ODFI-hosted file servers.

Inbound ODFI processing

A periodic or manually triggered processor downloads remote inbound directories, classifies ACH artifacts, emits domain outcomes, and cleans up remote files after handling. ODFI-specific flows cover returns, corrections, prenotes, reconciliation, audits, and download lifecycle. Paths: internal/incoming/odfi/incoming.go, internal/incoming/odfi/processor.go, internal/incoming/odfi/returns.go, internal/incoming/odfi/cleanup.go.

Events, audit, and operational integrations

Domain events are delivered via stream/Kafka or webhooks; audit records can be retained through blob storage. Notifications and alerts target email, Kafka, Slack, and PagerDuty. Prometheus metrics are served separately on the metrics/admin listener, with manual operational triggers including cutoff and inbound processing. Paths: internal/events/service.go, internal/events/service_webhook.go, internal/audittrail/storage_blob.go, internal/notify/multi.go, internal/alerting/alerter.go.

Deployment

The service targets Go 1.19+ and is distributed as a Docker image. Local/container deployment is defined by Dockerfile, docker-compose.yml, and examples/getting-started/docker-compose.yml; default Docker-oriented configuration is in configs/config.docker.yml.