All work Case study 03 / 04

FlowSight

Behavioral financial intelligence for people who already know their numbers — built on data you bring yourself, never a bank connection.

Type
Web app + desktop companion
Status
Core complete, active
License
MIT
Stack
Spring Boot 3.5 · Java 17 · PostgreSQL 16 · Flyway · Next.js 15 · TypeScript · Tauri 2
Links
Source
01 — Context

Most expense trackers stop at what you spent.

They answer how much went to food this month. They rarely answer the questions that change behaviour: is my spending drifting upward, which commitments could I quietly retire, and what does this EMI cost me in flexibility over ten years?

The gap is behavioural and consequential, not transactional. And because FlowSight never connects to a bank — you bring a CSV export, a manual entry, or a photo of a receipt — the first problem is making imported data trustworthy at all.

02 — Approach

One normalized record, many focused engines.

Every source is normalized into a single transaction record, and every analytical surface — recurring detection, leak detection, behavioural insights, decision simulation, reports — reads from that one source of truth.

Machine extraction is a step in the pipeline, not the pitch. A receipt photo produces a draft; nothing becomes a transaction until the user confirms an editable, prefilled form. Findings are framed as observations, not judgments.

ingest          CSV · manual · receipt
  → normalize   strip UPI / IMPS / NEFT refs and noise
  → categorize  keyword match + confidence
  → transaction record
      ├ analytics          ├ recurring detection
      ├ leak detection     ├ simulation baseline
      └ insights & reports
03 — Architecture

Two clients, one backend, one schema authority.

FlowSight architecture A Next.js web app and a Tauri desktop companion call a Spring Boot backend over HTTPS with JWT. Inside the backend, requests pass through controllers, a security layer with the JWT filter, refresh rotation, rate limiter and audit log, then services and analytical engines, then JPA repositories into PostgreSQL with Flyway migrations V1 to V14. Services also send receipts to an OCR microservice backed by a Groq vision model, with a Tesseract fallback, and send password-reset email through Gmail SMTP, Brevo or Resend. Next.js 15 web appZustand · React Hook Form · Zod Tauri 2 desktopshares the web design system HTTPS · JWT Spring Boot 3.5 · /api/v1 Controllers SecurityJWT filter · refresh rotation · rate limiter · audit log Services & analytical enginesanalytics · recurring · leaks · simulation · insights Spring Data JPA repositories multipart reset PostgreSQL 16Flyway V1–V14 Receipt OCRGroq vision LLM EmailSMTP · Brevo · Resend Tesseract fallback
Fig. 1Hibernate validates against the migrations and never generates schema: Flyway is the only authority.
FlowSight's Review receipt screen: merchant, total amount, transaction date and category prefilled from a scanned receipt, with Confirm and save and Enter manually instead buttons.
Fig. 2Review-first: OCR fills the form, the user saves it.
04 — Engineering

Making imported data trustworthy.

  1. Header detection, not per-bank parsers

    CSV import maps columns by alias — Date / Value Date, Narration / Particulars, Debit / Withdrawal / Money Out, Dr/Cr type columns, running balance — instead of carrying one parser per bank.

  2. Balance-only statements, reconstructed

    When a file carries no amount column at all, amounts are rebuilt from running-balance deltas, with confidence scoring and warnings.

  3. One bad row never fails the batch

    Per-row error recovery. A row whose amount can’t be resolved is reported as an error, never silently coerced to zero.

  4. Catching the classic OCR mistake

    An amount validator cross-checks line items and scores candidate labels, catching the case where a subtotal, VAT or GST line is read as the grand total — and assigns a confidence tier that drives an explicit warning.

  5. Sessions that notice theft

    Fifteen-minute access tokens with rotating fourteen-day refresh tokens, stored only as SHA-256 hashes and consumed on use. Replaying a spent token revokes every live session for that user.

  6. Exports that can’t attack the accountant

    Leading =, +, -, @, tab and CR are neutralized in free-text CSV columns, so an export can’t execute as a spreadsheet formula (CWE-1236). The audit log is written in a REQUIRES_NEW transaction so it survives the caller’s rollback.

05 — Tradeoffs

What I chose, and what it cost.

Why no bank connection?
FlowSight never reaches into bank infrastructure: you bring the data. That keeps a whole class of integration out of the system, and moves the hard problem to ingestion — which is why ingestion gets header detection, balance reconstruction and per-row recovery rather than trust.
Why is OCR review-first instead of automatic?
Vision models misread totals; the subtotal-for-total mistake is common enough to have its own validator. Every engine reads the same record, so one wrong number saved silently would skew all of them. A draft the user confirms doesn’t.
Why rate-limit in Postgres?
So the limits hold across instances and survive restarts with the database the system already has — fixed-window counters, shared by every backend instance.
Why are web tokens still in localStorage?
It is a known limitation, and documented as one: localStorage is exposable to XSS. The fifteen-minute access-token lifetime bounds the blast radius. Moving to httpOnly cookies needs CSRF handling, and is on the roadmap rather than half-done.
Why a desktop app at all?
A Raycast-style popup for quick capture and top signals. It reuses the backend, the DTO types and the web app’s design system through an alias, so it adds a surface without duplicating logic — the backend needed only two additive changes for it.
FlowSight's decision simulator modelling a vehicle loan: monthly, yearly, five-year and ten-year impact, and a financial flexibility score that drops from 82 to 63.
Fig. 3The decision simulator, projected against the user’s last three months and active recurring patterns.
06 — Results

What exists today.

AreaState
Engines — analytics, recurring, leaks, insights, simulation, reportsimplemented
Recurring cadence tiers, weekly → annual5
Brand-alias map for merchant identity80 entries
Schema migrations, validated at bootFlyway V1–V14
Tax sections detected, financial-year aware80C · 80D · 80E
Responsive web client, down to320 px

CI builds and tests the backend against a live Postgres, type-checks, lints and builds the frontend, and builds the Docker images. Planned, not built: httpOnly-cookie sessions, cloud receipt storage (uploads are ephemeral on the current host), bank-SMS parsing, and operational monitoring.