FinFinePro: Implemention writeup
breakdown of how the backend, data pipelines, sandbox, and AI agents used to make FinFInePro
I just spent a hackathon building FinFine Pro - an autonomous cash flow & solvency intelligence engine for Indian MSMEs.
This is a breakdown of how the backend, data pipelines, sandbox, and AI agents were actually designed, what AWS primitives we tied together, and every painful engineering roadblock we hit while trying to keep idle cost strictly at $0.00/hr.
1. The High-Level Architecture (The 30,000-Foot View)
Before diving into the broken builds, here’s how the whole system connects:
[MSME Browser / Next.js 15] │ ├── (1) Direct Upload ────────► [Amazon S3: public/] │ │ (ObjectCreated) │ ▼ │ [Amazon EventBridge] │ │ │ ▼ │ [AWS Step Functions] │ ├── Task 1: [Document Extractor Lambda] ──► [Amazon Bedrock (Multimodal)] │ └── Task 2: [Ingestion Normalizer Lambda] ──► [Amazon DynamoDB (13 Tables)] │ ▲ ├── (2) GraphQL Queries/Mutations ──► [AWS AppSync] ───────────────────────────────────┤ │ │ ├── (3) Chat /api/chat ─────────────► [FastAPI / Strands Agent Lambda] ────────────────┤ │ ├── S3 Session Snapshots (agent-sessions/) │ └── Private Math RPC ──► [Python Code Executor Sandbox] │ ├── (4) Probabilistic Forecast ─────► [AWS SageMaker Serverless (Chronos-Bolt)] │ └── Local Quantile Fallback Engine │ └── (5) Daily Tax Cron ─────────────► [EventBridge Schedule] ──► [Statutory Advisory Lambda]Everything runs inside
ap-south-1 (Mumbai) so data doesn't cross borders, and every single compute element scales to absolute zero.
2. The Core Subsystems & Pain Points
A. Document Ingestion: Step Functions + EventBridge (Why synchronous uploads are a trap)
- What we built: MSME financial docs (messy GST challans, POS slips, scanned bank statements) are dropped straight into S3 via presigned uploads. S3 emits an
ObjectCreatedevent to EventBridge, triggering a 2-step Step Functions state machine:
- Document Extractor Lambda (Node.js 22 / 1024MB): Pulls the binary, calls Amazon Bedrock (Claude 3.5 Sonnet / Nemotron Vision), and extracts tabular records, transaction dates, balances, and parties.
- Ingestion Normalizer Lambda (Node.js 22 / 512MB): Parses UPI reference strings, normalizes PAN/GSTIN IDs, calculates priority weights for creditors, and batch-writes to DynamoDB.
- The Pain Point: Early on, we tried doing OCR parsing synchronously in a Next.js API route. Huge mistake. 5-page PDF bank statements with vision models take 20–45 seconds to parse. API gateways timed out, frontend connections dropped, and retries caused duplicate writes. Moving to EventBridge + Step Functions with exponential backoff decoupled the UI completely. The user gets an immediate upload ack, and the UI reacts when DynamoDB updates via AppSync.
B. The Decision Core: Zero-Hallucination Agent + Python Code Sandbox
- What we built: The agent backend is a containerized FastAPI app running on AWS Lambda behind a Lambda Function URL with IAM/Cognito auth. When an MSME asks a complex question like "What happens to my runway if my top client delays payment by 20 days?", the LLM is never allowed to do math.
- The LLM reasons about what data is needed and issues tool calls.
- The Agent fetches live balances & obligations from DynamoDB and generates a transient sanitized CSV.
- The Agent calls
lambda:InvokeFunctiononfinfine-code-executor- an isolated Python 3.12 sandbox loaded with NumPy, pandas, SciPy, and linear programming tools.
- The sandbox runs deterministic solvency simulations (Days-to-Zero, buffer breach dates) and returns pure JSON numbers back to the agent for natural language summarization.
- The Pain Point: LLMs are terrible accountants. When asked for compound runway degradation under GST outflow, Claude/GPT will hallucinate plausible-looking numbers with total confidence. Sandboxing the math into a sub-100ms ephemeral Python Lambda turned financial calculations from "guesswork" into deterministic code execution.
C. Data Layer: Amplify Gen 2 + AppSync + DynamoDB
- What we built: 13 canonical DynamoDB tables (
Transaction,Obligation,CashPositionSnapshot,SupplierProfile,MerchantFinancialSettings, etc.) managed via AWS Amplify Gen 2 TypeScript schema definitions.
- The Pain Point: Amplify Gen 2 is cool because your schema is pure TypeScript CDK code, but debugging IAM policy generation when mixing custom CDK Lambdas with Amplify-managed DynamoDB tables was brutal. We had to carefully grant fine-grained
dynamodb:BatchWriteItemanddynamodb:Querypermissions inbackend.tsso custom Lambda extractors and the Docker agent could talk to AppSync-generated tables without running into cryptic STS 403 Forbidden errors at 3 AM.
D. Forecasting: SageMaker Serverless (and the Cold Start Reality Check)
- What we built: Probabilistic cash flow forecasting using Amazon's Chronos-Bolt time series model. It projects P10 (conservative / Value-at-Risk), P50 (median), and P90 (optimistic) balances, factoring in Indian statutory tax drain dates (like the 20th GSTR-3B deadline) and festive demand spikes (Diwali/Dussehra).
- The Pain Point: SageMaker Serverless is amazing for zero-dollar idle costs, but a cold start on a 2GB container running deep learning weights can take 8–15 seconds on the first invoke. In a hackathon demo, 15 seconds of silence feels like 15 years. We solved this by building an Embedded Quantile Fallback Engine directly into the client dispatcher (
sagemaker-forecast-client.ts). It attempts the SageMaker endpoint first; if it times out or is cold, it instantly falls back to a deterministic local quantile simulation without degrading the UI.
E. Scheduled Intelligence: EventBridge Daily Tax Cron
- What we built: A lightweight Node.js cron Lambda (
statutory-advisory-cron) triggered every 24 hours by EventBridge. It compares live liquid cash (CashPositionSnapshot) against upcoming statutory dues (Obligation), flags buffer breach risks 5–7 days before statutory tax dates (e.g. TDS on the 7th, GST on the 20th), and writes alerts intoStatutoryAdvisory.
- The Pain Point: Simple, but critical. MSMEs don't fail because they aren't profitable; they fail because statutory deadlines freeze their working capital unexpectedly. Making this an autonomous daily background job rather than something that only runs when the user logs in was essential.
3. The Security & Multi-Tenancy Boundary
- Cognito Auth: Client authentication uses Amazon Cognito User Pools issuing signed JWTs with custom tenant claims.
- Server-Side Tenant Enforcement: The tenant ID (
msme-001) is locked on the server side - client requests cannot spoof tenant IDs to read another merchant's books.
- Storage Isolation: Clients only get scoped presigned S3 URLs to
public/for uploads. Theagent-sessions/directory (where conversation history and financial artifacts live) is completely inaccessible to browser clients and only readable by the Agent Backend execution role.
4. Final Thoughts / Tech Summary
Layer | Technology | Why We Picked It |
|---|---|---|
Frontend / Edge | Next.js 15 App Router + Amplify Hosting | React Server Components + real-time dashboard |
Auth | Amazon Cognito User & Identity Pools | Zero-maintenance JWT auth & scoped IAM vending |
Orchestration | AWS Step Functions + EventBridge | Bulletproof async retry logic for document OCR |
Vision / OCR | Amazon Bedrock (Claude / Nemotron) | Multimodal extraction from messy Indian bills & slips |
Decision Core | FastAPI + Strands Agent on Lambda | Agentic tool loop with custom function URLs |
Compute Sandbox | Python 3.12 Lambda (NumPy/Pandas/PuLP) | Zero-hallucination deterministic math |
Database | DynamoDB (13 tables) via AppSync GraphQL | Sub-10ms operational queries, zero maintenance |
ML Inference | SageMaker Serverless (Chronos-Bolt) | Scale-to-zero probabilistic time series forecasting |
Building fully serverless means you spend 70% of your time wrestling IAM policies, timeouts, and asynchronous event boundaries. But when it clicks, you get an architecture that can process invoices, run linear programming runway simulations, forecast festive cash flows, and alert on tax deadlines - while costing literally $0 when nobody is using it.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article