billmalea/mpesa-credit-scorer
Domain:
socioeconomicRecord type:
software
Creator:
bil
Host:
# M-Pesa Credit Scorer
**TTACS Management Consulting** — deterministic M-Pesa statement underwriting with a core FlexVertex audit graph.
License: GNU Affero General Public License v3.0 (AGPL-3.0).
---
## What this is
A Java 21 credit scorecard that:
1. **Ingests** Safaricom M-Pesa statements (CSV export, SMS text, or password-protected PDF)
2. **Extracts** cash-flow features (verified inflow, tenure, volatility, salary/business patterns, round-tripping)
3. **Evaluates** eligibility rules from `policy.yml` (optionally overlaid from a lender policy PDF)
4. **Scores** 0–100 and recommends a max loan
5. **Persists** Applicant → Decision → Finding → Rule → PolicyChunk in FlexVertex for reconstructable audit
Scoring is **local and deterministic**. FlexVertex holds the audit / provenance graph for every run — Iron Edition must be up.
---
## Architecture
```text
┌─────────────┐ ┌──────────────────┐ ┌────────────────┐ ┌────────────┐
│ Statement │────▶│ FeatureExtractor │────▶│ RuleEvaluator │────▶│ Scorecard │
│ CSV/PDF/SMS │ │ │ │ HARD / SOFT │ │ 0–100 + │
└─────────────┘ └──────────────────┘ └────────────────┘ │ max loan │
└─────┬──────┘
│
┌───────────────▼───────────────┐
│ CreditDecision (JSON / UI) │
└───────────────┬───────────────┘
│ required audit path
┌───────────────▼───────────────┐
│ FlexVertexDecisionStore │
│ TTACS / Scorer / MpesaCredit │
└───────────────────────────────┘
```
### Decision pipeline
| Stage | Module | Responsibility |
|-------|--------|----------------|
| Ingest | `StatementIngestion`, parsers | Detect format; unlock PDF; parse transactions + identity |
| Features | `FeatureExtractor` | Monthly verified inflow, surplus, CV, patterns, fraud signals |
| Rules | `RuleEvaluator` | Eligibility with HARD_FAIL → DECLINED, SOFT_REFER → REFERRED |
| Score | `Scorecard` | Weighted points, caps by verdict, max loan vs requested |
| Audit | `DecisionStore` | FlexVertex au …