CAUSE2025 · Enterprising City · BizBuddy AI

Smart Inventory
& AI for Shops

An agentic AI-powered PWA that empowers Indian small shopkeepers with voice-first inventory, OCR bill scanning, real-time analytics, and a Llama-powered business assistant.

API Endpoints

AI-Powered

Agent Tools

App Pages

01 · Tech Stack

Built with the right tools

A lean, production-ready stack optimized for mobile-first PWA performance with real AI at the core.

Frontend

React 18 + Vite

Tailwind CSS, Recharts, Lucide Icons, PWA with service worker

Backend

FastAPI (Python)

28 endpoints, async routes, SSE streaming, Uvicorn

AI / LLM

Groq + Llama 3.3 70B

Tool-calling agent loop, 15 AI features, function definitions

Database

Firebase Firestore

Per-user isolation, real-time onSnapshot, 4 collections

Auth

Firebase Auth

Google OAuth, email/password, session persistence

OCR

Tesseract

pytesseract + Pillow, extracts text from bill photos

Streaming

SSE via fetch

ReadableStream for POST SSE, real-time agent step display

Voice

Web Speech API

Browser-native, no cost, Hindi + English, AI parsing

02 · Architecture

System architecture

A three-tier architecture with real-time Firebase sync and a streaming agentic AI layer.

📱 Frontend — React PWA (Mobile-First)

AuthPage

OnboardingPage

AISetupPage

DashboardPage

InventoryPage

ChatPage

AnalyticsPage

PosterPage

useAuth

useProducts

useAgentChat

useVoiceInput

useRentals

useNotifications

↕

⚡ Transport Layer

Firebase Auth (Google OAuth)

Axios REST → FastAPI

fetch + ReadableStream SSE

Firestore onSnapshot (realtime)

↕

🔧 Backend — FastAPI (Python)

19 Route Modules

Agent System (SSE)

Inventory CRUD

Transactions

Rentals

Analytics

Groq Service

Firebase Service

OCR (Tesseract)

↕

🗄️ Data & AI Layer

Firestore — products

Firestore — transactions

Firestore — rentals

Firestore — settings

Groq API — Llama 3.3 70B

Pexels API — images

03 · User Flow

End-to-end user journey

From first open to daily operations — a guided onboarding that gets shopkeepers running in minutes.

step 01
📱
Open App
PWA loads, checks Firebase Auth session

→

step 02

🔐

Google OAuth or Email/Password via Firebase

→

step 03

🏪

Onboarding

Select business type from 10 categories

→

step 04
🤖
AI Setup
AI generates 18 starter products + insights via /setup-shop

→

step 05

📊

Dashboard

Real-time stats, AI restock tips, demand forecast

→

daily

📦

Manage

Swipe to sell/rent, voice input, OCR bills

→

daily
💬
Ask AI
Agentic chat answers questions using live data

Sale Transaction Flow

💸 Sell Flow

Swipe Product Left

SwipeableProductCard reveals Sell / Rent / AI Price

SellModal Opens

Enter quantity + optional customer name

POST /sell

Validates stock, deducts qty, creates transaction record

Firestore onSnapshot

useProducts updates → UI re-renders instantly

📦 Rental Flow

Swipe → Rent

RentModal: qty + customer + return date

POST /rent

Deducts stock, creates rental (status: active)

Live Countdown

RentalCountdown ticks every second, color-coded urgency

Return → Stock Restored

POST /return-rental → status: returned, qty back

04 · Agentic AI

The agent loop

Llama 3.3 70B autonomously decides which tools to call, chains lookups, and streams results in real-time via SSE.

Agent execution flow (max 5 iterations)

User sends message

POST /agent/chat — full conversation history + business type sent

Groq LLM decides

Llama 3.3 70B with tool_choice: "auto" — picks 0 to N tools

Tool execution

Streams "status" event → queries Firestore → streams "tool_result"

Result fed back

Tool output appended to conversation, loop continues

Final response

Streams "message" event with formatted text → "done" event closes stream

SSE Event Types

status

tool_result

message

error

done

8 Available Tools

📦

get_inventory

All products for the user from Firestore

⚠️

get_low_stock

Products where qty ≤ threshold

📊

get_sales_analytics

Last 200 transactions summary

🧾

get_recent_transactions

Recent sales with optional limit

📈

get_demand_forecast

7-day AI demand predictions

🔄

get_restock_recs

AI restock recommendations

📋

get_business_report

Health score + AI summary

💰

record_sale

Write sale to Firestore via chat

05 · API Endpoints

All 28 endpoints

15 of 28 endpoints call Groq/Llama 3.3 70B. Each AI route has proper error handling and fallback responses.

