HisabMate: A Local-First, AI-Assisted Digital Bahi-Khata for Indian Microbusinesses

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

HisabMate is a local-first, AI-assisted bahi-khata (the traditional credit ledger) for Indian microbusinesses.

If you have ever bought something from a neighbourhood kirana, a tailor, or a small wholesaler, you have probably seen the system: a notebook where the owner writes who owes what. Customers take goods on credit (udhaar), pay back in pieces, and the owner reconciles it all by hand. It works because it is simple, but it is also fragile. Pages get smudged, entries go missing, and a disputed balance turns into an argument between two people who both want to stay on good terms.

Many bookkeeping tools exist, but they often assume cloud accounts, subscriptions, and a comfort with accounting vocabulary that a busy shopkeeper may not have. HisabMate takes a narrower path: keep the ledger on the owner's own machine, make the arithmetic exact and boring, and let a local language model help with the typing, never with the money.

The person who would pay for something like this is the owner who already runs on credit and handwritten pages and wants a clearer, searchable, exportable record without handing customer data to a third party. To be upfront: I have not had a paying user yet, so that is my hypothesis about the market, not a result.

Demo

HisabMate is not deployed publicly. It runs locally, and the two screenshots below are from the real application running on localhost.

Screenshot 1: HisabMate running locally at http://127.0.0.1:5174/.

Screenshot 2: a second view of the working local application.

Code

sm4006 / HisabMate

HisabMate

HisabMate is a local-first AI-assisted bahi-khata for Indian microbusinesses The Python backend owns validation, integer-paise calculations, SQLite persistence, idempotency, and CSV export. The React frontend is a local dashboard and review workflow.

Requirements

• Python 3.10+ (Python 3.13+ is the target documented in the PRD)
• Node.js and npm
• Optional: Ollama for natural-language transaction proposals

No Python package installation is required: the backend uses the standard library. Frontend dependencies are declared in frontend/package.json.

Installation

From the repository root:

Set-Location .\frontend
npm install
Set-Location ..

The backend creates the SQLite schema automatically on first start. It does not seed customers or transactions.

Ollama setup

Install Ollama separately, start its local service, and install the configured model:

ollama pull llama3.2:3b

HisabMate uses llama3.2:3b by default through http://localhost:11434. Override the model or endpoint when needed:

$env:OLLAMA_MODEL = "llama3.2:3b"
$env:OLLAMA_HOST = "http://localhost:11434"

The…

View on GitHub

Repository: github.com/sm4006/HisabMate

How I Built It

Architecture

The design rule is that the model proposes and the code decides.

• Backend (Python, standard library only). It owns validation, integer-paise calculations, SQLite persistence, idempotency, and CSV export. There are no Python packages to install.
• Frontend (React). A local dashboard and review workflow that talks to the backend API at http://127.0.0.1:8000/api.
• AI layer (Ollama). HisabMate uses llama3.2:3b by default through a local Ollama service at http://localhost:11434. The model and endpoint can be overridden with the OLLAMA_MODEL and OLLAMA_HOST environment variables.
• Storage. A local SQLite database. The schema is created automatically on first start, and nothing is seeded.

Safeguards documented in the repository

Money software has to be dull in the right places, so these are the parts I care about most:

• Integer paise, never floats. Credit and payment amounts are stored as integer paise, with exact two-decimal rupee/paise input validation. Balances are deterministic.
• Model output is a proposal only. When Ollama interprets a natural-language entry, the response goes through strict validation in Python. Nothing is written to the ledger until the user explicitly confirms it.
• Idempotent confirmations. Confirmed transaction submissions use persistent idempotency, so a double click or a retry does not create a duplicate entry.
• Append-only corrections. Mistakes are corrected by adding a new entry with an audit reference, not by silently editing history, much like striking through a line in a paper ledger.
• Safer CSV export. Text fields that begin with spreadsheet formula characters are escaped, so an exported file does not turn a customer name into a formula.
• Honest empty fields. The CSV has a remarks column, but the current schema stores no remarks, so it is exported blank rather than guessed.

