FinTrack

Intentionally built as a proof-of-concept for systems-thinking capability, not to solve a personal problem. Deployed live in production as proof of execution rigor.

View Live Demo ↗

The Problem & Constraint-First Thinking

Expert accountants expensive & slow. SMK/magang-level admin do data entry. Management needs accurate P&L visibility.

Operator (SMK/magang) unfamiliar with laptop/complex software. Solution: Telegram bot interface (mobile-first, familiar, low friction). Result: zero IT training needed, day-1 usable.

Prevent duplicate entry (retried webhook deliveries), unauthorized changes, fraud. Solution: an idempotency key on every Telegram delivery plus an API logic layer hidden behind the bot. Result: system enforces rules, operator cannot bypass, every change attributed to an actor.

Scope

What this reference implementation is responsible for, and where its boundaries and assumptions are — stated explicitly rather than implied.

In scope

  • Telegram-bot transaction entry — free-text parsed into structured amount, vendor, cost center
  • Single-entry running balance per account, updated atomically by a Postgres trigger on insert
  • Nightly Z-score anomaly detection (2.5σ threshold, 30-day lookback window)
  • Full audit trail — every insert/update/delete logged with an actor, whether a dashboard user or a Telegram user id
  • Idempotent webhook handling — a retried Telegram delivery is safely ignored, not double-posted
  • On-demand P&L aggregation via API route

Boundaries & assumptions

  • NOT full double-entry/GL bookkeeping — single-entry by design. The separately-deployed, actually-live FinTrack app implements genuine double-entry; this reference implementation deliberately doesn't replicate that.
  • No automatic vendor → account mapping yet — everything routes to an “Uncategorized” suspense account for manual re-coding on a dashboard.
  • No outbound Telegram alerts wired up yet — critical anomalies are logged, not pushed, pending a live bot token.
  • This is a reference implementation: never connected to live Supabase/Telegram credentials, not deployed anywhere.

Key Metrics

Manual Cycle Time

2 hours5 minutes

Anomaly Detection

Manual reviewAutomated (Z-score, 2.5σ threshold)

Update Frequency

End-of-day batchReal-time

End-to-End Flow

Transaction input, traced from the operator's message to a flagged anomaly six steps later.

01Operator sends a free-text message to the Telegram bot“Invoice #123 from Vendor A, Rp 5juta, for Cost Center XYZ”
02Telegram delivers a webhook to FastAPIHMAC-verified against a shared secret — fails closed (503) if the secret is unset, never silently accepts unverified traffic
03A regex parser extracts amount, vendor, cost centerfrom the raw message text, no NLP/LLM call needed for the common case
04Transaction inserted with actor + idempotency keyTelegram user id for attribution, Telegram update id so a retried delivery is rejected instead of double-posted
05A Postgres trigger updates the account balance and writes the audit logatomically, in the same transaction — structurally impossible to insert a transaction without it being audited
06A nightly worker computes Z-scores per accountover a 30-day window, flags anything beyond 2.5σ for human review the next morning

Solution Architecture

Frontend
Vite + React dashboard (analytics, account search, real-time P&L view)
Backend
Supabase PostgreSQL (single-entry running balance, anomaly detection)
Input Layer
Telegram Bot (Python) connected to the API
Deployment
Vercel (frontend), Railway (bot + backend logic)
Methodology
Vibe coding with Claude — AI-augmented development, not manual coding

Lessons Learned

Initially assumed Supabase's free tier was sufficient for anomaly-detection queries. At 1,000+ transactions, query latency increased. Solution: incremental Z-score calculation with a caching layer. Learning: production-level accounting systems must pre-optimize for scale, not react to it after the fact.