KiranaSetu: Offline-First POS for Kirana Stores
Explore KiranaSetu, an open-source POS for Indian kirana stores, with offline billing, pickup orders and AI tools. Review its trade-offs and code.
KiranaSetu: What an Offline-First POS Can Do for Neighborhood Stores
A busy grocery counter is a real-time operations problem. The owner has to find products, check stock, calculate a bill, answer questions and take payment - often while customers are waiting and the internet is unreliable. Paper ledgers and handwritten slips can work for the basics, but they get messy once pricing, stock tracking, and customer credit have to happen every day.
KiranaSetu Pro is an open-source retail management prototype built for those constraints. It combines point-of-sale billing, inventory, customer credit tracking, advance pickup orders, and neighborhood delivery in a single browser-based interface. It also uses AI for two specific tasks: interpreting informal grocery lists and drafting payment reminders.
What's genuinely interesting isn't just that AI is included - it's where the system draws the line. Core shop workflows are designed to run local-first, and an external AI service is used only when interpreting text actually helps. Below is how the pieces work, what the design gets right, where it may fall short, and what a shop should verify before trusting it day after day.
The problem KiranaSetu is designed to solve
KiranaSetu is aimed at India's neighborhood grocery shops, where transactions happen all day, margins can be tight, and service is personal. The project describes a market of more than 13 million kirana stores. Its target users are merchants who want more than a simple digital cash register, but may not want a cloud product that charges recurring fees, depends on stable connectivity, or forces customer records into a vendor-controlled system.
That context matters. A US-style retail POS for a chain - with reliable broadband, dedicated checkout hardware, and centrally managed stock - doesn't automatically fit a small shop where the same person handles billing, customer questions, and supplier ordering. A system has to reduce work at the counter without creating a new "gotcha" dependency.
From handwritten slips to a live counter
KiranaSetu replaces handwritten billing with a product catalog and a point-of-sale cart. You can search items in English or Devanagari, and the interface indicates whether a product is available, low in stock, or out of stock. Blocking an unavailable item from being added may sound minor, but it helps prevent the classic mistake of billing for something the shop can't actually supply.
The billing flow is designed for Indian retail. It supports rupee pricing, configurable GST rates, CGST and SGST calculations, and invoice output for 80 mm thermal paper or A4. It also calculates savings against MRP and applies rupee rounding. The real value isn't that arithmetic becomes impossible to mess up - it's that repeated calculations move out of the shopkeeper's head and into a consistent workflow.
What the product is competing with
This isn't only competing with other apps. A merchant might choose from:
- Paper records: cheap and familiar, but hard to search and reconcile.
- A cloud POS subscription: often easier to manage centrally, but dependent on connectivity and on the provider's pricing and data policies.
- A local-first application: keeps core work usable without a live server, but pushes backup, device security, and recovery responsibilities onto the merchant or the person running the deployment.
The project's pricing hypothesis is ₹299-₹₹499 per month or a one-time setup fee of ₹1,999. Those figures suggest what the project thinks a merchant might pay, not proof that demand is broad or stable. In a low-margin business, even a modest subscription needs to save time, prevent losses, or help recover credit reliably enough to justify the cost.
How the retail workflows fit together
KiranaSetu is more than a POS screen. The core idea is to connect what happens around a sale: stock checks, preparing orders, collecting payment, and tracking customer credit. That kind of integration can matter more than adding yet another isolated feature - assuming the data stays consistent across the workflows.
Billing, stock and payment
A sale starts with searching the catalog or adding items to the cart. The product includes a dynamic UPI QR flow that generates a standard payment deep link containing the merchant's UPI ID, name, amount, currency, and an invoice reference. Customers can scan it in supported UPI apps, including Google Pay, PhonePe, Paytm, and BHIM.
One point deserves emphasis: a generated QR code helps initiate or facilitate payment - it does not prove the payment has settled. The project also describes a browser-based "soundbox" effect, including a Hindi voice prompt generated with speech synthesis. That sound is just an interface notification, not an authoritative confirmation from a bank or payment provider.
In a production setup, you'd want the system to mark a transaction paid only after a trusted confirmation mechanism - rather than because audio played or a customer showed a screenshot. Audio feedback can still be useful at the counter, but payment status needs something you can verify.
Advance pickup and local delivery
The pre-order flow lets customers browse the catalog, choose a pickup time, and receive a token number. The shopkeeper sees the order in a fulfillment area and can use a checklist to prepare the bag before the customer arrives. It's a way to reduce the "shopping while blocking checkout" problem by shifting prep ahead of time.
Delivery works with an address, nearby landmark, and a delivery slot. It can apply delivery charges based on thresholds - for example, free delivery above ₹499 or a ₹30 fee below that - and it supports WhatsApp-based dispatch communication. Those are configuration choices, not universal rules. A shop still needs to calculate how delivery time and distance translate into cost before deciding what to charge.
Pickup and delivery also bring operational requirements that a POS alone doesn't solve. Someone has to monitor incoming orders, keep inventory synchronized, and handle substitutions if an item becomes unavailable after an order is placed. The software can structure the process, but it can't remove the need for a clear fulfillment policy.
Customer credit and AI-assisted grocery lists
KiranaSetu keeps a digital ledger for customer credit balances and payments. In the source, this is called a khata: a neighborhood credit book. The app can draft WhatsApp payment reminders in three tones (from respectful to friendly to professional) using Google Gemini, and the shopkeeper chooses the message before sending it through WhatsApp.
This makes sense because reminders aren't just accounting messages. A customer could be a neighbor, a regular, or an older person - so giving the merchant tone control is more practical than sending the same automated template to everyone. Even so, the owner should review names, amounts, and wording before sending. A generated reminder is still a draft, not a substitute for checking the ledger.
The second AI feature, Smart Parchi, parses an informal grocery list or shopping slip. People may write quantities using colloquial terms, use a brand nickname, or mix languages. Gemini gets the text plus a selection of the store catalog, then returns matched products, quantities, stock information, and unmatched items in structured JSON. The merchant reviews matches and adds available products to the cart.
This is a reasonable use of AI because it targets an input problem that ordinary search handles poorly. It's also a workflow where uncertainty has to stay visible. "Half a kilo" could mean a loose-weight product, a pack size, or multiple units. The system shouldn't quietly turn an ambiguous phrase into a confirmed order. Confidence, unmatched items, and human review are essential safeguards.
The architecture and its trade-offs
The codebase is organized as a modular JavaScript application, with separate modules for billing, inventory, bookings, customer orders, the credit ledger, analytics, audio, and AI. The project uses Vite, custom CSS, and browser storage - such as localStorage or IndexedDB - depending on the implementation details. The repository and implementation are available on GitHub, and the original project submission includes additional context.
Local-first is a reliability choice, not a free guarantee
Keeping core data in the browser can help billing keep going when the internet drops. It can also reduce the need to send every catalog lookup or transaction to a cloud service. For shops with inconsistent connectivity, that's a meaningful design decision.
But local storage changes the failure model, it doesn't eliminate failure. If a device is lost, damaged, or reset, data may be gone unless it's been backed up. Browser storage is also not automatically encrypted, safely shared across multiple devices, or protected from unauthorized access. A prototype that demonstrates offline workflows is one thing; a deployed system used by a real merchant needs a tested backup, restore, and device migration plan.
There's also a boundary to the "offline" claim. Core POS screens and locally stored records may work without a network, but Gemini calls require connectivity to the API. WhatsApp sharing and dispatch links also depend on those apps and services being available. So the accurate framing is "offline-capable for selected local workflows," not "every feature works offline."
AI should solve a bounded task
The project uses Gemini Flash for two defined tasks, instead of embedding a generic chatbot throughout the interface. For list parsing, the model is instructed to return structured JSON and match items against a catalog excerpt. For reminders, it drafts several message styles using customer and account details.
That narrower scope makes it easier to evaluate. A merchant or developer can test whether common product names map correctly, whether quantities are interpreted safely, and how often the model invents a match. It also matters how the API key and customer data are handled: production use should avoid exposing secrets in client-side code and should clearly describe what information is sent to the external model provider. A local-first database doesn't mean every part of the system is local-first.
Open source and the cost of ownership
Open-source code lets merchants and developers inspect, adapt, and host the app. It can support local product catalogs, languages, packaging conventions, and integrations without waiting on a vendor roadmap. The project also argues that local control can help keep sensitive customer credit records from being locked into a commercial cloud.
But these benefits come with operational responsibility. Someone still has to maintain the code, ship security updates, configure deployments, and provide support. Open source removes one type of vendor dependency; it doesn't make hosting, backups, and maintenance free. That's the central trade-off: more control and flexibility in exchange for more ownership of the system.
What to validate before using it in a real shop
The source describes a working prototype and a pilot conversation with a shopkeeper. That's useful for spotting real pain points - especially rush-hour stock questions, pickup preparation, and credit reminders. It shouldn't be treated as a controlled performance study or proof that the app is production-ready.
Before a shop depends on any POS, it's worth testing failure modes alongside the happy path.
Run a small, measurable pilot
Start with a limited catalog and a separate test device (or a copy of the data). Measure a few outcomes over a defined period:
- Time to complete a typical basket compared with the current process.
- Billing corrections, stock mismatches, and customer disputes.
- Number of pickup orders prepared on time.
- Whether staff can restore data after a simulated device failure.
- How often AI list parsing needs manual correction.
- Whether credit records and reminders match the merchant's ledger.
If the software saves time but creates more reconciliation work at closing, the adoption decision may still go the wrong way. That's exactly why the pilot should measure both sides.
Check tax, privacy and payment handling
Review GST invoices against the merchant's actual tax setup, product classifications, and accounting workflow. Mentioning GST rates doesn't guarantee every invoice will be compliant in every situation. Confirm the tax calculation and invoice format before using them for official records.
Customer names, phone numbers, addresses, and credit balances are sensitive business data. Decide who can access the device, how backups are protected, what data is sent to Gemini, and how records will be exported or deleted. For payments, separate "creating a UPI payment request" from "confirming receipt." The source describes QR generation and audio feedback - so a merchant should verify what payment confirmation the deployed version actually supports.
Decide who owns support and recovery
A small shop needs clear answers to the everyday "what if" questions:
- What happens if the browser cache is cleared?
- Can the owner move data to a replacement device?
- What happens when an API key expires?
- Who fixes a broken build or updates the product after a security issue?
These aren't edge cases for a system that holds invoices and credit balances - they're part of the product. If the project is deployed as a static site or a container, it may be simple to deploy, but data persistence and secure configuration still need to be designed for that setup. The repository is a useful starting point; it isn't, by itself, a service-level agreement.
Conclusion
KiranaSetu is most compelling as a product-design exercise - matching software behavior to the realities of a neighborhood shop. It treats billing, stock checks, pickup orders, and customer credit as connected workflows, while keeping selected core operations local and using AI only for bounded language tasks.
The trade-offs matter as much as the features. Local storage needs a recovery plan. AI needs review. A UPI QR isn't payment confirmation. Open source can give you control, but someone still has to maintain and support the deployment.
If you're evaluating the project, start with the KiranaSetu repository, run it against a small test catalog, and measure operational results before moving live records. The right POS isn't the one with the longest feature list - it's the one your shop can trust during the evening rush, and that you can recover when something goes wrong.