FinTrace ingests payment data from five sources (payments, settlements, bank feeds, fee schedules, and general ledger entries), matches them against each other using a native reconciliation engine, and uses AI agents to investigate the exceptions that come out of the matching process.
It reports what matched, what didn't, and why.
Finance teams reconcile data across payment gateways, settlement files, bank portals, and ERPs. This is largely a manual process involving spreadsheets, and it breaks down at scale. A missed discrepancy can result in an incorrect balance sheet.
FinTrace separates the work into two layers. The matching itself is handled by a deterministic engine that produces exact, reproducible results. The AI layer sits on top and handles the investigative side: pulling evidence, diagnosing root causes, and drafting resolution proposals. The AI does not decide whether a transaction matched or not.
flowchart LR
A["Raw Data\n(5 sources)"] --> B["Deterministic\nMatching Engine"]
B -->|"Matches +\nExceptions"| C[("Database +\nKnowledge Graph")]
C --> D["AI Agent\nPipeline"]
subgraph Agents ["Agent pipeline"]
D --> E["Pull evidence"]
D --> F["Re-verify numbers"]
D --> G["Classify root cause"]
D --> H["Draft corrections"]
end
Agents --> I["Human review\n& sign-off"]
The pipeline works in six stages:
- Ingest: Load payments, settlements, bank transactions, fee rules, and GL entries from CSV files into the database.
- Match: The reconciliation engine runs multi-way matching across all five sources (sub-second for the full batch).
- Flag: Transactions that don't match cleanly are flagged as one of 8 exception types, ranked by severity.
- Investigate: AI agents pull related records from the knowledge graph, re-check the calculations, and classify the root cause.
- Report: Each exception gets a forensic report with a proposed fix (journal entry, dispute memo, etc.).
- Review: A human reviews the findings and approves, rejects, or escalates. All decisions are logged.
The system tracks three things: throughput, match rate, and the full list of exceptions.
| Metric | How it's reported |
|---|---|
| Throughput | The engine processes the full batch in one pass. Each stage (database load, reconciliation, graph build) is independently timed and printed. |
| Match rate | The dashboard shows exact counts: total processed, matched, and flagged. These numbers come from the deterministic engine, not the AI. |
| Exception list | All 8 exception types are shown with severity labels. Cases that can't be closed by the agent pipeline are marked KEEP_OPEN or ESCALATE. |
| Batch runs | You can select any number of exceptions and run the agent pipeline across all of them. Each case gets its own evidence packet, verification, and report. |
| Exception | Description |
|---|---|
AMOUNT_MISMATCH |
Payment amount ≠ settlement amount |
BANK_AMOUNT_MISMATCH |
Settlement payout ≠ bank deposit amount |
DELAYED_SETTLEMENT |
Settlement exceeded the expected window (> 24h) |
DUPLICATE_SETTLEMENT |
Same transaction settled more than once |
FEE_MISMATCH |
Fees charged don't match the agreed merchant rate |
LEDGER_MISMATCH |
Debits and credits in the GL don't balance |
MISSING_BANK_TRANSACTION |
Settlement exists but no matching bank entry found |
MISSING_SETTLEMENT |
Payment was captured but never settled |
Each exception is assigned a severity level: CRITICAL, HIGH, MEDIUM, or LOW, based on the financial amount involved.
FinTrace is organized into modular components. The matching core operates deterministically without LLM intervention, while the agent layer investigates flagged discrepancies and prepares remediation actions.
The matching core is implemented in C++17 and bound to Python using pybind11. It ingests records across payments, settlements, bank statements, fee schedules, and general ledger postings. The engine indexes records into memory structures, evaluates fee formulas against contract tiers, checks transaction timing windows, and executes multi-way joins in sub-second passes. When records do not align, it classifies them into one of 8 discrepancy categories with severity rankings.
flowchart LR
subgraph Inputs ["Input Datasets"]
P["Payments"]
S["Settlements"]
B["Bank Feeds"]
F["Fee Rules"]
L["General Ledger"]
end
subgraph Core ["Deterministic Engine (C++17)"]
VAL["Validation & Indexing"]
MAT["Multi-Way Matching"]
CALC["Fee & Window Evaluation"]
end
subgraph Outputs ["Engine Output"]
OK["Clean Reconciled Records"]
EX["Flagged Exceptions (8 Classes)"]
end
Inputs --> VAL --> MAT --> CALC --> Outputs
A Neo4j 5 property graph models transaction journeys as connected entity graphs. Rather than inspecting disconnected relational rows, the graph links payments, settlement batches, bank deposits, ledger postings, merchants, and discrepancy tags into a unified lineage. Cytoscape.js visualizes these subgraphs in the browser, allowing analysts to inspect the complete lifecycle of any contested transaction.
flowchart TD
M["Merchant"] -->|CAPTURED| P["Payment"]
P -->|SETTLED_BY| S["Settlement Batch"]
S -->|DEPOSITED_AS| B["Bank Transaction"]
P -->|POSTED_TO| GL["General Ledger Entry"]
P -->|EVALUATED_BY| F["Fee Rule"]
P -->|FLAGGED_WITH| D["Discrepancy Node"]
The primary agent workflow handles batches of flagged exceptions. For each case, an evidence extraction worker queries the graph and database for related context. A deterministic verification worker re-evaluates the arithmetic, fee calculations, and timing intervals. A policy classifier identifies the root cause category, and a report generator drafts a structured forensic report with recommended journal adjustments or merchant dispute memos.
flowchart LR
EX["Flagged Exceptions"] --> EM["Evidence Materializer\n(Extracts Subgraph & Records)"]
EM --> VW["Verification Worker\n(Deterministic Math Check)"]
VW --> PC["Policy Classifier\n(Root Cause Assessment)"]
PC --> RG["Report Generator\n(Adjustment Proposal / Memo)"]
RG --> PKG["Forensic Case Packet"]
A LangGraph state machine provides conversational investigation across the transaction history. The agent runs a three-node loop: retrieve context from the property graph and database, formulate an answer grounded strictly in retrieved records, and validate statements against evidence. If supporting evidence is absent or contradictory, the agent reports that the claim cannot be verified rather than guessing.
flowchart LR
Q["Analyst Query"] --> RET["Context Retrieval\n(Graph + Relational DB)"]
RET --> SYN["Answer Synthesis\n(LLM Formulation)"]
SYN --> VAL{"Evidence Verification\n(Matches Ground Truth?)"}
VAL -->|Verified| ANS["Grounded Answer with Sources"]
VAL -->|Unverified| RET
Automated recommendations require human review before accounting entries are finalized. Finance teams inspect the evidence packet and proposed resolution in the case management interface. Reviewers can approve journal adjustments, mark items within tolerance as false positives, generate formal vendor dispute notices, or escalate complex discrepancies to senior staff. Every action, reviewer decision, and timestamp is stored in an audit log.
flowchart TD
PKG["Forensic Case Packet"] --> REV["Review Queue"]
REV --> ACT{"Controller Decision"}
ACT -->|Resolve| ADJ["Post Adjustment Entry"]
ACT -->|Tolerance| FP["Mark False Positive"]
ACT -->|Dispute| DIS["Generate Vendor Dispute Memo"]
ACT -->|Escalate| ESC["Route to Senior Controller"]
ADJ & FP & DIS & ESC --> AUD[("Immutable Audit Trail")]
An analytics interface that converts plain text questions into SQL queries against the PostgreSQL database. Generated queries are parsed with sqlglot to enforce read-only constraints: only SELECT queries are permitted, schema modifications and data mutations are blocked, and query timeouts are enforced. Results are returned in tables with an explanation and an interactive ER diagram of the underlying database schema.
flowchart LR
NL["Natural Language Query"] --> GEN["SQL Generator"]
GEN --> AST{"AST Guard (sqlglot)\nStrict Read-Only"}
AST -->|Mutation / Invalid| REJ["Query Blocked"]
AST -->|Valid SELECT| DB[("PostgreSQL")]
DB --> RES["Tabular Data & Explanation"]
- Docker and Docker Compose (v20.10+)
- Python 3.11+
- Node.js 18+ and npm
git clone https://github.com/HarshitR2004/fintrace.git
cd fintrace
cp .env.example .env
# Add your OPENROUTER_API_KEY and OPENROUTER_MODEL to .env
# Start PostgreSQL and Neo4j
docker compose up -d
# Set up Python backend and run reconciliation
cd backend
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
python ingest_data.py --data-dir ../data
python run_server.pyIn a second terminal, start the frontend:
cd frontend
npm install
npm run devOpen http://localhost:3000 in your browser.
| Service | URL | Login |
|---|---|---|
| Web app | http://localhost:3000 |
n/a |
| API | http://localhost:8000 |
n/a |
| API docs | http://localhost:8000/docs |
n/a |
| Neo4j browser | http://localhost:7474 |
neo4j / fintrace_password |
| Neo4j bolt | bolt://localhost:7687 |
neo4j / fintrace_password |
| Postgres | localhost:5432 |
postgres / fintrace_password |
Dashboard (/): Shows total volume, discrepancy amount, active exceptions, and fee variance. You can filter transactions, click into any one to see its transaction graph, view the evidence packet, or ask the Q&A agent about it. The "Investigation Cases" tab is where human decisions are recorded.
Exception Batch (/exception-batch): Select exceptions (one or many), configure the agent pipeline, and run it. A live terminal shows agent progress. There is a 3D view of exception clusters and downloadable forensic reports.
SQL Studio (/analytics): Ask questions about the data in natural language. The schema is shown as an ER diagram. The agent generates SQL, validates it, runs it, and explains the results.
Backend: C++17 + pybind11 (engine), Python 3.11+ / FastAPI / Uvicorn (API), PostgreSQL 16 + Neo4j 5 (storage), LangGraph + LangChain (agents), sqlglot (SQL safety)
Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS 4, Framer Motion, Cytoscape.js, React Three Fiber