GitHub - Magraa/Hisab-AI: An AI-powered financial ledger & smart Bahi-Khata notebook for small businesses and freelancers. Features sub-second natural language & voice expense entry, Gemini AI multimodal OCR for receipts & handwritten bills, 300+ merchant detection, Supabase cloud sync, offline PWA, and 1-tap WhatsApp PDF statements.

Your Business. Your Hisab.
An intelligent, lightning-fast financial ledger and AI-powered expense notebook crafted for Indian small businesses, freelancers, and smart spenders.

UI Showcase • Features • Avatars • Merchants • Architecture • NLP Engine • Quickstart • Security • Roadmap

🌟 Overview

Hisab AI transforms the way Indian shopkeepers, MSMEs, contractors, and individuals manage their daily cash flow and credit accounts (Bahi-Khata).

Instead of tedious multi-step form entry, Hisab lets you type or speak naturally — like 500 diesel, Ramesh 500, or Sent 1200 to Sharma Hardware for cement — and instantly categorizes the transaction, infers incoming vs. outgoing flow, matches contacts, and keeps running balances accurate to the paisa.

Equipped with Google Gemini 2.0 Flash Vision AI, Hisab also scans printed receipts, grocery slips, and handwritten physical ledger notes, converting them into structured accounting entries in seconds.

📱 Live UI Showcase

✨ Home & Natural Input	📊 Business Insights	📜 Transaction Ledger
🚀 Onboarding Flow	⚙️ Settings & Theme Hub	💼 Personalized Setup

⚡ Superpowers & Core Features

🧠 1. Hybrid Natural Language Entry & Gemini 2.0 Flash AI Parsing

3-Way Parsing Mode Switch (Settings → Parsing Engine):
- ⚡ Local: Instant on-device NLP parser running in <2ms with phonetic speech-to-text mishearing normalization (sent ↔ saint, kal ↔ call, maal ↔ mall). 100% offline-ready.
- 🧠 Smart Auto: Fast local parser runs first; if confidence is low or complex sentence structures are detected, it seamlessly escalates to Gemini 2.0 Flash AI.
- 🤖 Always AI: Routes every entry through Gemini 2.0 Flash for maximum contextual and semantic extraction.
Resilient, Non-Blocking UX: Displays an animated "Thinking…" state with a Cancel button while the AI call is in flight. Silently and instantly falls back to the local parser on any timeout, offline state, or quota exhaustion — user entry is never blocked.
Dedicated Daily Quotas: Built-in free tier with 25 AI text parses/day (independent of the 3/day receipt scan quota), or unlimited usage by entering your own free Gemini API key in Settings.
Provenance & AI Tagging: Entries parsed by Gemini are tagged source: "ai_text" and display a distinctive "AI parsed" badge in the Transaction Detail Sheet.

🎙️ 2. Native Voice-to-Hisab

Tap the microphone and speak your transaction in Hinglish or English.
Real-time transcription via Web Speech API with instantaneous parsing directly into the ledger.

👁️ 3. Multimodal Gemini 2.0 Flash Vision OCR

Receipt & Invoice Scanner: Point your camera at thermal paper slips, invoices, or grocery bills.
Handwritten Khata Reader: Reads handwritten dairy pages and bahi-khata notebooks.
Multi-Item Extraction: Breaks down bundled receipts into categorized sub-entries with vendor association and user-provided API key quota controls.

📖 4. Smart Bahi-Khata Ledger Engine

Khata Directionality: Strict accounting conventions — clearly monitors "You owe" vs. "They owe you".
Entity Relationship Tagging: Organize contacts by Customer, Supplier, Employee, Partner, Freelancer, or Personal.
Nickname & Alias System: Attach nicknames (e.g. "Pappu", "Hardware Shop") so the parser always resolves the right person.
One-Tap Settle Up: Seamless debt reconciliation with auto-generated settlement records.

📊 5. Dynamic Financial Insights & Analytics

Multi-Period Filters: Filter instantly by Today, This Week, This Month, Last Month, This Year, or All Time.
Visual Category Donut: Interactive breakdown of your highest spending categories.
Daily Spending Trend Charts: Clean SVG visualization of daily cash flow.
Auto-Generated Financial Health Cards: Contextual warnings on spike spending, highest-debt customers, and cash vs. digital split.

📲 6. Progressive Web App (PWA) & Offline Mode

Installable on Any Device: Native standalone experience on iOS (Safari Add to Home Screen) and Android (Chrome PWA prompt).
Service Worker Offline Caching: Full cache fallback for core assets and routes, allowing continuous access even in zero-connectivity areas.

