# valitydev/hellgate architecture

> Architecture diagram of the GitHub repository valitydev/hellgate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valitydev/hellgate
- Repository: https://github.com/valitydev/hellgate

## Overview

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: [`apps/hellgate/src/hg_invoice_handler.erl`](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice_handler.erl) (Invoice handler), [`apps/hg_proto/src/hg_woody_service_wrapper.erl`](https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_woody_service_wrapper.erl) (Service wrapper), [`apps/hellgate/src/hg_invoice.erl`](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice.erl) (Invoice logic), [`apps/hg_progressor/src/hg_progressor_handler.erl`](https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_progressor_handler.erl) (Progress handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["External consumers"]
  node_hg_client_api["Client API<br/>SDK API<br/>[hg_client_api.erl]"]
  node_hg_client_event_poller["Event poller<br/>SDK poller"]
  node_hg_client_invoicing["Client invoicing<br/>SDK helper"]
end

subgraph group_transport["Transport boundary"]
  node_hg_proto["Proto app<br/>transport app<br/>[hg_proto.erl]"]
  node_hg_woody_wrapper["Woody wrapper<br/>rpc adapter"]
  node_hg_woody_service_wrapper["Service wrapper<br/>rpc service"]
end

subgraph group_core["Core domain"]
  node_hg_domain["Domain model<br/>core model<br/>[hg_domain.erl]"]
  node_hg_invoice_handler["Invoice handler<br/>workflow"]
  node_hg_invoice["Invoice logic<br/>invoice domain<br/>[hg_invoice.erl]"]
  node_hg_invoice_payment["Payment state<br/>payment domain"]
  node_hg_cashflow["Cashflow<br/>cash ledger<br/>[hg_cashflow.erl]"]
  node_hg_allocation["Allocation<br/>[hg_allocation.erl]"]
  node_hg_machine["State machine<br/>state engine<br/>[hg_machine.erl]"]
end

subgraph group_policy["Routing policy"]
  node_hg_routing["Routing<br/>policy engine<br/>[hg_routing.erl]"]
  node_hg_routing_explanation["Route explain<br/>policy explain"]
end

subgraph group_workers["Background workers"]
  node_hg_progressor["Progressor<br/>worker app<br/>[hg_progressor.erl]"]
  node_hg_progressor_handler["Progress handler<br/>worker handler"]
  node_hg_hybrid["Hybrid worker<br/>worker logic<br/>[hg_hybrid.erl]"]
end

subgraph group_support["Operational support"]
  node_hg_proxy["Proxy<br/>outbound adapter<br/>[hg_proxy.erl]"]
  node_hg_proxy_provider["Proxy provider<br/>provider adapter"]
  node_hg_limiter["Limiter<br/>traffic control<br/>[hg_limiter.erl]"]
  node_hg_retry["Retry<br/>resilience<br/>[hg_retry.erl]"]
  node_hg_inspector["Inspector<br/>observability<br/>[hg_inspector.erl]"]
  node_hg_fault_detector_client["Fault detector<br/>monitoring client"]
end

node_hg_client_api -->|"calls"| node_hg_proto
node_hg_client_invoicing -->|"wraps"| node_hg_client_api
node_hg_client_event_poller -->|"consumes"| node_hg_client_api
node_hg_proto -->|"adapts"| node_hg_woody_wrapper
node_hg_woody_wrapper -->|"dispatches"| node_hg_woody_service_wrapper
node_hg_woody_service_wrapper -->|"enters"| node_hg_invoice_handler
node_hg_woody_service_wrapper -->|"maps"| node_hg_domain
node_hg_invoice_handler -->|"orchestrates"| node_hg_invoice
node_hg_invoice_handler -->|"updates"| node_hg_invoice_payment
node_hg_invoice_handler -->|"drives"| node_hg_machine
node_hg_invoice -->|"uses"| node_hg_allocation
node_hg_invoice -->|"uses"| node_hg_cashflow
node_hg_invoice_payment -->|"consults"| node_hg_routing
node_hg_routing -->|"explains"| node_hg_routing_explanation
node_hg_progressor -->|"contains"| node_hg_progressor_handler
node_hg_progressor_handler -->|"coordinates"| node_hg_hybrid
node_hg_progressor_handler -->|"advances"| node_hg_invoice_handler
node_hg_invoice_handler -->|"outbounds"| node_hg_proxy
node_hg_proxy -->|"backed by"| node_hg_proxy_provider
node_hg_invoice_handler -->|"guards"| node_hg_limiter
node_hg_invoice_handler -->|"retries"| node_hg_retry
node_hg_invoice_handler -->|"observes"| node_hg_inspector
node_hg_invoice_handler -->|"reports"| node_hg_fault_detector_client

click node_hg_client_api "https://github.com/valitydev/hellgate/blob/master/apps/hg_client/src/hg_client_api.erl"
click node_hg_client_event_poller "https://github.com/valitydev/hellgate/blob/master/apps/hg_client/src/hg_client_event_poller.erl"
click node_hg_client_invoicing "https://github.com/valitydev/hellgate/blob/master/apps/hg_client/src/hg_client_invoicing.erl"
click node_hg_proto "https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_proto.erl"
click node_hg_woody_wrapper "https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_woody_wrapper.erl"
click node_hg_woody_service_wrapper "https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_woody_service_wrapper.erl"
click node_hg_domain "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_domain.erl"
click node_hg_invoice_handler "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice_handler.erl"
click node_hg_invoice "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice.erl"
click node_hg_invoice_payment "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice_payment.erl"
click node_hg_cashflow "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_cashflow.erl"
click node_hg_allocation "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_allocation.erl"
click node_hg_machine "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_machine.erl"
click node_hg_routing "https://github.com/valitydev/hellgate/blob/master/apps/routing/src/hg_routing.erl"
click node_hg_routing_explanation "https://github.com/valitydev/hellgate/blob/master/apps/routing/src/hg_routing_explanation.erl"
click node_hg_progressor "https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_progressor.erl"
click node_hg_progressor_handler "https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_progressor_handler.erl"
click node_hg_hybrid "https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_hybrid.erl"
click node_hg_proxy "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_proxy.erl"
click node_hg_proxy_provider "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_proxy_provider.erl"
click node_hg_limiter "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_limiter.erl"
click node_hg_retry "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_retry.erl"
click node_hg_inspector "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_inspector.erl"
click node_hg_fault_detector_client "https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_fault_detector_client.erl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hg_client_api,node_hg_client_event_poller,node_hg_client_invoicing toneBlue
class node_hg_proto,node_hg_woody_wrapper,node_hg_woody_service_wrapper toneAmber
class node_hg_domain,node_hg_invoice_handler,node_hg_invoice,node_hg_invoice_payment,node_hg_cashflow,node_hg_allocation,node_hg_machine toneMint
class node_hg_routing,node_hg_routing_explanation toneRose
class node_hg_progressor,node_hg_progressor_handler,node_hg_hybrid toneIndigo
class node_hg_proxy,node_hg_proxy_provider,node_hg_limiter,node_hg_retry,node_hg_inspector,node_hg_fault_detector_client toneTeal
```

## Components

### External consumers

SDKs and outside callers that interact with the service.

- [Client API](https://github.com/valitydev/hellgate/blob/master/apps/hg_client/src/hg_client_api.erl): SDK API · Consumer-facing library entry point for service calls. · `apps/hg_client/src/hg_client_api.erl`
- [Event poller](https://github.com/valitydev/hellgate/blob/master/apps/hg_client/src/hg_client_event_poller.erl): SDK poller · Client-side consumer for the event stream or follow-up work. · `apps/hg_client/src/hg_client_event_poller.erl`
- [Client invoicing](https://github.com/valitydev/hellgate/blob/master/apps/hg_client/src/hg_client_invoicing.erl): SDK helper · 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](https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_proto.erl): transport app · Transport application that exposes the service boundary. · `apps/hg_proto/src/hg_proto.erl`
- [Woody wrapper](https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_woody_wrapper.erl): rpc adapter · Adapter around RPC calls and service plumbing. · `apps/hg_proto/src/hg_woody_wrapper.erl`
- [Service wrapper](https://github.com/valitydev/hellgate/blob/master/apps/hg_proto/src/hg_woody_service_wrapper.erl): rpc service · 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](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_domain.erl): core model · Shared business abstractions and canonical domain types. · `apps/hellgate/src/hg_domain.erl`
- [Invoice handler](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice_handler.erl): workflow · Coordinates invoice lifecycle transitions and handling. · `apps/hellgate/src/hg_invoice_handler.erl`
- [Invoice logic](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice.erl): invoice domain · Invoice state and business rules. · `apps/hellgate/src/hg_invoice.erl`
- [Payment state](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_invoice_payment.erl): payment domain · Registered payments, captures, refunds, and chargebacks. · `apps/hellgate/src/hg_invoice_payment.erl`
- [Cashflow](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_cashflow.erl): cash ledger · Cash movement and flow calculations. · `apps/hellgate/src/hg_cashflow.erl`
- [Allocation](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_allocation.erl): allocation engine · Allocation and distribution logic for monetary amounts. · `apps/hellgate/src/hg_allocation.erl`
- [State machine](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_machine.erl): state engine · Machine-driven progression and transition control. · `apps/hellgate/src/hg_machine.erl`

### Routing policy

Dedicated route selection and explanation subsystem.

- [Routing](https://github.com/valitydev/hellgate/blob/master/apps/routing/src/hg_routing.erl): policy engine · Route selection logic used to decide how requests are handled. · `apps/routing/src/hg_routing.erl`
- [Route explain](https://github.com/valitydev/hellgate/blob/master/apps/routing/src/hg_routing_explanation.erl): policy explain · Explains why a route or decision was chosen. · `apps/routing/src/hg_routing_explanation.erl`

### Background workers

Asynchronous progression and reconciliation components.

- [Progressor](https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_progressor.erl): worker app · Background application for asynchronous progression. · `apps/hg_progressor/src/hg_progressor.erl`
- [Progress handler](https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_progressor_handler.erl): worker handler · Handles progressor work and advancement steps. · `apps/hg_progressor/src/hg_progressor_handler.erl`
- [Hybrid worker](https://github.com/valitydev/hellgate/blob/master/apps/hg_progressor/src/hg_hybrid.erl): worker logic · Hybrid synchronous/asynchronous processing helper. · `apps/hg_progressor/src/hg_hybrid.erl`

### Operational support

Shared behavioral and integration subsystems used by the core.

- [Proxy](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_proxy.erl): outbound adapter · Outbound proxy boundary used by the core. · `apps/hellgate/src/hg_proxy.erl`
- [Proxy provider](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_proxy_provider.erl): provider adapter · Provider abstraction behind proxy-based integrations. · `apps/hellgate/src/hg_proxy_provider.erl`
- [Limiter](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_limiter.erl): traffic control · Rate or load limiting around sensitive operations. · `apps/hellgate/src/hg_limiter.erl`
- [Retry](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_retry.erl): resilience · Retry and fallback support for transient failures. · `apps/hellgate/src/hg_retry.erl`
- [Inspector](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_inspector.erl): observability · Inspection hook for introspection and diagnostics. · `apps/hellgate/src/hg_inspector.erl`
- [Fault detector](https://github.com/valitydev/hellgate/blob/master/apps/hellgate/src/hg_fault_detector_client.erl): monitoring client · Client integration for external fault detection or monitoring. · `apps/hellgate/src/hg_fault_detector_client.erl`

## Connections

- 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.
