Ejimjim/cashtrack

Cash-Flow Management Information System for micro-enterprises in Nigeria # CashTrack CashTrack is a Cash-Flow Management Information System (MIS) designed to support financial decision-making among micro-enterprises in Nigeria. It is a research prototype built for a Master's thesis. The system lets a trader record sales and expenses by typing plain-language messages to a Telegram bot (e.g. *"sold rice 3500"* or *"paid transport 800"*). An LLM (OpenAI API) interprets each message, extracts structured transaction data, and persists it to a SQLite database. The bot replies with immediate confirmation and daily totals. A separate mobile-first React dashboard reads the same database through a REST API, providing date-grouped transaction history and weekly financial decision-support insights. --- ## Key Features - **Conversational transaction capture** via Telegram — no forms, no menus - **Natural-language interpretation** using the OpenAI API (GPT-4o mini) - **Free-text categories** derived from the item in the message, with spelling normalisation and reuse of existing close-match categories - **Multi-item entry** in a single message, supporting comma, newline, space, and run-together formats; a single action verb carries forward to cover subsequent verb-less items, with per-line confirmation so the user can catch any wrong inference - **Daily, weekly, and all-time queries** answered in plain language via the bot (`today`, `this week`, `balance`) - **Plain-language financial insights** generated from computed figures without an LLM (rule-based) - **Mobile-first React dashboard** with Home, History, Week, and Settings screens; history grouped by date; individual transaction delete with confirmation - **Automated unit test suite** covering all cashflow computation functions and insight generation logic --- ## Architecture ``` Telegram ──► bot.js ──► interpreter.js ──► OpenAI API │ ▼ cashtrack.db (SQLite — shared source of truth) │ ▼ api.js (Express REST API) │ ▼ React Dashboard (Vite) ``` | Component | Role | |---|---| | `bot.js` | Te …