emeraldev/paypredict

PayPredict is a pre-collection risk scoring API and ops dashboard for instalment lenders in Africa. It predicts which upcoming loan/BNPL collections will fail before the collection is attempted, and recommends actions to improve recovery rates. # PayPredict Pre-collection risk scoring for African lenders. Predicts which instalment collections will fail before they're attempted. ## Overview PayPredict is an API + ops dashboard that scores upcoming loan/BNPL collections by risk of failure. It serves two markets: - **South Africa** — card-on-file and debit order collections - **Zambia** — mobile money wallet auto-deductions The scoring engine uses configurable heuristic factors (7-8 per market) that produce an explainable risk score. Every scored collection and its outcome creates training data for future ML models. ## Repository structure ``` paypredict/ ├── CLAUDE.md # AI assistant context for this project ├── README.md # This file ├── docker-compose.yml # Local dev: Postgres + Redis ├── api/ # FastAPI backend (Python) │ ├── app/ # Application code │ ├── alembic/ # Database migrations │ ├── tests/ # Test suite │ ├── Dockerfile │ └── pyproject.toml ├── dashboard/ # Next.js frontend (TypeScript) │ ├── src/ │ └── package.json └── docs/ # Project documentation ├── business-context.md ├── data-model.md ├── factors.md ├── api-reference.md └── development-guide.md ``` ## Quick start ```bash # Start local infrastructure docker-compose up -d # Setup API cd api python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" alembic upgrade head python -m app.seed uvicorn app.main:app --reload # Test it curl -X POST localhost \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "customer_id": "test_cust_1", "collection_id": "test_inst_1", "collection_amount": 500.00, "collection_currency": "ZAR", "collection_due_date": "2026-04-15", "collection_method": "CARD", "customer_data": { "total_payments": 10, "successful_payments": 7, "last_successful_payment_date": "2026-03-28", "card_type": "debit", "card_expiry_date": "2026-08-01" …