 █▀▀█ █▀▀█ █▀▀█ █▀▀█ █▀▀█   █▀▀█ █▀▀█ █▀▀█ █   █
 █  █ █  █ █  █ █  █ █▄▄▀   █    █  █ █  █  █ █
 █▀▀▀ █▀▀▀ █▀▀▀ █  █ █  █   █▄▄  █▀▀▀ █▀▀▀   █

DukanSaathi AI — दुकानसाथी

AI Back-Office Agent for India's 63 Million Kirana Stores

No typing. No accountant. No confusion.

A kirana owner speaks in Hindi → DukanSaathi records the sale, updates inventory, generates a GST receipt, and flags low stock — automatically.

🚀 LIVE APP · 📹 DEMO VIDEO · 📄 PROJECT DOC · 🧪 TRY DEMO MODE

💡 What Is This?

🎤 Speak in Hindi	→	🤖 AI Parses	→	📒 Auto-Records	→	🧾 GST Invoice
"Ramesh ne 500 ka atta liya, udhaar"		Samajh Agent extracts: customer, items, prices, credit		Transaction saved + customer ledger updated		CGST + SGST PDF bill generated

No existing solution offers: Voice-first Hindi input + AI parsing + GST invoicing + Inventory alerts + Zero cost.

🏆 Why This Wins

Criterion	Weight	Our Answer
Technical Execution	50%	4-agent architecture · Firestore atomic transactions · Triple AI fallback · Offline queue · 15 unit tests
Impact & Problem Fit	20%	63M kirana stores · 80% on paper · Hindi voice-first removes adoption barrier
Use of Codex	15%	Every line generated via Codex · 14 commits · 94 files · 15,300+ lines
Creativity & Originality	10%	Agent-per-domain · Voice-native Hindi commerce · GST auto-detection
Completeness & Demo	5%	3-min demo · Live deployed URL · Try Demo button for judges

✨ Features

🎤 Voice-First Input

Speak in Hindi / Hinglish — no typing needed.
Powered by Web Speech API (hi-IN).

🤖 4-Agent AI System

Samajh (Understand) → Bahi (Ledger) → Stock (Inventory) → Bill (PDF)
Each agent does one thing perfectly.

🧾 GST Invoice PDF

One-click CGST + SGST compliant bills.
Auto-detects GST rates: 0% grains, 5% packaged, 12% electronics.

📦 Smart Inventory

Auto-updates on every sale.
Low-stock alerts when items drop below reorder level.

💰 Credit Tracking

Customer-wise udhaar (credit) ledger.
Never lose track of who owes you money.

📱 Mobile-First Design

Built for kirana owners' phones.
Bottom nav on mobile, sidebar on desktop.

🔒 Phone OTP Login

No password. No email. Just your mobile number.
Firebase Phone Auth with OTP.

🔌 Triple AI Fallback

Gemini → Groq → Local Parser — works even offline.
Zero downtime, zero cost.

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                     DUKANSAATHI AI                                │
│              🎤 Voice → 🤖 4 Agents → 📊 Business                │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  🎤 Shopkeeper speaks Hindi / Hinglish                            │
│         │                                                         │
│         ▼                                                         │
│  ┌─────────────────────────────────────────────────┐              │
│  │  🤖 AGENT LAYER                                  │              │
│  │                                                  │              │
│  │  Samajh Agent ──→ Bahi Agent ──→ Stock Agent     │              │
│  │  (Hindi Parser)   (Ledger)      (Inventory)     │              │
│  │       │                                │         │              │
│  │       │         ┌──────────────────────┘         │              │
│  │       │         │                                │              │
│  │       │         ▼                                │              │
│  │       │    Bill Agent                            │              │
│  │       │    (GST PDF)                             │              │
│  └───────┼──────────────────────────────────────────┘              │
│          │                                                        │
│          ▼                                                        │
│  ┌─────────────────────────────────────────────────┐              │
│  │  💾 INFRASTRUCTURE (All Free)                     │              │
│  │                                                  │              │
│  │  🧠 Gemini API ──→ 🧠 Groq API ──→ 📝 Local    │              │
│  │  (Primary AI)     (Fallback AI)   (Offline)     │              │
│  │                                                  │              │
│  │  🔥 Firebase Auth + Firestore                    │              │
│  │  ▲ Vercel + Vite                                │              │
│  └─────────────────────────────────────────────────┘              │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

The 4 Agents

#	Agent	Name	Role	File
1	🤖	Samajh Agent (समझ)	Hindi/Hinglish → Structured JSON	`src/agents/samajhAgent.js`
2	📒	Bahi Agent (बही)	Record transactions + update ledger	`src/agents/bahiAgent.js`
3	📦	Stock Agent (स्टॉक)	Track inventory + fire alerts	`src/agents/stockAgent.js`
4	🧾	Bill Agent (बिल)	Generate GST invoice PDF	`src/agents/billAgent.js`

🛠️ Tech Stack

Layer	Technology	Cost
Frontend	React 18 + Vite 5	Free
Styling	Tailwind CSS + Framer Motion	Free
Voice	Web Speech API (hi-IN)	Free
AI	Google Gemini API + Groq API	Free
Offline	Local regex parser	Free
Database	Cloud Firestore (Spark)	Free
Auth	Firebase Phone OTP	Free
PDF	jsPDF + AutoTable	Free
Deploy	Vercel (Hobby)	Free
PWA	Service Worker + Manifest	Free

