Debts Hub

The problem

Balady’s service-issuance flow needs to verify a citizen has no outstanding debt before granting a licence. The original integration relied on REST callbacks from the payment-confirmation flow. Under load, synchronous callbacks offered weak delivery guarantees — a class of dropped or duplicated confirmation that the design needed to rule out.

The architecture

A centralized debts substrate sitting between the licence-issuing services and the payments domain. Internally it is a small ensemble of services split across a synchronous query/inquiry surface and a set of background workers, backed by a shared store and an event bus.

Eligibility is fully data-driven: operators configure which debt categories block which services and at what threshold, and the gate re-evaluates an identity as bills are paid, issued, or cancelled.

Drove the revision that replaced REST callbacks with event-driven (RabbitMQ) consumption for the payment-confirmation flow, giving reliable, replayable delivery of confirmations.

Pattern view — an eligibility gate that consumes confirmation events; a scheduled reconciler self-heals, with a decoupled analytics pipeline.

Trade-offs (ADRs)

• Scheduled scan over an always-on payment listener — scanning only registered identities on a schedule keeps system load focused, at the cost of slight eligibility latency: an explicit consistency-vs-overhead trade-off
• A single replicated liability view backs all eligibility queries, so consuming services read consistent debt truth from one source rather than fanning out to multiple upstream systems
• BI/ETL replication into a separate analytics store — a decoupled pipeline avoids coupling the operational hub to analytics workloads

Outcome

A whole class of dropped-confirmation failures designed out. The RabbitMQ-based substrate is now the contract for all consuming services in the Balady ecosystem.