---
title: "Karobar ERP: Books That Balance for the Corner Shop"
description: "How I built Karobar ERP: an open-source Django and React system that gives a small shop or distributor its stock, sales, accounts and payroll in one place, in English, Urdu and Arabic, with books that always balance and stock that stays right when two cashiers sell the last item."
author: "Syed Ahmer Shah"
date: 2026-11-13
url: https://ahmershah.dev/blogs/karobar-erp-case-study-erp-for-small-shops
tags: ["karobar-erp", "case-study", "django", "react", "mysql", "accounting", "multi-tenancy", "system-design"]
series: "The Engineering Logs" (part 23)
---

# Karobar ERP: Books That Balance for the Corner Shop

_A case study on the three promises a shopkeeper needs from software: the books balance, the stock is right, and nobody else can see their numbers_

![Syed Ahmer Shah at a shop counter with a laptop, the Karobar ERP home page behind him and the title KarobarERP: Books That Balance for the Corner Shop](https://ahmershah.dev/blog/karobar-erp-case-study-erp-for-small-shops/cover-16ecef03.webp)


Walk into almost any small shop in Pakistan and you'll find the business in three places. The stock is on the shelves and in the owner's head. The sales are in a till, or a drawer. And the money people owe, the part that decides whether the shop survives the month, is in a notebook under the counter.

That works until it doesn't. The notebook gets wet. The nephew who knew the prices leaves. Two people sell the same last carton. The owner asks a simple question, "did I make money in October?", and nobody can answer it without three evenings and a calculator.

Software for this exists, and it's called an ERP. The big ones are built for companies with an accounts department. They assume you know what a debit is, that you read English comfortably, and that you have someone to set it all up. A kiryana store has none of those.

Karobar ERP is my attempt at the other kind: one place for stock, sales, accounts and payroll, for shops, wholesalers and distributors, in English, Urdu and Arabic. "Karobar" simply means "business". I built it between 2 and 13 November 2026, across 73 pull requests. Every module is finished and it's open source. It isn't live yet: the public demo opens after the browser testing I describe at the end.

This is how it fits together, what fought back, and the three promises I wrote down before anything else.

* * *

## Three promises before any code

The forms are the easy part of an ERP. Anyone can build a screen that saves an invoice. The hard part is what has to stay true after ten thousand invoices.

**The books always balance.** Every sale, purchase, payment and salary writes its own accounting entry, and that entry can't be saved unless both sides add up. Once it's posted it can never be edited, not even by me with direct access to the server. A mistake is fixed the way an accountant fixes it: with a second entry that reverses the first, so the history stays honest.

**The stock is always right.** If two cashiers try to sell the last bag of rice at the same moment, exactly one of them succeeds. Not usually. Always.

**One business never sees another's numbers.** Many businesses share one installation, and each one must be as private as if it were alone.

Each promise has tests whose only job is to try to break it. That's the part I'd point to if someone asked why they should trust this with their shop.

## One sale, four things that must agree

Here's what happens when a cashier presses **Cash** on a sale of rice, cooking oil, tea and sugar.

The stock of four products goes down. The cost of those four products moves out of "inventory" and into "cost of goods sold". The sale and its tax are recorded as income and as tax owed to the government. And the cash in the drawer goes up.

That's four separate facts, and they all have to be saved together or not at all. If the power dies halfway, the shop can't be left with the stock gone and no money recorded. So posting a document is one database transaction: lock the stock rows it touches, write the stock movements, write the accounting entry, mark the document as posted. If any step fails, none of it is kept.

![The counter with four items in the sale, the tax worked out and the total to pay](/blog/karobar-erp-case-study-erp-for-small-shops/9539c8f7df.webp)

The rules for which accounts a sale touches live in one small module of plain Python with no database in it, tested to 100% of its branches. They don't say "debit account 1130". They say "debit receivables", and each business maps that role to its own chart of accounts. So the same rule works for a shop in Hyderabad and a trading company in Dubai.

The shopkeeper sees none of this. They see a button that says Cash.

## The last bag of rice

This is the oldest bug in retail software, and I'd met it before in other projects. Two people read "1 left" at the same time. Both sell it. The stock goes to minus one, and somebody is promised rice that doesn't exist.

Karobar's answer is a lock. Before a sale changes the stock of a product in a warehouse, it takes a lock on that one row in the database. The second cashier's sale waits a few milliseconds, then reads the true number, which is now zero, and is refused politely.

I didn't want to believe that from reading the code, so there's a test that really does it: several sales of the last item fired at the same instant against a real MySQL database. One wins. The rest are told the item is gone. The tests run on MySQL, never on a lighter stand-in database, precisely because locking behaves differently on each and I wanted the test to tell the truth about production.

## Many businesses, one building

Karobar is "multi-tenant", which is a dry word for a simple idea: it's an apartment building. Everyone shares the plumbing, and nobody can open anybody else's door.

Every row of business data carries the ID of the business that owns it. The code that reads the database is written so that forgetting to filter by business doesn't quietly return everybody's data. It raises an error instead. I'd rather the app crash in front of me than leak in front of a customer.

And then there's a test that plays the nosy neighbour. It signs in as a member of one business and calls every endpoint in the system asking for another business's records. Every single one has to answer "not found". When I add a new screen, that test covers it automatically.

## Software for people who aren't accountants

The design rule was: if a shopkeeper who has never opened accounting software can't use it, it isn't done.

So the screens are named for the question, not the report. The receivables ageing report is called **Who owes me**. The dashboard is **How is my business?** The profit and loss page asks, in its own subtitle, "Did you make money in this period?" Every page has a short "How to use this page" box with numbered steps.

![The dashboard: sales today, sales this month, profit on goods, what customers owe and thirty days of sales](/blog/karobar-erp-case-study-erp-for-small-shops/e14f6a26c8.webp)

The whole app works in English, Urdu and Arabic, and switches direction properly: in Urdu and Arabic the menu moves to the right and everything reads right to left, including the printed bill. Urdu uses the Nastaliq script people actually read in, not a generic Arabic font.

![The same dashboard for the Dubai demo company, in Arabic and right to left](/blog/karobar-erp-case-study-erp-for-small-shops/c90d7043e0.webp)

A few things came straight from how shops really work. Products are bought by the carton and sold by the piece. A bill can be sent to the customer on WhatsApp. There's a reminder button next to every late payer. And the bill itself comes in six designs, on A4 paper or the 80 mm roll a till printer uses.

## The accountant still gets everything

Friendly words on top, real accounting underneath. An accountant who opens Karobar finds a chart of accounts, a journal, a general ledger, a trial balance, profit and loss, a balance sheet, cash flow and a sales tax report, all with spreadsheet export.

![The trial balance of the demo store: every account with its debit or credit balance](/blog/karobar-erp-case-study-erp-for-small-shops/0074c84291.webp)

Two details matter more than they look. Document numbers have no gaps: a number is only taken at the moment a document is posted, so a deleted draft never burns one, and an auditor who sees INV-000845 and INV-000847 knows 846 exists. And tax rates are stored with the dates they applied, so last year's bill still shows last year's rate after the government changes it.

## Payroll, and the numbers I refused to guess

Payroll was the module that taught me the most. Karobar works out a month's pay for everyone from their contracts, takes off unpaid leave and absences by the day, withholds income tax, posts the salaries to the books and produces a payslip for each person. For Pakistan the income tax slabs ship with the app, taken from the Finance Act itself.

![Three months of payroll for the six employees of the Dubai demo company](/blog/karobar-erp-case-study-erp-for-small-shops/7b5d2ec0ad.webp)

Then I got to the pension contribution, EOBI. Every guide on the internet states the rate confidently. The copy of the law I could find said something different. I couldn't find the official text that settles it.

So I made a rule: **Karobar only ships a legal number if I can point to the official document it came from.** Where I could, like the minimum wages notified for Islamabad and Sindh, the number is built in with its source shown on screen. Where I couldn't, the business types the rate in, and nothing is pre-filled. The same rule covers the Gulf: the end-of-service gratuity formulas for the UAE and Saudi Arabia come from the labour laws, but no social insurance rate ships.

It makes the software look less finished. But someone's wages depend on it, and a confident wrong number is worse than an empty box.

## An assistant that isn't allowed to act alone

There's an optional chat, "Ask Karobar", where an owner can type "who owes me the most?" or "make a bill for Paradise Bakers, ten cartons of oil".

It follows three rules. It only ever sees the figures your role is allowed to see, so a cashier can't ask it for the profit. It never saves anything by itself: it prepares a draft, shows it on a card, and waits for you to press Confirm. And every message is signed and chained to the one before it, so if someone edits an old answer in the database, or removes one from the middle of a conversation, the app notices.

## How I worked

I built Karobar with an AI coding assistant beside me the whole way, and I'd rather say that plainly than have someone discover it. What I learned is that the assistant is the easy part. The discipline around it is the work.

Every change, however small, went through a pull request. Nothing merged until the full test suite, the type checker, the linters and a security scan passed, and until a second, independent automated reviewer had read the change and every one of its comments was answered. That reviewer found real mistakes right up to the final day. The decisions were mine: the three promises, the rule about official numbers, what to leave out. The tests are there so that neither of us has to be trusted.

## What I got wrong

**The chat could freeze the whole app.** At first, a chat answer was produced inside the web request. A slow reply from the AI provider would hold that request open, and enough of them at once would leave nobody able to load a page. Answers now run in a background worker and the screen simply checks back, so a slow answer only slows itself.

**Signing in with Facebook wasn't safe enough, so I turned it off.** Confirming someone's email address doesn't prove they own the Facebook account being attached to it. Rather than ship a sign-in I couldn't fully stand behind, it's switched off at launch. Email and Google sign-in remain.

**People who start mid-year were going to pay the wrong tax.** Income tax is worked out over the whole tax year. A business that starts using Karobar in November has employees who were already paid, and taxed, since July. My first version ignored that and would have withheld too little. Each employee now has a place for "pay before Karobar".

**My demo shop was losing money.** To show the app with realistic data, a script invents two businesses and runs a year of purchases, sales and salaries through the real posting rules. The first results were realistic in the wrong way: both shops were quietly going bankrupt. I had to tune them like a real business, with bigger wholesale orders, fuller shelves and a smaller wage bill in Dubai, until the Hyderabad store turned a healthy profit. The Dubai company still only just breaks even, which is at least true to life.

**Big reports are still slow.** With a million accounting lines loaded, the balance sheet takes about 4.7 seconds and the cash flow about 7. That's too slow, I know why, and the proper fix (keeping running balances instead of adding everything up each time) is on the list. A small shop will never hit it. I'd still rather write it down than hide it.

**Two languages still need a native reader.** The Urdu and Arabic text has had one careful review pass, and the phrases I'm unsure of are listed in the repository for a native reader to check. There's also a small bug where the business name is cut off in the right-to-left menus. Both are in the open list of things to fix.

## By the numbers

- 12 days from the first commit to every module being finished
- 73 pull requests, each checked by CI, a security scan and an automated reviewer
- 1,136 automated tests on the backend and 35 on the web app, with 97% of the backend covered
- 100% branch coverage on the accounting and payroll rules, enforced by CI
- 3 languages on every screen and every printed document, 2 of them right to left
- 6 bill designs, on A4 or an 80 mm roll
- 500 employees' payroll worked out in about half a second
- 2 invented demo businesses, one in rupees and one in dirhams, with about 2,400 sales bills between them in four months of history

## What's next

The building is done; what's left is proving it from the outside. Next comes a suite of browser tests that clicks through the main journeys the way a person would: sign up, add stock, sell at the counter, receive a payment, run a month's payroll. Then it goes live at karobarerp.ahmershah.dev with a public demo anyone can sign into, reset every night, and version 1.0.0 is tagged.

After that the work moves outside the code: the first real shop, and everything its owner tells me I got wrong. A few items are already waiting on the outside world, like the official EOBI text and next year's tax slabs.

If I started again, I'd write the same three promises on day one. And I'd build the demo shops in the first week instead of the last, because nothing shows you what's missing from accounting software like watching an invented shop go bankrupt in it.

The source is on [GitHub](https://github.com/ahmershahdev/karobar-erp), and I wrote about the idea itself, for people who have never thought about what's inside a shop's notebook, in [The shop that ran on a notebook](/blogs/the-shop-that-ran-on-a-notebook).


---

*Originally published at https://ahmershah.dev/blogs/karobar-erp-case-study-erp-for-small-shops — © Syed Ahmer Shah*
