GitHub - ZatoBox/main: ZatoBox is an open-source modular POS empowering SMEs to digitalize, sell online ZatoLink, and connect payments with ZatoConnect.

Most small businesses still run inventory and sales with spreadsheets, notes, and fragmented tools. ZatoBox is an open-source alternative: a simple POS + inventory workflow with an Smart Inventory (OCR importer) to digitize products directly from invoices. Bitcoin on-chain is optional and non-custodial.

Status: actively developed. New modules and improvements are continuously being added as the platform expands.
Visit our website »

Watch Demo · Report a Bug · Request a Feature

Table of Contents

General Description
System Architecture
Technologies
Frontend
Backend
OCR
Installation and Configuration
Deployment
Contribution
License
Useful Links

General Description

ZatoBox is a modern and comprehensive Point of Sale system that integrates three main components, designed to be modular and scalable:

Frontend: Modern user interface built with Next.js, React, and TypeScript.
Backend: Robust REST API with FastAPI and an administrative panel.
OCR: Optical Character Recognition service with Google Gemini 1.5 Flash.

System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Frontend     │    │     Backend     │    │      OCR        │
│   (Next.js)     │◄──►│   (FastAPI)     │◄──►│   (FastAPI)     │
│   Port: 3000    │    │   Port: 4444    │    │   Port: 5000    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Vercel/       │    │   Render /      │    │   Render /      │
│   Local Dev     │    │   Local Dev     │    │   Local Dev     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │    Supabase     │
                       │   (Database)    │
                       └─────────────────┘

The frontend handles the user interface, the backend manages business logic and data persistence with Supabase (PostgreSQL) and Cloudinary for images. The OCR service extracts data from documents using Google Gemini 1.5 Flash.

Technologies

Frontend

Main Technologies

Framework: Next.js 15.5.0 with React 19.1.0
Language: TypeScript
Styles: Tailwind CSS 4
UI Components: Radix UI
State Management: Zustand and React Context API
Forms: React Hook Form + Formik + Yup
Authentication: Supabase Auth
HTTP Client: Axios

Main Features

Modern and responsive interface for product, inventory, order, and subscription management.
Complete authentication system with JWT, including registration, login, and profile management. Social login integration is planned.
Real-time inventory management with filtering, bulk operations, and JSON product import.
Support for cash and cryptocurrency payments (BTCPay Server integration).
Online catalog management (ZatoLink). (working)
OCR integration for document processing and product creation from extracted data.
Plugin store to extend application functionality.
Product management with image uploads to Cloudinary.

Starting the Frontend

cd frontend

# Install dependencies
pnpm install

# Configure environment variables
cp .env.example .env.local
# Edit .env.local with your credentials

# Development mode
pnpm dev

Required Environment Variables

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_OCR_API_URL=http://localhost:8001

Backend

Backend Architecture

The backend is divided into two components:

1. Main API (zato-csm-backend)

Framework: FastAPI 0.116.1
Database: Supabase (PostgreSQL)
Authentication: JWT + Supabase Auth
ORM: Custom repository with psycopg2
Validation: Pydantic 2.11.7
Modules: Authentication, profiles, categories, inventory, layouts, products, payments (cash and BTCPay), OCR.
Image Management: Cloudinary.
Documentation: Automatic OpenAPI (Swagger).

2. Admin Panel (admin-dashboard)

Framework: Streamlit
Functionality: Administrative dashboard with metrics.
Integration: Connects with the main API.
Current Status: Currently not operational. Requires attention for functionality.

Main Features

Complete REST API with automatic documentation (Swagger).
JWT authentication system with role-based access control.
Full CRUD for products, inventory, sales, and categories.
Store layout management.
Custom middleware for security and access control.
Image handling with Cloudinary.
Payment processing (cash and cryptocurrency via BTCPay Server).
Encryption/decryption functions (zatobox/main/src/utils/crypto.ts, zatobox/main/src/utils/crypto.utils.ts) for sensitive data handling.

Starting the Backend

Main API

