KhoAI - AI-Powered Inventory Management System

An intelligent inventory management system for Vietnamese businesses featuring invoice scanning, voice commands, and batch photo counting.

Features

• Invoice Scanning - Claude AI extracts data from receipt/invoice images
• Voice Commands - Whisper + Claude for Vietnamese/English inventory commands
• Batch Photo Counting - Grounding DINO for zero-shot object detection
• Odoo Integration - Sync with Odoo ERP for purchase orders and inventory

Tech Stack

Component	Technology
Backend	Python 3.11+, FastAPI, SQLAlchemy, Celery
Mobile	React Native, Expo
Web	React, Vite, TypeScript
Database	PostgreSQL
Cache/Queue	Redis
Storage	MinIO/S3
Auth	Keycloak
AI	Anthropic Claude, OpenAI Whisper, Grounding DINO

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+
• Docker & Docker Compose (optional)

Quick Start with Docker

The easiest way to run the full stack:

cd infrastructure
docker-compose up -d

This starts all services: API, PostgreSQL, Redis, MinIO, and Keycloak.

Manual Setup

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
python -m pip install -r requirements.txt

# Copy environment file and configure
copy .env.example .env   # Windows
cp .env.example .env     # Linux/Mac

# Run database migrations
alembic upgrade head

# Start the API server
uvicorn app.main:app --reload --port 8000

The API will be available at http://localhost:8000

API documentation: http://localhost:8000/api/v1/docs

2. Start Celery Worker (for async tasks)

In a separate terminal:

cd backend
celery -A app.tasks.celery_app worker --loglevel=info --pool=solo

3. Web Frontend Setup

cd web

# Install dependencies
npm install

# Start development server
npm run dev

The web app will be available at http://localhost:5173

4. Mobile App Setup

cd mobile

# Install dependencies
npm install

# Start Expo development server
npx expo start

# Run on specific platform
npx expo start --ios      # iOS Simulator
npx expo start --android  # Android Emulator

Environment Variables

Create a .env file in the backend directory. See backend/.env.example for all options.

Required Variables

# AI Services
ANTHROPIC_API_KEY=sk-ant-...      # Required for invoice scanning
OPENAI_API_KEY=sk-...             # Required for voice commands

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=khoai
POSTGRES_PASSWORD=your_password
POSTGRES_DB=khoai

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Storage (MinIO/S3)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_INVOICES=invoices
S3_BUCKET_VOICE=voice
S3_BUCKET_COUNTING=counting

Optional Variables

# Keycloak (disable for development)
KEYCLOAK_ENABLED=false
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=khoai
KEYCLOAK_CLIENT_ID=khoai-api

# Odoo Integration
ODOO_URL=http://localhost:8069
ODOO_DB=odoo
ODOO_USERNAME=admin
ODOO_PASSWORD=admin

Development Mode

For local development without Keycloak, use the dev token:

curl -H "Authorization: Bearer dev-token" http://localhost:8000/api/v1/products

Project Structure

kho-ai/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # REST endpoints
│   │   ├── core/           # Security, database
│   │   ├── models/         # SQLAlchemy models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   └── tasks/          # Celery tasks
│   ├── alembic/            # Database migrations
│   └── tests/              # Backend tests
├── mobile/                  # React Native/Expo app
├── web/                     # React/Vite web app
├── infrastructure/          # Docker, seed scripts, Keycloak config
└── docs/                    # Architecture and workflow documentation

API Endpoints

Method	Endpoint	Description
POST	/api/v1/invoices/scan	Upload and scan invoice
GET	/api/v1/invoices	List invoices
GET	/api/v1/invoices/{id}	Get invoice details
PUT	/api/v1/invoices/{id}	Update invoice
POST	/api/v1/invoices/{id}/confirm	Confirm invoice
POST	/api/v1/voice/command	Process voice command
POST	/api/v1/counting/analyze	Analyze batch photos
GET	/api/v1/products	List products
GET	/api/v1/locations	List warehouse locations

Xe Kem Test Data Setup

The project includes seed scripts for Xe Kem (Vietnamese Ice Cream & Dessert Shop) to populate Odoo and KhoAI with real business data. This is useful for development, testing, and demo purposes.

Prerequisites

1. Odoo 17 running at localhost:8069 with database xekem created
2. KhoAI backend running at localhost:8000
3. PostgreSQL, Redis, and MinIO running
4. backend/.env configured with Odoo credentials