📄 7. PDF Statements & 1-Tap WhatsApp Dispatch

Custom-Engineered PDF Export: Auto-formatted account statements with transaction histories, debt balance boxes, and clean rupee typography.
WhatsApp Direct Dispatch: Native Web Share API integration to send PDFs or formatted ledger balances directly to party WhatsApp numbers.

☁️ 8. Dual-Mode Cloud Architecture & Google Auth

Signed-Out Mode: 100% offline-ready, single-device localStorage persistence.
Signed-In Mode: Supabase Cloud Sync with Row-Level Security (RLS), Google 1-Tap OAuth & Email/Password auth, optimistic UI updates, and automatic seed-to-cloud migration on first login.

🎨 9. Pastel & Sage Design System

Mobile-First Luxury UI: Designed with delicate pastel tones, soft borders, clean card elevation, and tactile typography.
Smooth Spring Physics: Powered by motion with gesture-driven swipeable sheets and tactile haptics.
Instant Theme Switching: Sage (warm earthy palette) and Indigo (crisp modern palette) with zero-flash CSS variable tokens.

🎭 260+ Avatar System

Hisab includes a built-in library of 260+ vibrant 3D & illustrated WebP avatars with deterministic name hashing. Every party, vendor, and business profile receives a unique, charming avatar automatically:

_Astronaut	_Dragon	_Alpaca	_{Arctic Fox}	_Axolotl	_Beagle	_Bee	_Bento
_Bonsai	_Camera	_Cat	_Corgi	_Coffee	_Badger	_{Baby Seal}	_Backpack

...and 244+ more collectible avatars optimized for instant rendering!

🏪 300+ Pre-Configured Merchant Intelligence

Hisab includes an extensive built-in dictionary of 300+ top Indian and global merchants across food delivery, quick commerce, groceries, dining, shopping, utilities, travel, subscriptions, and digital payments. When you mention any brand or alias in your natural language entry, Hisab automatically recognizes the vendor, renders its official brand logo, and pre-categorizes the expense:

_Swiggy	_Zomato	_Blinkit	_Zepto	_BigBasket	_McDonald's	_Domino's	_Starbucks
_Amazon	_Flipkart	_Myntra	_Uber	_Ola	_Apple	_Netflix	_Spotify
_Paytm	_PhonePe	_{Google Pay}	_Airtel	_Jio	_DMart	_{Apollo 24\|7}	_IRCTC

...and 276+ more pre-mapped merchants with automatic brand colors, aliases & auto-categorization!

💡 Hybrid NLP & AI Engine in Action

Hisab dynamically routes parsing based on your chosen engine mode (Local, Smart Auto, or Always AI):

Input: "Sent 4500 to Sharma Hardware for cement via UPI"
│
├── 🤖 Engine       : Gemini 2.0 Flash / Local Fallback
├── 💰 Amount       : ₹4,500
├── 👤 Entity       : Sharma Hardware (matched alias: "cement supplier")
├── 🏷️ Category     : Construction / Materials (matched keyword: "cement")
├── 🔄 Direction    : Outgoing ("You gave")
├── 💳 Payment      : UPI
├── 🏷️ Source       : ai_text (Tagged with "AI parsed" badge)
└── 🎯 Confidence   : 98% (Auto-suggests one-tap record)

Input Sample	Detected Entity	Amount	Category	Direction	Source
`500 diesel petrol pump`	None	₹500	Fuel & Travel	Outgoing	Local (<2ms)
`Ramesh gave 1200 cash for rent`	Ramesh	₹1,200	Rent & Utilities	Incoming	Local (<2ms)
`Paid 15000 salary to Mukesh via NEFT`	Mukesh	₹15,000	Salaries & Wages	Outgoing	Gemini AI
`Tea snacks with client 120`	None	₹120	Food & Dining	Outgoing	Local (<2ms)
`Received 5000 from ABC Corp for invoice 42`	ABC Corp	₹5,000	Sales / Income	Incoming	Gemini AI

🏗️ System Architecture