What works today

• Customer records with outstanding balances calculated from the ledger.
• Credit and payment transactions.
• Local Ollama transaction proposals with an explicit confirmation step.
• Customer-specific ledgers and a Daily Hisab view filtered by business date, customer, transaction type, and search text.
• Transaction-history CSV export that respects the active filters.
• Loading, empty, validation, offline, and API-error states in the frontend.
• A Python unittest suite, a compile check, and a frontend build, all runnable from the README commands.

How GitHub Copilot fits in

I used GitHub Copilot Chat in VS Code, primarily in Agent mode, as a coding assistant throughout HisabMate's development.

I used it to help implement and refine the Python ledger and API, build the React/Vite interface, develop the AI-assisted transaction proposal flow, add Daily Hisab filters and CSV export, and expand tests and project documentation. I worked incrementally, reviewing the implementation and testing the application between tasks.

One concrete moment where it helped: Copilot helped connect the customer-specific ledger view to the backend so that selecting a customer displayed that customer's transactions and outstanding balance rather than generic or unrelated data.

One moment that required correction: During the final submission process, I had to correct the Git remote configuration before the existing local commit could be pushed to GitHub. This was a reminder that agent-generated instructions still need to be checked against the actual repository state.

What remained human-owned: The core financial-safety decisions were not delegated to the model. Transaction amounts use integer paise, the backend validates proposed transactions, and the user must review and explicitly confirm a transaction before it is written to the ledger. The AI proposes an interpretation; it does not get direct database-write authority.

I also reviewed the generated changes, ran tests and build checks, and checked the application against the intended workflow rather than treating generated code as automatically correct.

Repository: https://github.com/sm4006/HisabMate

Copilot was a development aid, not a substitute for reviewing financial logic or verifying the finished application.

Known Limitations

I would rather list these here than have a reader discover them:

• No contact details or opening balances. The current SQLite schema does not represent them.
• No free-text remarks. They are not stored, so search covers customer names and controlled transaction labels only.
• Out of scope for this release: payment reminders, CSV customization, bank integrations, and multi-user accounts.
• No frontend unit or end-to-end test framework. The browser workflows were manually exercised against disposable local services, and the Python suite is the automated safety net.
• Ollama must be installed and running for live interpretation. The normal Python test suite does not need it.
• A 3B model is small. I am not publishing accuracy benchmarks for its interpretations. That is exactly why every proposal needs a human confirmation before it touches the ledger.
• Setup instructions in the README use PowerShell syntax. Other shells will need small adjustments.
• Not deployed. There is no hosted version. It is meant to run on the owner's own machine.

Why Does Open Innovation Matter?

For a small business, a ledger is not just data. It is who trusts whom, and how much. Open-weight models and local inference change what is possible here:

1. The data can stay on the owner's machine. By default, HisabMate points at a local Ollama endpoint and a local SQLite file. A closed hosted API would mean sending customer names and amounts to a server the shopkeeper does not control.
2. The cost model fits the customer. A microbusiness cannot easily absorb per-request fees or a monthly subscription for something that used to be a notebook. Running a model locally has no per-call bill.
3. The model is swappable. Because the model name and host are configuration, not a vendor contract, the owner or a local developer can try a different open model without rewriting the application.
4. The behaviour is inspectable. The backend is plain Python and the rules that guard the money are readable. For software that tracks who owes whom, being able to read the rules is a feature.

The honest trade-off is capability. A small local model is weaker than a large hosted one, which is why HisabMate treats it as a typing assistant behind a validation boundary rather than as an authority.

Prize Categories

• Best Use of GitHub Copilot

---

Thanks for reading, and for any feedback, especially from anyone who has run a credit-based shop and knows what a real bahi-khata needs.