Settly is a network optimization and reconciliation engine for banks, payment aggregators, and corporates. It is designed to be a "smart clearing brain" that finds the minimal settlement paths between multiple parties, drastically reducing reconciliation overhead and freeing up locked liquidity.
This repository contains the Minimum Viable Product (MVP) of Settly, featuring a FastAPI backend for the core reconciliation logic and a React frontend for user interaction.
In complex financial ecosystems like Egypt and Saudi Arabia, businesses face significant operational pain from financial reconciliation:
- Multi-Channel Mismatches: Transactions from wallets, POS, cards, and bank transfers rarely reconcile cleanly, leading to discrepancies.
- Liquidity Lockups: Delays in settlement mean millions of dollars can be "frozen" daily, impacting cash flow.
- Human & Spreadsheet Fatigue: Manual reconciliation is slow, error-prone, and relies on fragile spreadsheets and overworked back-office teams.
Settly solves this nasty back-office problem by automating and optimizing the reconciliation process.
- Dual File Upload: Upload ledgers and statements in CSV, XLSX (up to 20 sheets), or bank-style PDFs and reconcile them side-by-side.
- Smart Column Mapping: Automatically detects and suggests mappings for transaction ID, amount, and date columns, with a manual override.
- High-Speed Reconciliation Engine:
- Normalization: Cleans and standardizes inconsistent data formats for IDs, amounts, and dates.
- Exact Matching: First pass to instantly match identical transactions.
- Fuzzy Matching: A sophisticated second pass that identifies likely matches based on:
- Time Tolerance: Matches transactions within a configurable time window (e.g., 120 seconds).
- Amount Tolerance: Accounts for small differences due to fees or FX rates.
- ID Truncation: Matches partial or truncated reference IDs.
- Simple Dashboard: Visualizes the reconciliation results with a clear percentage breakdown.
- Exception Reporting & Exports: Download matched+unmatched CSVs, filtered CSVs from the UI, and the exception list for audit trails.
- Backend:
- Framework: FastAPI
- Core Logic: Polars (for high-performance data manipulation) & RapidFuzz (for string similarity matching).
- Server: Uvicorn
- Frontend:
- Framework: React (with Vite)
- API Client: Axios
- Charting: Recharts
- Language: Python 3.10+, JavaScript (ES6+)
- Python 3.10+ and
pip - Node.js v18+ and
npm
# Navigate to the backend directory
cd backend
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows, use: .\.venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run the development server
uvicorn app:app --reload --port 8000The backend API will now be running at http://localhost:8000.
# Open a new terminal and navigate to the frontend directory
cd frontend
# Install dependencies
npm install
# Run the development server
set VITE_API_BASE=http://127.0.0.1:8000 # PowerShell
npm run devThe frontend application will now be running at http://localhost:5173 (or another available port). Open this URL in your browser to use the application.
If you change backend host/port, update VITE_API_BASE before running dev/build.
- Bank PDF parsing: PDFs are parsed via layered heuristics that extract deals, accounts, currencies, amounts, and dates even when the file is plain text. If no perfect table exists, Settly still provides structured columns such as
deal,account,entry_type,currency, andamount. - Multi-sheet Excel ingestion: Up to 20 sheets are concatenated with a
__sheetcolumn so you can reconcile complex ERPs without pre-merging files. - Robust date/amount normalization: Mixed formats like
1-Jul-25,03SEP25, or2025-06-01are normalized to strings and parsed during matching to prevent crashes. - Large uploads: Frontend timeout increased (90s) plus backend error handling ensures big PDFs finish processing.