tabbych/checkbill-ocr-backend

CheckBill App

CheckBill is a static bill-splitting web app with offline-friendly OCR for receipts.

Features

• —Split bills across multiple people
• —Save bills locally in the browser
• —Generate PromptPay QR codes
• —OCR receipt upload with offline Tesseract assets
• —Thai, English, Chinese, Japanese, and Korean OCR support
• —Auto-detect OCR mode
• —Local English translation for CJK receipt items

Local Usage

Serve the project over HTTP instead of opening index.html via file:// because OCR uses workers and WASM.

Example:

python3 -m http.server 8000

Then open http://localhost:8000.

Backend OCR with EasyOCR

The frontend now tries to call a FastAPI OCR backend first, then falls back to browser OCR if the backend is unavailable.

Install dependencies with PDM:

pdm install

Run the OCR API:

pdm run dev

Then set the API base in index.html if needed:

<meta name="checkbill-api-base" content="http://127.0.0.1:8001">

If that meta tag is left empty:

• —on localhost or 127.0.0.1, the frontend defaults to http://127.0.0.1:8001
• —on any other host, the frontend calls /api/receipt/ocr on the same origin

Free Backend Deploy Option

The simplest free host for the Python OCR backend is a Hugging Face Docker Space.

Why this fits:

• —official free CPU Basic hardware is available for Spaces
• —Docker Spaces support custom FastAPI containers
• —the backend can expose a plain HTTP API for the Pages frontend

Official docs used:

• —https://huggingface.co/docs/hub/en/spaces-overview
• —https://huggingface.co/docs/hub/en/spaces-sdks-docker

Files already prepared for this path:

• —Dockerfile
• —.dockerignore

Suggested Hugging Face Space settings:

• —SDK: Docker
• —App port: 7860
• —Visibility: Public

Once the Space is live, set the frontend API base in index.html:

<meta name="checkbill-api-base" content="https://tabbych-checkbill-ocr-backend.hf.space">

Sync GitHub to Hugging Face Space

This repository includes a GitHub Actions workflow template for syncing main to a Hugging Face Space.

What you need to set in GitHub repository secrets:

• —HF_TOKEN: a Hugging Face write token
• —HF_SPACE_REPO_ID: in the format username/space-name

Deploy on Cloudflare Pages

This project is best deployed as a static site on Cloudflare Pages.

Use these settings when creating the Pages project:

• —Framework preset: None
• —Production branch: main
• —Build command: exit 0
• —Build output directory: /
• —Root directory: leave blank

Cloudflare Pages docs used for this setup:

• —https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
• —https://developers.cloudflare.com/pages/configuration/build-configuration/

After connecting the GitHub repository, Cloudflare will deploy index.html and the assets/ folder directly from the repository root.