flowchart TD
    subgraph Client ["Client (Browser / PWA / Service Worker)"]
        UI["React 19 + Next.js App Router"]
        Input["HisabInput (Thinking State & Fallback)"]
        Voice["Web Speech API"]
        OCR["Camera / Receipt Upload"]
        LocalParser["Local NLP & Phonetic Engine (<2ms)"]
        AIHelper["src/lib/aiParser.ts"]
        Store["Dual-Mode State Layer (Optimistic Store)"]
        SW["Service Worker (Offline Cache)"]
    end

    subgraph AI_Cloud ["AI & Cloud Services"]
        GeminiText["Gemini 2.0 Flash (/api/parse-text)"]
        GeminiVision["Gemini 2.0 Flash Vision (/api/scan-receipt)"]
        SupabaseAuth["Supabase Auth (Google OAuth & Email)"]
        SupabaseDB[("Supabase PostgreSQL (RLS & Profiles)")]
        PDFGen["jsPDF + AutoTable Engine"]
    end

    Input --> |Local / Fallback| LocalParser
    Input --> |Smart Auto / Always AI| AIHelper
    Voice --> Input
    AIHelper --> GeminiText
    GeminiText -.-> |Silent Fallback on Timeout| LocalParser
    OCR --> GeminiVision
    GeminiVision --> Store
    LocalParser --> Store
    AIHelper --> Store
    Store <--> |Signed Out| LocalStorage[("Browser localStorage")]
    Store <--> |Signed In / Optimistic Sync| SupabaseDB
    Store --> PDFGen
    PDFGen --> WhatsApp["WhatsApp / Web Share API"]
    SW <--> UI

🛠️ Tech Stack Matrix

Layer	Technology	Purpose
Core Framework	Next.js 16 (App Router)	Turbopack-powered SSR/CSR hybrid web application
UI & Runtime	React 19 + TypeScript 5	High-performance UI state management & full type safety
Styling	Tailwind CSS v4	Utility-first styling with custom CSS variable themes
Animations & UX	Motion (Framer Motion)	Spring physics, swipeable bottom sheets & micro-interactions
Artificial Intelligence	Google Gemini 2.0 Flash	Multimodal vision OCR for receipts & handwritten ledgers
Backend & Database	Supabase (PostgreSQL)	Google OAuth, relational schema, and Row-Level Security
PWA & Offline	Progressive Web App	Service worker offline caching and home-screen installability
Document Generation	jsPDF + jspdf-autotable	Client-side vector PDF statement generator with Rupee formatting
Icons & Avatars	Lucide React + 260+ WebP Avatars	Deterministic visual representation and lightweight SVG icons

📂 Repository Structure

HisabAI/
├── web/
│   ├── src/
│   │   ├── app/
│   │   │   ├── (app)/                  # Main app route group (BottomNav shell)
│   │   │   │   ├── page.tsx            # Home dashboard & quick hisab entry
│   │   │   │   ├── accounts/           # Bahi-Khata ledger & party detail pages
│   │   │   │   ├── entries/            # Full date-grouped transaction history
│   │   │   │   ├── insights/           # Analytics, donuts, trends & cards
│   │   │   │   └── more/               # Settings, themes, categories, export
│   │   │   ├── api/
│   │   │   │   └── scan-receipt/       # Gemini 2.0 Flash multimodal OCR route
│   │   │   ├── login/                  # Auth portal (Google OAuth / Email)
│   │   │   └── onboarding/             # Guided setup wizard
│   │   ├── components/
│   │   │   ├── hisab/                  # Account detail, transaction row, OCR modal
│   │   │   ├── layout/                 # BottomNav, page headers, error banners
│   │   │   ├── onboarding/             # Step-by-step onboarding wizard screens
│   │   │   ├── theme/                  # Theme script, provider, & selector
│   │   │   └── ui/                     # Cards, chips, bottom sheets, icon badges
│   │   └── lib/
│   │       ├── parser.ts               # Local NLP parser & phonetic normalizer
│   │       ├── store.tsx               # Unified Dual-Mode State Provider
│   │       ├── avatars.ts              # 260+ Avatar catalog & deterministic hasher
│   │       ├── categories.ts           # Category dictionary & keyword registry
│   │       ├── statementPdf.ts         # PDF statement engine with Rupee support
│   │       ├── whatsapp.ts             # Direct WhatsApp sharing handler
│   │       ├── selectors.ts            # Khata balance computation algorithms
│   │       └── supabase/               # SSR client, server queries, RLS mappers
│   └── public/
│       ├── Assets/                     # Brand logos, icons, & 260+ avatars
│       ├── screenshots/                # Showcase captures for web & mobile
│       ├── sw.js                       # Service worker for PWA offline caching
│       └── manifest.json               # Web App Manifest
└── UI Plan/                            # Complete product UX specifications & mockups

🚀 Getting Started

Follow these steps to run Hisab AI locally on your machine.