Step 1: Start Odoo

cd infrastructure
docker-compose -f docker-compose.odoo.yml up -d

Open http://localhost:8069 and create the xekem database if it doesn't exist. Install the Inventory and Purchase modules.

Step 2: Seed Odoo Data

This creates suppliers, product categories, warehouses, and ~90 products in Odoo:

cd infrastructure
python seed_xekem_odoo.py

What gets created:

Data	Count	Details
Product Categories	23	Hierarchical: Packaging > Cups & Lids, Dry Materials > Spices, etc.
Warehouses	2	Mississauga (MSS), North York (NYK)
Suppliers	17	Cash & Carry, Mr. Dairy, PreGel, Viet Thai, Foods Up, etc.
Products	~90	Cups, lids, boxes, syrups, powders, dairy, frozen items, fresh ingredients

Each product has a SKU (e.g., PKG-CC-003), category, cost price, and linked supplier.

Step 3: Seed KhoAI Data

This syncs Odoo data to KhoAI and configures supplier name patterns for invoice auto-detection:

cd infrastructure
python seed_xekem_khoai.py

What it does:

1. Syncs suppliers from Odoo to KhoAI (POST /api/v1/suppliers/sync)
2. Updates supplier name patterns for auto-detection from invoice vendor names, e.g.:
   • "Cash & Carry" invoice → matches supplier CC via patterns ["cash & carry", "cash and carry", "c&c"]
   • "FreshCo" invoice → matches supplier WS via patterns ["freshco", "nofrills", "walmart"]
3. Syncs products from Odoo to KhoAI (POST /api/v1/products/sync)

Step 4: Verify Setup

# Check suppliers are synced with patterns
curl -H "Authorization: Bearer dev-token" \
  "http://localhost:8000/api/v1/suppliers?page_size=100"

# Test supplier auto-detection
curl -H "Authorization: Bearer dev-token" \
  "http://localhost:8000/api/v1/suppliers/detect/by-vendor-name?vendor_name=Cash%20%26%20Carry"

# Check products are synced
curl -H "Authorization: Bearer dev-token" \
  "http://localhost:8000/api/v1/products?page_size=100"

Step 5: Test Invoice Scanning

Upload a test receipt from backend/tests/receipts/xekem/:

curl -X POST -H "Authorization: Bearer dev-token" \
  -F "file=@backend/tests/receipts/xekem/CashAndCarry_2026Feb03.png" \
  "http://localhost:8000/api/v1/invoices/scan"

Or use the web UI at http://localhost:5173 to upload and review invoices.

Test Receipts Available

File	Supplier	Items
CashAndCarry_2026Feb03.png	Cash & Carry	Cups, lids, boxes, gloves, parchment paper
FoodsUp_2026Feb02.png	Foods Up	Eggs, flour, sugar
FreshCo_2026Feb05.png	FreshCo (Western)	Dairy, fresh produce
HDBio_2026Jan30.png	HD Bio	Packaging boxes, containers
MrDairy_2026Feb04.png	Mr. Dairy	Milk, whipping cream, butter
PreGel_2026Jan25.png	PreGel	Ice cream base, stabilizer
VietThai_2026Jan28.png	Viet Thai	Thai tea, condensed milk, frozen durian
MilkTeaSupply_2026Jan31.png	Milk Tea Supply	Syrups, tea, flavourings
SeowNation_2026Feb05.png	Seow Nation	Frozen durian
LuckySupermarket_2026Feb01.png	Lucky Supermarket	Asian groceries, spices

Full Invoice-to-Odoo Flow

See docs/Invoice-Scanning-to-Odoo-Flow.md for the complete workflow from scanning to receiving inventory in Odoo.

Data Migration Plan

See docs/XeKem-Data-Migration-Plan.md for the full spreadsheet analysis and product catalog design.

Running Tests

cd backend
pytest tests/ -v

Common Issues

"email-validator is not installed"

pip install email-validator

Circular import errors

Ensure you're using the latest code with lazy imports in service files.

Database connection refused

Make sure PostgreSQL is running:

# Docker
docker-compose up -d postgres

# Or check local PostgreSQL service

Redis connection refused

Make sure Redis is running:

# Docker
docker-compose up -d redis

# Or check local Redis service

License

Proprietary - All rights reserved