PaytmFlow

A deterministic financial-journey recovery platform: guided document/form workflows across six financial products, backed by a local-or-cloud Document AI pipeline, a human review queue, and event-driven notifications.

Status: Hackathon/demo prototype, actively deployed. Live frontend: https://paytmflow-frontend.vercel.app Live backend health: https://paytmflow-backend.onrender.com/api/v1/health API docs: https://paytmflow-backend.onrender.com/docs License: Not currently specified in this repository.

---

Overview

PaytmFlow is a guided workflow engine for financial products — a personal loan, a health insurance enrollment, periodic KYC re-verification, a co-branded credit card, a savings account, or a mutual fund investment. A user picks one of six journeys, and the system tracks exactly which requirements are still outstanding, explains why each one is blocked, recommends a single next action, and interprets any document the user uploads through a real document-intelligence pipeline before deciding whether that document actually satisfies the requirement.

It solves this by keeping two concerns strictly separate: an AI/OCR layer that interprets evidence (what kind of document is this, what does it say, how confident is that reading), and a deterministic engine, driven entirely by per-journey YAML configuration, that decides whether a requirement is satisfied and writes the resulting state. The AI layer never has write access to journey state — it can only produce a proposal that the deterministic engine independently validates.

When something can't be resolved deterministically — two documents that disagree on an amount, evidence that's plausible but under the confidence threshold — the case is routed to a lightweight Human Review Center rather than guessed at by a model, and outbound events (Slack for reviewers, email for customers) are dispatched through a real n8n Cloud workflow at each meaningful lifecycle point.

It's built for two overlapping audiences: an applicant moving through a financial workflow who needs to know what's missing and why, and a reviewer who needs a queue of exactly the cases that genuinely require a human decision — not every case.

Problem

Financial workflows built around document collection tend to fail users in the same three ways:

• It's unclear what's missing. A rejected or pending application rarely explains, in plain language, which specific requirement is blocking progress.
• It's unclear why. A generic "verification failed" message gives no actionable next step.
• It's unclear what happens after submission. A document goes into a queue with no visibility into whether it was even the right kind of document, or whether a conflicting earlier submission is quietly overriding it.

The common underlying cause is that document interpretation and workflow decision-making are usually the same step, often behind an opaque or fully-manual process, so there's no way to trust a decision or to reproduce it later.

Solution

PaytmFlow separates interpretation from decision at the architecture level, not just as a convention:

1. A document is ingested and validated by content (magic bytes), not by its declared name or extension.
2. It's run through a Document AI pipeline — either a from-scratch local pipeline (OCR + trained classifier + rule-based extraction) or an optional real cloud provider (Sarvam AI) — which produces a classification, extracted field values, and a confidence score.
3. That output is handed to a deterministic engine as a proposal only. The engine — pure, I/O-free, and enforced as such by an import-linter contract — evaluates it against the journey's YAML-defined dependency graph and confidence thresholds, and is the only code path allowed to advance journey state.
4. If the engine can't resolve something on its own (a conflict, a borderline confidence score), the case goes to a Human Review Center instead of being decided automatically.
5. Real lifecycle events (evidence uploaded, review needed, case resolved, journey completed) are dispatched to an n8n Cloud workflow, which notifies reviewers on Slack and customers by email — asynchronously, and never in a way that can block or fail the request that triggered it.

Key Features

Six configuration-driven journeys

Lending, Insurance, KYC, Credit Card, Account Opening, and Investment all share one frontend and one backend engine. Each journey's required fields, dependency graph, available actions, and evidence mappings live in a YAML manifest (backend/app/packs/manifests/) — there is no if journey_type == "LENDING" branching anywhere in the engine or the UI.

Deterministic workflow engine

Journey state is a set of typed fields (SATISFIED, BLOCKED, AMBIGUOUS, ...) connected by an explicit dependency graph. Every mutation must supply the snapshot version it expects; a stale or conflicting mutation is rejected outright. Snapshots are immutable and append-only, enforced by database triggers, not just application code.

Dual Document AI providers

A local, from-scratch pipeline (PyMuPDF + Tesseract OCR, a TF-IDF/logistic- regression classifier trained per journey, rule-based field extraction with OCR-noise correction) runs with no external API. An optional cloud provider, Sarvam AI, can be swapped in by configuration for Document AI, speech-to-text, translation, and chat — with automatic, logged fallback to the local pipeline on any failure.

Human Review / Exception Resolution Center

Cases the deterministic engine can't resolve on its own are queued, claimable (with optimistic-lock protection against two reviewers grabbing the same case), and resolvable — resolution re-enters the same deterministic mutation path a customer's own action would use, never a separate write path. An optional AI-generated case summary is available as an advisory aid, always labeled as such.

This is the beginning of the README. Read the rest at the original. Read the full README ↗