How zatobox/main works
Project Type & Purpose
– Full-stack, modular POS system (“ZatoBox”)
– Three main services:
• Frontend (Next.js)
• Backend API (FastAPI) + Admin Panel (Streamlit)
• OCR microservice (FastAPI + Google Gemini)
– Persistent store: Supabase (PostgreSQL)
– External integrations: Supabase Auth, Cloudinary, payment gateways (Polar, cash), Google Gemini AI
High-Level Components
A. User/Browser
B. Frontend Application
• Next.js (app router under src/app, components under src/components)
• Public assets (public/images, shared/)
C. Backend Core API
• FastAPI server
• Domain modules: auth, products, inventory, category, layout, etc. (backend/back/*)
• OCR client module (backend/OCR/client.ts) integration
D. OCR Service
• FastAPI (backend/OCR)
• Google Gemini AI for image analysis
E. Admin Dashboard
• Streamlit app (backend/admin-dashboard)
• Connects to Core API
F. Database & Storage
• Supabase (PostgreSQL + Auth)
• Cloudinary (media storage)
G. External Services
• Google Gemini AI
• Payment providers (Polar, cash)
• Deployment environments (Vercel, Render, Docker)
Relationships & Data Flows
– Browser ↔ Frontend: HTTP/HTTPS requests, WebSocket or SSE if used
– Frontend → Backend API: REST calls via Axios to endpoints (e.g., /auth, /products, /inventory, /checkout)
– Backend API → Supabase DB: SQL queries via psycopg2/custom repo, Supabase Auth for JWT
– Backend API → OCR Service: HTTP POST /extract-product
– OCR Service → Google Gemini: API calls for image OCR
– Backend API → Cloudinary: Image uploads/downloads
– Frontend → Supabase Auth: Token-based login/register flows
– Admin Dashboard → Backend API: same REST endpoints, Swagger docs
– Backend API → Payment gateways: webhook endpoints (/webhooks/cart-checkout, /webhooks/polar)
Architectural Patterns & Design Principles
– Service decomposition: Core API vs. OCR microservice vs. Admin UI
– Module-per-domain in backend (auth, product, inventory, layout)
– Next.js App-Router with server components and client components
– State management (Zustand) and form handling (React Hook Form, Formik)
– Repository pattern in backend (models.ts, repository.ts, service.ts per module)
– Rate limiting at OCR service
– Environment separation: local dev vs. Vercel/Render vs. Docker