📋 Prerequisites

Node.js: v18.18.0 or later (Node 20+ recommended)
Package Manager: npm, pnpm, or yarn
Supabase Account (optional, for cloud sync): supabase.com
Google Gemini API Key (optional, for AI receipt scanning): Google AI Studio

📥 1. Clone the Repository

git clone https://github.com/Magraa/Hisab-AI.git
cd Hisab-AI/web

📦 2. Install Dependencies

npm install

⚙️ 3. Configure Environment Variables

Create a .env.local file in the web directory:

# Supabase Configuration (Optional for cloud sync)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key

# Gemini AI Vision Key (Optional - users can also provide their own key in Settings)
GEMINI_API_KEY=your-gemini-api-key

Note: Hisab runs 100% locally out-of-the-box using browser localStorage if Supabase environment variables are omitted!

💻 4. Run Development Server

npm run dev

Open http://localhost:3000 (or http://localhost:3100 if custom port is used) in your browser.

🏗️ 5. Build for Production

npm run build
npm run start

🔒 Database & Security Model

When Supabase is enabled, Hisab enforces strict PostgreSQL Row-Level Security (RLS):

-- Example RLS Policy for Transactions
ALTER TABLE public.transactions ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can only access their own transactions"
ON public.transactions
FOR ALL
USING (auth.uid() = user_id)
WITH CHECK (auth.uid() = user_id);

Zero Data Leaks: Every entity, transaction, and profile is scoped to auth.uid().
Encrypted Local Storage: Client keys and offline entries remain on your hardware.
Client-Side Key Option: Users can input their personal Gemini API key stored strictly in local memory.

🗺️ Roadmap

🤝 Contributing

Contributions make the open-source community thrive. Any contributions you make are greatly appreciated!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'feat: add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

Crafted with ❤️ for Indian MSMEs, Freelancers, and Small Businesses.

Hisab AI • Your business. Your Hisab.

Name		Name	Last commit message	Last commit date
public		public
scripts		scripts
src		src
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
middleware.ts		middleware.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

🌟 Overview

📱 Live UI Showcase

⚡ Superpowers & Core Features

🧠 1. Hybrid Natural Language Entry & Gemini 2.0 Flash AI Parsing

🎙️ 2. Native Voice-to-Hisab

👁️ 3. Multimodal Gemini 2.0 Flash Vision OCR

📖 4. Smart Bahi-Khata Ledger Engine

📊 5. Dynamic Financial Insights & Analytics

📲 6. Progressive Web App (PWA) & Offline Mode

📄 7. PDF Statements & 1-Tap WhatsApp Dispatch

☁️ 8. Dual-Mode Cloud Architecture & Google Auth

🎨 9. Pastel & Sage Design System

🎭 260+ Avatar System

🏪 300+ Pre-Configured Merchant Intelligence

💡 Hybrid NLP & AI Engine in Action

🏗️ System Architecture

🛠️ Tech Stack Matrix

📂 Repository Structure

🚀 Getting Started

📋 Prerequisites

📥 1. Clone the Repository

📦 2. Install Dependencies

⚙️ 3. Configure Environment Variables

💻 4. Run Development Server

🏗️ 5. Build for Production

🔒 Database & Security Model

🗺️ Roadmap

🤝 Contributing

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🌟 Overview

📱 Live UI Showcase

⚡ Superpowers & Core Features

🧠 1. Hybrid Natural Language Entry & Gemini 2.0 Flash AI Parsing

🎙️ 2. Native Voice-to-Hisab

👁️ 3. Multimodal Gemini 2.0 Flash Vision OCR

📖 4. Smart Bahi-Khata Ledger Engine

📊 5. Dynamic Financial Insights & Analytics

📲 6. Progressive Web App (PWA) & Offline Mode

📄 7. PDF Statements & 1-Tap WhatsApp Dispatch

☁️ 8. Dual-Mode Cloud Architecture & Google Auth

🎨 9. Pastel & Sage Design System

🎭 260+ Avatar System

🏪 300+ Pre-Configured Merchant Intelligence

💡 Hybrid NLP & AI Engine in Action

🏗️ System Architecture

🛠️ Tech Stack Matrix

📂 Repository Structure

🚀 Getting Started

📋 Prerequisites

📥 1. Clone the Repository

📦 2. Install Dependencies

⚙️ 3. Configure Environment Variables

💻 4. Run Development Server

🏗️ 5. Build for Production

🔒 Database & Security Model

🗺️ Roadmap

🤝 Contributing

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages