Logic Leap Collections — Debt Collection System

Overview

A Django‑based collections platform: debt portfolios assigned to collectors, client and company records, payment plans and settlements, commissions and targets, approval chains with a full audit trail, and automated messaging — with bulk imports processed through Celery and Polars, and a React dashboard for live monitoring.

01The challenge

A collections agency is hired by creditors — a telecom, say — to collect overdue debts. The file arrives as an Excel of hundreds of thousands of rows. Importing it the usual way (row by row through the ORM) takes hours and stalls the system, and this is the first step of every new engagement — so its slowness makes everything slow.

Then distribution: debts are allocated to collectors against percentage targets. Simple round-robin punishes whoever holds the hard files and piles work on some. Fair allocation needs exact proportional splitting that neither loses nor duplicates a row.

Then money: commission is computed over amount bands, at rates with effective dates, across three levels (collector, supervisor, manager) — and each payment may need multi-step approval before it counts.

The system is Arabic-first and right-to-left, and needs live notifications for approvals.

02What we built

Import was built as a high-performance path: the file is read and processed vectorised through polars and PyArrow, then loaded into PostgreSQL with COPY FROM STDIN rather than row-by-row inserts — targeting around 71,000 rows per second. It runs through explicit phases — upload, preview, column mapping, start — executing on a dedicated heavy Celery queue with a background job tracking progress, and failed rows download as a CSV instead of failing the whole batch.

Distribution does not use round-robin: it splits proportionally using the Hamilton largest-remainder method to guarantee an exact split with nothing lost or duplicated, then picks the least-loaded collector — so fairness is structural rather than discretionary. Redistribution rotates neglected debts while keeping an assignment history.

The architecture is uniformly organised: every app puts its logic in a service layer returning a ServiceResult, views stay thin, and every response is wrapped in one envelope — so behaviour is predictable across 394 endpoints.

Money is modelled explicitly: commission rates over amount bands with effective dates, a collected-totals ledger per level, and a monthly commission run computing from totals against targets. Approvals are a configurable engine (template → ordered steps → instance) that notifies approvers live over WebSocket.

The React 18 + TypeScript front end is fully Arabic and RTL, with a mock mode that lets it be developed with no backend running.

03The outcome

Importing a large portfolio became a minutes-long operation with a progress indicator instead of hours that stall the system — the very step that used to delay the start of every new engagement.

Distribution became explainable: a collector knows why they received this many, and management knows the split is exact rather than approximate.

Commission is computed from a totals ledger and rules with effective dates, so a disagreement about numbers became a record review rather than a negotiation. All of it is documented across nine reference documents that cite the code by line — including an explicit risk register of known gaps.