A comprehensive, mobile-first full-stack retail management web application built for modern shopkeepers and merchants. Features AI voice/chat workflow automation, instant barcode scanning, POS billing, customer udhari (khata) tracking, inventory control, and payment reminders.
🔗 Live App URL: https://shopmateai.lovable.app
- Overview
- System Architecture & Workflow
- Core Features
- Tech Stack
- Project Structure
- Getting Started
- Security & Privacy
- License
🌐 Try the Live Application: https://shopmateai.lovable.app
Running a retail shop involves balancing inventory, processing rapid customer queues, managing outstanding credits (udhari), and sending payment reminders. Shopmate AI replaces messy paper notebooks and clunky legacy software with a fast, mobile-friendly full-stack application that puts AI at the service of the shopkeeper.
- AI Shopkeeper Assistant: Speak naturally or type commands to add products, check stock, or draft orders hands-free.
- Barcode Scanner & Fast Billing: Point phone camera at any product barcode to auto-populate name, unit, and price, generating a clean printable/shareable invoice in seconds.
- Digital Khata & Credit Ledger: Track which customer owes how much, log partial repayments, and maintain clear transaction histories.
- Smart Reminders: Set automated payment alerts and WhatsApp-ready reminder notifications for outstanding balances.
- Real-time Inventory & Sales Insights: Monitor low-stock alerts, best-selling items, and daily revenue metrics.
flowchart TD
subgraph Client["📱 Shopmate Frontend (React 19 + TanStack)"]
Scanner[Barcode Scanner & Camera]
Billing[POS & Invoice Generator]
Khata[Customer Credit Ledger / Udhaar]
Inventory[Stock & Catalog Manager]
VoiceAssistant[Voice & AI Naturalist Panel]
end
subgraph Security["🛡️ Security & Auth Gate"]
Session[Auth Session Validation]
EnvConf[Client Environment Config]
end
subgraph BackendAPI["☁️ Backend / Edge Layer"]
ShopService[Store & Product Service]
OrderService[Billing & Sales Service]
AIService[AI NLP & Voice Assistant Service]
end
subgraph Storage["🗄️ Database & Ledgers"]
ShopDB[(Shops & Products)]
LedgerDB[(Customers & Khata Entries)]
BillDB[(Invoices & Orders)]
ReminderDB[(Payment Reminders)]
end
Scanner --> Billing
Billing --> ShopService --> BillDB
Khata --> ShopService --> LedgerDB
Inventory --> ShopService --> ShopDB
VoiceAssistant <--> AIService
Session <--> Storage
EnvConf --> Client
| Module | Description | Capability |
|---|---|---|
| ⚡ Barcode Scanner & POS Billing | Instant camera-based barcode scanning to add line items and calculate taxes/discounts. | Rapid checkout & digital receipt generation |
| 📒 Digital Khata (Customer Credit) | Complete ledger tracking customer debts, partial payments, and net credit balances. | Transparent credit tracking with zero paper loss |
| 🤖 AI Voice & Chat Assistant | Hands-free natural language voice interface to query stock, create customer tabs, or record orders. | Conversational shop management |
| 📦 Inventory Management | Catalog management with SKU, barcode, unit, cost price, and auto-flagging of low stock. | Never run out of critical inventory |
| ⏰ Payment Reminders | Schedule payment due dates and generate quick payment reminder messages. | Improve cash collection speed |
| 📈 Sales Analytics & Reports | Daily, weekly, and monthly sales graphs with revenue breakdowns and top-selling items. | Actionable business intelligence |
| 📱 Mobile & PWA Ready | High-performance responsive UI optimized for single-handed mobile use on the shop floor. | Works on any phone, tablet, or PC |
- Frontend Core: React 19 + TanStack Router
- Bundler & Build Tool: Vite 7 + TypeScript
- Styling: Tailwind CSS v4 with native design tokens and responsive utilities
- UI Primitives: Radix UI accessible primitives + Lucide Icons + Recharts
- Voice Capabilities: Web Speech API (
SpeechRecognition+SpeechSynthesis) - Notifications: Sonner Toasts
- Database / Backend: Ready for connection with Supabase (PostgreSQL + RLS) or any custom REST backend
shopmate-ai/
├── public/ # Static assets, logos, and favicon
├── src/
│ ├── assets/ # App illustrations and brand assets
│ ├── components/ # Reusable UI widgets and layout modules
│ │ ├── ui/ # Accessible Radix UI components (Dialog, Drawer, Table...)
│ │ └── ...
│ ├── hooks/ # Custom business and utility hooks (useAuth, useMobile...)
│ ├── integrations/ # Backend adapters (Supabase client & middleware)
│ ├── lib/ # Helper utilities and formatters
│ ├── routes/ # TanStack file-based routes
│ │ ├── __root.tsx # App shell, navigation providers
│ │ ├── index.tsx # Landing page & hero presentation
│ │ ├── auth.tsx # Merchant login & registration
│ │ ├── onboarding.tsx # Shop profile setup wizard
│ │ ├── _app.tsx # Authenticated application layout & sidebar
│ │ ├── _app.dashboard.tsx # Overview dashboard with KPIs
│ │ ├── _app.billing.tsx # POS checkout & barcode invoice terminal
│ │ ├── _app.products.tsx # Product inventory catalog
│ │ ├── _app.customers.tsx # Customer credit (Khata) management
│ │ ├── _app.orders.tsx # Order processing & statuses
│ │ ├── _app.sales.tsx # Sales analytics & revenue reports
│ │ ├── _app.assistant.tsx # AI voice & chat shop assistant
│ │ ├── _app.reminders.tsx # Payment reminder scheduler
│ │ ├── _app.history.tsx # Past transaction audit trail
│ │ └── _app.settings.tsx # Store settings & tax rates
│ ├── router.tsx # Router initialization & error handling
│ ├── server.ts # Server entry point
│ └── styles.css # Tailwind v4 theme styles
├── .env.example # Environment variables template
├── package.json # Project dependencies and scripts
├── tsconfig.json # TypeScript compiler config
└── vite.config.ts # Vite configuration
Follow these steps to set up and run Shopmate AI locally.
- Node.js (version 18.x or higher, recommended 20+)
npm,pnpm, orbunpackage manager
git clone https://github.com/dipzz0/Shopmate-AI.git
cd Shopmate-AI
npm installCopy the sample environment template:
cp .env.example .envOpen .env and fill in your backend credentials:
# Backend / Database Configuration (e.g. Supabase)
VITE_SUPABASE_URL="https://your-project.supabase.co"
VITE_SUPABASE_PUBLISHABLE_KEY="your-anon-publishable-key"
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_PUBLISHABLE_KEY="your-anon-publishable-key"This frontend is designed to be completely decoupled. You can connect it to your own Supabase instance or custom database backend:
Click to view required database schema (SQL)
-- Profiles
create table public.profiles (
id uuid primary key references auth.users(id) on delete cascade,
full_name text,
shop_id uuid,
created_at timestamptz not null default now(),
updated_at timestamptz not null default now()
);
-- Shops
create table public.shops (
id uuid primary key default gen_random_uuid(),
owner_id uuid not null references auth.users(id) on delete cascade,
name text not null,
shop_type text not null default 'general',
address text,
phone text,
currency text not null default 'INR',
gst_number text,
created_at timestamptz not null default now()
);
-- Products
create table public.products (
id uuid primary key default gen_random_uuid(),
shop_id uuid not null references public.shops(id) on delete cascade,
name text not null,
barcode text,
sku text,
category text,
unit text default 'pcs',
price numeric(12,2) not null default 0,
cost_price numeric(12,2) default 0,
stock numeric(12,2) not null default 0,
low_stock_threshold numeric(12,2) default 5,
tax_rate numeric(5,2) default 0,
created_at timestamptz not null default now()
);
-- Customers (Khata)
create table public.customers (
id uuid primary key default gen_random_uuid(),
shop_id uuid not null references public.shops(id) on delete cascade,
name text not null,
phone text,
address text,
credit_balance numeric(12,2) not null default 0,
notes text,
created_at timestamptz not null default now()
);The AI assistant (_app.assistant.tsx) allows shopkeepers to perform voice and chat actions. You can hook it up to any LLM service (Google Gemini, OpenAI, Anthropic, or local models):
// Sample API handler contract for shop assistant actions
// Input: { message: "Check how much rice is in stock", shopId: "..." }
// Output: { reply: "You currently have 42 kg of Basmati Rice remaining in inventory." }npm run devOpen your browser and navigate to http://localhost:5173 to start using the shop terminal!
npm run build
npm run preview- Client-Side Data Safeguards: Barcode decoding and audio capture are processed directly in the merchant's browser to minimize latency and protect store confidentiality.
- On-Demand Hardware Permissions: Camera (for barcodes) and microphone (for voice commands) are activated only when explicitly triggered by the user.
- Native Web Speech Privacy: Voice interaction relies on native browser APIs without third-party audio recording trackers.
- End-to-End Encrypted Transport: All communication between client applications and backend endpoints occurs exclusively over secure HTTPS/TLS protocols.
This project is licensed under the MIT License — feel free to use, modify, and build upon it.
Built for smart merchants & retail shopkeepers everywhere. 🛍️
