# zatobox/main architecture

> Architecture diagram of the GitHub repository zatobox/main, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zatobox/main
- Repository: https://github.com/zatobox/main

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js)"
        direction TB
        NextApp["Next.js Frontend"]:::frontend
        subgraph "Sub-layers"
            direction TB
            AppRouter["App Router (src/app/)"]:::frontend
            Components["UI Components (src/components/)"]:::frontend
            PublicAssets["Public Assets (public/ & shared/)"]:::frontend
            Services["Services (src/services/)"]:::frontend
            Context["State Management (src/context/)"]:::frontend
            Utils["Client Helpers (src/utils/)"]:::frontend
            APIRoutes["Edge API Routes (src/app/api/)"]:::frontend
        end
    end

    %% Supabase Utils under Frontend
    subgraph "Supabase Utils"
        direction TB
        SBClient["Client (src/utils/supabase/client.ts)"]:::frontend
        SBMiddleware["Middleware (src/utils/supabase/middleware.ts)"]:::frontend
        SBServer["Server Helpers (src/utils/supabase/server.ts)"]:::frontend
        SBPolar["Polar Integration (src/utils/supabase/polar.ts)"]:::frontend
    end

    Utils --> SBClient
    Utils --> SBMiddleware
    Utils --> SBServer
    Utils --> SBPolar

    %% Services details
    subgraph "Payment Services"
        direction TB
        PSPolar["Polar Service (src/services/polar.service.ts)"]:::frontend
        PSCash["Cash Payments Service (src/services/cash-payments.service.ts)"]:::frontend
    end
    Services --> PSPolar
    Services --> PSCash

    %% Backend Core API
    subgraph "Backend Core API (FastAPI)"
        direction TB
        CoreAPI["FastAPI Core API"]:::backend
        subgraph "Domain Modules"
            direction TB
            AuthMod["Auth Module (backend/auth/)"]:::backend
            CatMod["Category Module (backend/back/category/)"]:::backend
            InvMod["Inventory Module (backend/back/inventory/)"]:::backend
            LayMod["Layout Module (backend/back/layout/)"]:::backend
            ProdMod["Product Module (backend/back/product/)"]:::backend
        end
        OCRClient["OCR Client Integration (backend/OCR/client.ts)"]:::backend
        OCRHandler["OCR Handler (backend/OCR/handlers.ts)"]:::backend
        subgraph "Webhooks Endpoints"
            direction TB
            WH1["Cart Checkout (src/app/api/webhooks/cart-checkout/route.ts)"]:::backend
            WH2["Polar Webhook (src/app/api/webhooks/polar/route.ts)"]:::backend
            WH3["Setup Webhook (src/app/api/webhooks/setup/route.ts)"]:::backend
        end
    end

    %% OCR Microservice
    subgraph "OCR Microservice (FastAPI)"
        direction TB
        OCRService["OCR Service"]:::backend
        OCRSvcHandlers["Handlers (backend/OCR/handlers.ts)"]:::backend
        OCRSvcClient["Google Gemini Client (backend/OCR/client.ts)"]:::backend
    end

    %% Admin Dashboard
    Admin["Admin Dashboard (Streamlit)"]:::backend

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        SupabaseDB["Supabase (PostgreSQL + Auth)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        CloudinaryExt["Cloudinary"]:::external
        GeminiExt["Google Gemini AI"]:::external
        PolarExt["Payment: Polar"]:::external
        CashExt["Payment: Cash"]:::external
    end

    %% Browser
    Browser["Browser / User"]:::external

    %% Relationships
    Browser -->|HTTP/HTTPS| AppRouter
    AppRouter -->|"REST /auth, /products, /inventory"| CoreAPI
    Services -->|calls REST API| CoreAPI
    APIRoutes -->|"POST /ocr"| OCRService
    CoreAPI -->|"SQL via Supabase Client"| SupabaseDB
    CoreAPI -->|"Auth via Supabase"| SupabaseDB
    CoreAPI -->|"POST /extract-product"| OCRService
    OCRService -->|"calls Gemini API"| GeminiExt
    CoreAPI -->|"upload/download"| CloudinaryExt
    Admin -->|"REST endpoints"| CoreAPI
    CoreAPI -->|Webhooks| WH1
    CoreAPI -->|Webhooks| WH2
    CoreAPI -->|Webhooks| WH3
    PSPolar -->|"to Polar gateway"| PolarExt
    PSCash -->|"to Cash gateway"| CashExt

    %% Click Events
    click AppRouter "https://github.com/zatobox/main/tree/main/src/app/"
    click Components "https://github.com/zatobox/main/tree/main/src/components/"
    click PublicAssets "https://github.com/zatobox/main/tree/main/public/"
    click Services "https://github.com/zatobox/main/tree/main/src/services/"
    click Context "https://github.com/zatobox/main/tree/main/src/context/"
    click Utils "https://github.com/zatobox/main/tree/main/src/utils/"
    click APIRoutes "https://github.com/zatobox/main/tree/main/src/app/api/"
    click SBClient "https://github.com/zatobox/main/blob/main/src/utils/supabase/client.ts"
    click SBMiddleware "https://github.com/zatobox/main/blob/main/src/utils/supabase/middleware.ts"
    click SBServer "https://github.com/zatobox/main/blob/main/src/utils/supabase/server.ts"
    click SBPolar "https://github.com/zatobox/main/blob/main/src/utils/supabase/polar.ts"
    click PSPolar "https://github.com/zatobox/main/blob/main/src/services/polar.service.ts"
    click PSCash "https://github.com/zatobox/main/blob/main/src/services/cash-payments.service.ts"
    click AuthMod "https://github.com/zatobox/main/tree/main/backend/auth/"
    click CatMod "https://github.com/zatobox/main/tree/main/backend/back/category/"
    click InvMod "https://github.com/zatobox/main/tree/main/backend/back/inventory/"
    click LayMod "https://github.com/zatobox/main/tree/main/backend/back/layout/"
    click ProdMod "https://github.com/zatobox/main/tree/main/backend/back/product/"
    click OCRClient "https://github.com/zatobox/main/blob/main/backend/OCR/client.ts"
    click OCRHandler "https://github.com/zatobox/main/blob/main/backend/OCR/handlers.ts"
    click WH1 "https://github.com/zatobox/main/blob/main/src/app/api/webhooks/cart-checkout/route.ts"
    click WH2 "https://github.com/zatobox/main/blob/main/src/app/api/webhooks/polar/route.ts"
    click WH3 "https://github.com/zatobox/main/blob/main/src/app/api/webhooks/setup/route.ts"
    click OCRSvcHandlers "https://github.com/zatobox/main/blob/main/backend/OCR/handlers.ts"
    click OCRSvcClient "https://github.com/zatobox/main/blob/main/backend/OCR/client.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef backend  fill:#D6F5D6,stroke:#028A0F,stroke-width:1px
    classDef datastore fill:#FFE8A1,stroke:#CC7A00,stroke-width:1px
    classDef external fill:#E8E8E8,stroke:#666666,stroke-width:1px
```