Total Cost: ₹0 / $0 💯

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
A modern browser (Chrome/Edge for voice)

1. Clone & Install

git clone https://github.com/sanjayofficial-glitch/dukan-saathi-ai.git
cd dukan-saathi-ai
npm install

2. Get FREE API Keys

Service	URL	Free Tier
Google AI Studio	aistudio.google.com	1,500 req/day
Groq	console.groq.com	14,400 req/day
Firebase	console.firebase.google.com	Spark plan forever

3. Configure Environment

cp .env.example .env.local
# Edit .env.local with your Firebase config

Set API keys in Vercel Dashboard → Settings → Environment Variables:

GEMINI_API_KEY=your_gemini_key_here
GROQ_API_KEY=your_groq_key_here

4. Setup Firebase

Create a Firebase project → Spark plan (free)
Enable Authentication → Phone
Enable Cloud Firestore → Start in test mode
Paste security rules (see docs)

5. Run Locally

npm run dev

Open http://localhost:5173 🎉

6. Deploy to Vercel

npm i -g vercel
vercel login
vercel --prod

📁 Project Structure

dukan-saathi-ai/
├── src/
│   ├── agents/              🤖  The 4 AI Agents
│   │   ├── samajhAgent.js   Hindi parser (Gemini → Groq → Local)
│   │   ├── bahiAgent.js     Transaction recorder
│   │   ├── billAgent.js     GST PDF generator
│   │   ├── stockAgent.js    Inventory tracker
│   │   └── samajhAgent.test.js
│   ├── components/          🧩  React Components
│   │   ├── Layout.jsx       App shell with sidebar
│   │   ├── PhoneAuth.jsx    OTP login
│   │   ├── VoiceInput.jsx   Microphone button
│   │   ├── TransactionForm.jsx  Voice → Parse → Save flow
│   │   ├── Dashboard.jsx    Summary + quick transaction
│   │   ├── Transactions.jsx Full ledger with filters
│   │   ├── Inventory.jsx    Stock management
│   │   ├── Invoices.jsx     PDF downloads
│   │   ├── AlertBanner.jsx  Low-stock notifications
│   │   ├── ErrorBoundary.jsx    Error handling
│   │   └── RouteErrorBoundary.jsx
│   ├── hooks/               ⚡  Custom Hooks
│   │   ├── useAuth.js       Firebase auth state
│   │   └── useFirestore.js  Real-time Firestore
│   ├── lib/                 🔧  Utilities
│   │   ├── firebase.js      Firebase initialization
│   │   └── constants.js     Items, units, GST rates
│   ├── App.jsx              🚀  Main app + routing
│   ├── main.jsx             Entry point
│   └── index.css            Tailwind + custom styles
├── api/                     🌐  Vercel Serverless Functions
│   └── parse.js             AI proxy (keeps API keys secure)
├── docs/                    📄  Documentation
│   ├── google-doc-ready.md  Hackathon submission doc
│   ├── demo-script.md       3-min demo video script
│   ├── deployment-checklist.md
│   └── project-description.md
├── public/                  📦  Static assets
├── PRD.md                   📋  Product Requirements (314 lines)
├── TRD.md                   📐  Technical Requirements (610 lines)
├── CONTRIBUTING.md          🤝  Contribution guide
├── SECURITY.md              🔐  Security policy
└── LICENSE                  📜  MIT License

🎬 Demo

📹 Video: Watch the 3-minute demo on YouTube
📄 Project Doc: Google Doc — Full Submission

⚡ Quick Test (For Judges)

Step	Action
1	Open the app
2	Enter phone number: `+91 8984413298`
3	Enter OTP: `098765`
4	Tap 🎤 microphone → Say: "Ramesh ne 500 ka atta liya, udhaar"
5	Review parsed items → Tap "Confirm & Save"
6	Check Dashboard for updated sales
7	Go to Invoices → Generate GST PDF

Full Demo Flow

Open the app
Login with demo credentials above
Tap 🎤 microphone → Speak in Hindi/Hinglish
Review parsed items → Tap "Confirm & Save"
Check Dashboard for updated sales
Go to Invoices → Generate GST PDF
Check Inventory for stock updates

Recording a Transaction

Step	Action
1	Login with phone number (OTP) or use Demo mode
2	Tap the 🎤 microphone button
3	Speak in Hindi/Hinglish
4	Review the parsed data (editable if needed)
5	Tap "Confirm & Save"
6	✅ Transaction saved + inventory updated + credit tracked

Example Inputs

Hindi/Hinglish Input	Parsed As
"Ramesh ne 500 ka atta aur 200 ka tel liya, udhaar"	Sale to Ramesh: Atta ₹500 + Tel ₹200, Payment: Credit
"Sharma ji ko 2 kg chawal 120 rupaye kilo diye"	Sale to Sharma: Chawal 2kg @ ₹120/kg
"Mohan se 1000 rupaye cash aaye"	Payment received from Mohan: ₹1000 Cash

🧪 Testing

Read the rest on GitHub

muse-code	1 · avg 2.0
codex	7 · avg 1.0
claude	36 · avg 0.9
claude-code	68 · avg 0.9
cursor	10 · avg 0.6

listed slop	693
in the trough	0
slopsmiths	7
votes	1039
comments	0

dukan-saathi-ai

I'm not calling your project slop! Geeze, it's a joke... Do you own this repo?

Disclosures, inferred by the Cap'm

The Cap'm's log