Walkthrough

How InsightStack works

A step-by-step trace from CSV upload to AI-generated spending recommendations.

Try it yourself →Learn more

Flow

User flow

01

Register & login

Create an account with email + password. Passwords are hashed with bcrypt. A JWT is issued and stored client-side for subsequent requests.

POST /api/auth/register → POST /api/auth/login
02

Create a dataset

Name your dataset — e.g. 'Jan 2026 Expenses'. This creates a Dataset row in Postgres with status UPLOADED.

POST /api/datasets
03

Upload a CSV

Upload a CSV with date, description, category, amount columns. The server parses every row, validates fields, and batch-inserts Transaction rows. Status advances to PARSED.

POST /api/datasets/:id/upload
04

View metrics

The metrics endpoint aggregates income, expenses, net savings, savings rate, top categories, and monthly breakdown. Results are cached as a MetricSnapshot for 1 hour.

GET /api/datasets/:id/metrics
05

Generate AI insights

Transactions are PII-redacted, then passed to the FinanceAI engine — BM25 retrieval, linear regression, expert rules, and NLG composition all run in-process. Results are Zod-typed and saved to the database.

POST /api/datasets/:id/insights
06

Read your insights

Structured output: summary text, top spending categories with reasons, anomaly transactions, and 3 personalised recommendations — all rendered as expandable cards.

GET /api/datasets/:id/insights

Engineering

Engineering highlights

Production-grade details that are invisible when they work.

PII Redaction

Emails, phone numbers, NRICs, and long digit strings are scrubbed from transaction descriptions before any processing.

Zero External API

FinanceAI runs entirely in-process — BM25 retrieval, linear regression, expert rules, and NLG. No API key, no latency, no cost per call.

Daily Quota

Each user has a 30-insights-per-day cap enforced via AuditLog counting.

Cache Layer

Identical data hashes skip recomputation entirely and return the cached insight. Metrics snapshots cache for 1 hour.

CSRF Protection

Cookie-authenticated requests require a matching CSRF header. Bearer token requests bypass this (standard SPA pattern).

Audit Log

Every upload, insight generation, rename, and delete writes an immutable AuditLog row with IP and user-agent metadata.

Format

CSV format

Any bank or credit card export works. The parser expects four columns:

Download sample CSV — try it right now
date,description,category,amount
2026-01-02,McDonalds,Food,-9.50
2026-01-22,Salary,Income,1200.00
2026-01-25,Phone bill,Utilities,-25.00
2026-02-01,Netflix,Entertainment,-15.99
  • date — any parseable date string
  • description — merchant or transaction label
  • category — e.g. Food, Transport, Income, Utilities
  • amount — negative for expenses, positive for income

Ready to see your own spending insights?

Upload a CSV and get AI analysis in under a minute.

Get started for free →