#	Method	Path	AI	Purpose
1	GET	/inventory	—	List all products for user
2	POST	/inventory	—	Add new product
3	POST	/sell	—	Record a sale, deduct stock
4	POST	/rent	—	Record a rental, deduct stock
5	POST	/return-rental	—	Return rental, restore stock
6	GET	/rentals	—	Active rentals list
7	GET	/transactions	—	Sales history
8	GET	/export	—	CSV export of all data
9	GET	/analytics	—	Sales summary + stats
10	POST	/chat	AI	Simple single-turn chat
11	POST	/agent/chat	AI	Agentic chat — SSE stream
12	POST	/setup-shop	AI	Generate starter inventory + insights
13	POST	/suggest-products	AI	Product recommendations for business type
14	POST	/daily-insight	AI	Daily business tip
15	GET	/demand-forecast	AI	7-day demand prediction
16	GET	/smart-restock	AI	Restock recommendations
17	GET	/business-report	AI	Health score + business summary
18	POST	/optimize-price	AI	AI price suggestion for product
19	POST	/auto-categorize	AI	Auto-fill category, price, threshold
20	POST	/voice-parse	AI	Parse natural spoken input
21	POST	/ocr	AI	Extract items from bill photo
22	POST	/image-recognize	AI	Identify product from image
23	POST	/poster	AI	Generate promotional poster text
24	POST	/festival-insights	AI	Festival-based stock tips + notifications
25	POST	/product-image	AI	Fetch product image via Pexels
26	GET	/	—	Health check
27	GET	/health	—	Health check
28	POST	/ocr/base64	AI	OCR from base64 image

06 · Database Schema

Firestore collections

Per-user data isolation under users/{userId}/. Real-time sync via onSnapshot listeners.

products

users/{uid}/products/{id}

namestring

categorystring

quantitynumber

pricenumber ₹

thresholdnumber

imagestring

createdAttimestamp

updatedAttimestamp

transactions

users/{uid}/transactions/{id}

type"sale"

productIdstring

productNamestring

categorystring

quantitynumber

pricePerUnitnumber ₹

totalAmountnumber ₹

createdAttimestamp

rentals

users/{uid}/rentals/{id}

productIdstring

productNamestring

quantitynumber

customerNamestring?

returnDatetimestamp

status"active"|"returned"

createdAttimestamp

returnedAttimestamp?

settings

users/{uid}/settings/ai_setup

business_insightsarray

welcome_messagestring

tipsstring[]

ai_greetingstring

createdAttimestamp

07 · Key Features

What makes it work

Every feature is designed for shopkeepers with limited digital literacy — simple, fast, and offline-capable.

🎤

Voice-First Input

Web Speech API for hands-free product entry. Speak naturally in English or Hindi — AI parses the intent and fills in product fields automatically.

📸

OCR Bill Scanning

Photograph any supplier invoice. Tesseract extracts text, Groq AI identifies product names, quantities, and prices — auto-populates inventory.

👆

Swipe to Sell / Rent

Swipe any product card left to reveal Sell, Rent, or AI Price buttons. Complete a sale in 3 taps — no complex forms.

⏱️

Live Rental Countdown

Real-time countdown timers on rentals, ticking every second. Color-coded urgency from green → amber → red as return date approaches.

🤖

Agentic Chat

Ask "What should I reorder?" and the AI autonomously queries inventory, runs demand forecast, and gives a specific answer — not generic advice.

🎨

AI Poster Generator

Describe any promotion and get professional poster text instantly. No design skills needed — ready to print or share on WhatsApp.

📊

Smart Dashboard

Real-time stats: total products, low stock count, portfolio value, top seller. AI restock recommendations and 7-day demand forecast updated daily.

🔔

Festival Insights

AI detects upcoming festivals and proactively suggests which products to stock up — Diwali, Holi, Eid, regional festivals included.

📱

PWA — Installable

Works like a native app on Android and iOS. Add to home screen, service worker caching, no app store required. Works on any phone browser.

08 · Impact

SDG alignment

BizBuddy AI directly supports three UN Sustainable Development Goals.

💼

SDG 8 — Decent Work & Economic Growth

Reduces manual workload for small businesses, enabling informed decisions via AI dashboards and chatbots. More time to grow, less time on paperwork.

🏗️

SDG 9 — Industry, Innovation & Infrastructure

Promotes digital inclusion through offline-first, mobile-friendly design. AI-driven features built for real-world use in low-connectivity environments.

⚖️

SDG 10 — Reduced Inequalities

Makes enterprise-grade AI tools accessible to small shops via voice input and local language support. SmartBiz Rooms enable peer learning among business owners.

Smart Inventory & AI for Shops

Built with the right tools

System architecture

End-to-end user journey

Sale Transaction Flow

The agent loop

All 28 endpoints

Firestore collections

What makes it work

SDG alignment

Smart Inventory
& AI for Shops