How valitydev/hellgate works
Hellgate is an Erlang/OTP service ecosystem centered on payment-state processing. The repository is organized as a multi-app release, with one primary domain engine and several surrounding adapter/support applications.
At the center is apps/hellgate, which contains the core business logic and domain model. This is the main processing layer for invoices, payments, cash, allocations, accounting, and related state transitions. The module names show a fairly rich payment domain: invoice lifecycle handling, registered payments, refunds, chargebacks, invoice repair/mutations, cashflow and allocation logic, party/payment-tool/payment-institution concepts, machine/state-machine handling, retries, limiting, inspection, profiling, and context/timing helpers. The include/*.hrl headers define shared record and event schemas for invoices, payments, parties, allocations, and durations, so this app is the canonical source of domain contracts.
A useful way to think about hellgate is as the business engine that turns input events or API calls into updated payment-state decisions and emitted domain events. It is not just a collection of utilities; it is the place where the service’s main invariants and state transitions live.
The apps/routing application is a separate decision-making boundary. It contains hg_route, hg_routing, hg_routing_ctx, and hg_routing_explanation, which indicates a dedicated routing subsystem responsible for choosing how a payment or request should be handled and explaining why that route was chosen. The presence of doc/route_pins.md reinforces that routing is an explicit, modeled concern rather than an incidental detail. In an architecture diagram, this should sit beside the core domain engine as a pure policy/decision layer that the business logic consults.
The apps/hg_proto application is the transport/service boundary. The presence of hg_woody_service_wrapper and hg_woody_wrapper strongly suggests the service is exposed over a Woody-based RPC interface, with hg_proto adapting protocol-level calls into the core domain logic and back. mg_msgpack_marshalling.erl in the core app also shows that message encoding/decoding is part of the integration boundary. In the diagram, this is the ingress/egress layer between external clients and the internal domain model.
The apps/hg_client application is a consumer-side library for interacting with Hellgate. It includes an API module, an event poller, and higher-level helpers for invoice templating and invoicing. This looks like an SDK or integration client rather than another server component. It likely consumes the RPC API and/or event stream exposed by the main service, so it belongs on the “external consumer” side of the architecture.
The apps/hg_progressor application appears to be a background processing component. Its hg_progressor_handler and hg_hybrid modules suggest asynchronous progression or reconciliation of work that cannot be completed in a single synchronous request path. In a diagram, it should be shown as a worker/daemon-style OTP app that cooperates with the main domain engine, probably advancing payment/invoice states or handling delayed transitions.
There are also several internal support boundaries inside apps/hellgate that matter architecturally:
• hg_proxy, hg_proxy_provider, and hg_proxy_host_provider indicate outbound proxy/provider integrations.
• hg_limiter and hg_limiter_client indicate rate/traffic control around some operations.
• hg_fault_detector_client suggests integration with an external fault-detection or monitoring service.
• hg_inspector, hg_profiler, and hg_timings suggest observability/diagnostic hooks.
• hg_retry and hg_cascade support resilient processing and fallback behavior.
These are not separate apps, but they are distinct integration/behavioral subsystems inside the core.
The test structure is also informative about architecture. The apps/hellgate/test directory contains Common Test suites plus dummy providers, inspectors, proxies, and a KV store, which implies the production system is built around pluggable boundaries that are easy to fake in tests. The test/postgres directory and Docker Compose files show that some integration tests rely on PostgreSQL, so persistence exists at least in the test environment and likely forms part of the real deployment story as well.
Operationally, the repo is built as an OTP release with rebar3, configured via config/sys.config and config/vm.args, and packaged through Docker/Docker Compose. The CI workflows cover linting, build-image creation, Erlang checks, and tagging, which means the project is intended to run as a containerized backend service rather than as a library-only codebase.
If you were drawing the architecture, the main boxes would be:
1. External clients / consumers
2. hg_proto transport/API boundary
3. hellgate core domain engine
4. routing policy engine
5. Outbound integrations such as proxy/provider, limiter, fault detection, and any persistence/event infrastructure
6. hg_client as a separate consumer SDK
7. hg_progressor as a background worker for asynchronous advancement
The key data flow is: external request or event enters through the protocol layer, the core domain evaluates business rules and routing, updates payment/invoice state, emits or persists outcomes, and asynchronous workers/clients consume follow-up events or continue progression where needed.
Main entry points: hg_invoice_handler.erl Invoice handler · hg_woody_service_wrapper.erl Service wrapper · hg_invoice.erl Invoice logic · hg_progressor_handler.erl Progress handler
Components 24
External consumers
SDKs and outside callers that interact with the service.
- Client API · Consumer-facing library entry point for service calls.
apps/hg_client/src/hg_client_api.erl - Event poller · Client-side consumer for the event stream or follow-up work.
apps/hg_client/src/hg_client_event_poller.erl - Client invoicing · Higher-level invoicing convenience layer for consumers.
apps/hg_client/src/hg_client_invoicing.erl
Transport boundary
RPC and serialization layer at the service edge.
- Proto app · Transport application that exposes the service boundary.
apps/hg_proto/src/hg_proto.erl - Woody wrapper · Adapter around RPC calls and service plumbing.
apps/hg_proto/src/hg_woody_wrapper.erl - Service wrapper · Maps inbound service calls into internal handlers.
apps/hg_proto/src/hg_woody_service_wrapper.erl
Core domain
Primary payment-state and invoice processing engine.
- Domain model · Shared business abstractions and canonical domain types.
apps/hellgate/src/hg_domain.erl - Invoice handler · Coordinates invoice lifecycle transitions and handling.
apps/hellgate/src/hg_invoice_handler.erl - Invoice logic · Invoice state and business rules.
apps/hellgate/src/hg_invoice.erl - Payment state · Registered payments, captures, refunds, and chargebacks.
apps/hellgate/src/hg_invoice_payment.erl - Cashflow · Cash movement and flow calculations.
apps/hellgate/src/hg_cashflow.erl - Allocation · Allocation and distribution logic for monetary amounts.
apps/hellgate/src/hg_allocation.erl - State machine · Machine-driven progression and transition control.
apps/hellgate/src/hg_machine.erl
Routing policy
Dedicated route selection and explanation subsystem.
- Routing · Route selection logic used to decide how requests are handled.
apps/routing/src/hg_routing.erl - Route explain · Explains why a route or decision was chosen.
apps/routing/src/hg_routing_explanation.erl
Background workers
Asynchronous progression and reconciliation components.
- Progressor · Background application for asynchronous progression.
apps/hg_progressor/src/hg_progressor.erl - Progress handler · Handles progressor work and advancement steps.
apps/hg_progressor/src/hg_progressor_handler.erl - Hybrid worker · Hybrid synchronous/asynchronous processing helper.
apps/hg_progressor/src/hg_hybrid.erl
Operational support
Shared behavioral and integration subsystems used by the core.
- Proxy · Outbound proxy boundary used by the core.
apps/hellgate/src/hg_proxy.erl - Proxy provider · Provider abstraction behind proxy-based integrations.
apps/hellgate/src/hg_proxy_provider.erl - Limiter · Rate or load limiting around sensitive operations.
apps/hellgate/src/hg_limiter.erl - Retry · Retry and fallback support for transient failures.
apps/hellgate/src/hg_retry.erl - Inspector · Inspection hook for introspection and diagnostics.
apps/hellgate/src/hg_inspector.erl - Fault detector · Client integration for external fault detection or monitoring.
apps/hellgate/src/hg_fault_detector_client.erl
Connections 23
- Client API → Proto app: calls · Client SDK sends requests through the transport boundary.
- Client invoicing → Client API: wraps · Higher-level invoicing helpers build on the base SDK.
- Event poller → Client API: consumes · Poller consumes service or event interfaces via the SDK.
- Proto app → Woody wrapper: adapts · Transport app delegates RPC plumbing to the wrapper.
- Woody wrapper → Service wrapper: dispatches · Wrapper routes inbound calls into service handlers.
- Service wrapper → Invoice handler: enters · Service calls reach the core invoice workflow.
- Service wrapper → Domain model: maps · Transport layer converts protocol payloads into domain shapes.
- Invoice handler → Invoice logic: orchestrates · Invoice workflow coordinates invoice-specific rules.
- Invoice handler → Payment state: updates · Workflow advances payment and refund state.
- Invoice handler → State machine: drives · State transitions are executed through the machine layer.
- Invoice logic → Allocation: uses · Invoice logic relies on allocation calculations.
- Invoice logic → Cashflow: uses · Invoice logic interacts with cashflow computations.
- Payment state → Routing: consults · Payment handling can depend on routing decisions.
- Routing → Route explain: explains · Routing policy produces decision explanations.
- Progressor → Progress handler: contains · Progressor app delegates work to its handler.
- Progress handler → Hybrid worker: coordinates · Handler uses hybrid execution for mixed sync/async work.
- Progress handler → Invoice handler: advances · Background worker continues invoice or payment progression.
- Invoice handler → Proxy: outbounds · Core logic may call outbound proxy integrations.
- Proxy → Proxy provider: backed by · Proxy layer is implemented through provider abstractions.
- Invoice handler → Limiter: guards · Limiter constrains selected operations.
- Invoice handler → Retry: retries · Transient failures are handled through retry support.
- Invoice handler → Inspector: observes · Diagnostic hooks inspect execution paths.
- Invoice handler → Fault detector: reports · Core processing can report faults to monitoring.