cd backend/zato-csm-backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your credentials

# Start server
uvicorn main:app --reload --port 4444

Admin Panel

cd backend/admin-dashboard

# Install dependencies (if not already installed)
pip install streamlit requests pandas

# Start dashboard
streamlit run main.py --server.port 8080 (dashboard is not working)

Backend Environment Variables

SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_service_role_key
SUPABASE_JWT_SECRET=your_supabase_jwt_secret
SECRET_KEY=your_secret_key_for_jwt
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret

Main Endpoints

Auth: /auth/login, /auth/register, /auth/me
Products: /products/ (complete CRUD)
Inventory: /inventory/ (stock management)
Sales: /sales/ (sales processing)
Layouts: /layouts/ (store configuration)
OCR: /ocr/extract-data (document data extraction)
BTCPay: /btcpay/create-invoice, /btcpay/webhook

OCR

Technologies

Framework: FastAPI
AI: Google Gemini 1.5 Flash
Processing: Image and PDF analysis with generative AI

Features

Advanced optical character recognition.
Product data extraction from images and PDFs.
Rate limiting (5 minutes between requests per user) to manage API usage.
Processing of multiple image formats.
Integration with the main API for product creation.

Starting the OCR Service

cd OCR

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your Gemini API key

# Start server
uvicorn main:app --reload --port 500

OCR Environment Variables

GEMINI_API_KEY=your_google_gemini_api_key

OCR Endpoints

POST /extract-product/: Extract product information from images.
GET /health: Service health check.

Installation and Configuration

Prerequisites

Node.js 18+ and pnpm
Python 3.8+
Supabase account
Google AI account (for Gemini API)
Cloudinary account (optional, for images)

Complete Configuration

Clone the repository

git clone https://github.com/ZatoBox/main.git
cd main

Configure Database
- Create a project in Supabase.
- Run necessary SQL migrations.
- Obtain URL and API keys.
Configure each service (follow specific instructions above).
Recommended startup order:
1. Backend API (port 4444)
2. OCR Service (port 5000)
3. Frontend (port 3000)
4. Admin Panel (port 8080) - Note: The admin panel is not currently working.

Deployment

Docker

The project includes Dockerfiles for the backend and OCR:

# Build images
docker build -f Dockerfile.backend -t zatobox-backend .
docker build -f Dockerfile.ocr -t zatobox-ocr .

# Run containers
docker run -p 8000:8000 zatobox-backend
docker run -p 8001:8001 zatobox-ocr

Production

Frontend: Vercel (recommended)
Backend + OCR: Railway, Render, or any Docker provider.
Database: Supabase (already included).

Refer to DEPLOYMENT.md for detailed deployment instructions.

Contribution

Fork the project.
Create a branch for your feature (git checkout -b feature/AmazingFeature).
Commit your changes (git commit -m 'Add: AmazingFeature').
Push to the branch (git push origin feature/AmazingFeature).
Open a Pull Request.

Top Contributors

License

This project is licensed under the MIT License. See the LICENSE.txt file for more details.

Useful Links

Made with ❤️ by the ZatoBox team

Name		Name	Last commit message	Last commit date
Latest commit History 699 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
.vscode		.vscode
public		public
shared/images		shared/images
src		src
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE.txt		LICENSE.txt
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vercel.json		vercel.json

License

ZatoBox/main

Folders and files

Latest commit

History

Repository files navigation

General Description

System Architecture

Technologies

Technologies

Frontend

Main Technologies

Main Features

Starting the Frontend

Required Environment Variables

Backend

Backend Architecture

1. Main API (zato-csm-backend)

2. Admin Panel (admin-dashboard)

Main Features

Starting the Backend

Main API

Admin Panel

Backend Environment Variables

Main Endpoints

OCR

Technologies

Features

Starting the OCR Service

OCR Environment Variables

OCR Endpoints

Installation and Configuration

Prerequisites

Complete Configuration

Deployment

Docker

Production

Contribution

Top Contributors

License

Useful Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 8

Uh oh!

Languages

Packages