npm run dev

backend/README.md

@@ -0,0 +1,137 @@
+# Slip Scanner Backend (FastAPI)
+
+FastAPI service exposing a /scan endpoint to process receipt images:
+
+- Validates Supabase user via Authorization: Bearer <supabase_jwt>
+- Detects edges and crops the receipt (OpenCV, perspective transform)
+- Performs OCR via Hugging Face Inference API (TrOCR)
+- Uploads the cropped image to Supabase Storage
+- Inserts a row into the slips table with extracted metadata
+
+## Prerequisites
+
+- Python 3.11+
+- Supabase project with Storage and Postgres
+- Hugging Face account and API token
+
+## Environment Variables
+
+Create a .env file in backend/ with:
+
+SUPABASE_URL=...
+SUPABASE_ANON_KEY=...
+SUPABASE_SERVICE_ROLE_KEY=...
+SUPABASE_STORAGE_BUCKET=slips
+
+HUGGINGFACE_API_TOKEN=...
+HF_OCR_MODEL=microsoft/trocr-base-printed
+
+FRONTEND_CORS_ORIGIN=http://localhost:3000
+
+Notes:
+
+- Use the Service Role key server-side only. Never expose it to the frontend.
+- If you prefer signed URLs, adjust upload_bytes_to_supabase_storage accordingly and do not make the bucket public.
+
+## Install & Run (Windows PowerShell)
+
+cd backend
+python -m venv .venv
+. .venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
+
+## API
+
+### Health
+
+GET http://localhost:8000/health
+
+### Scan
+
+POST http://localhost:8000/scan
+Authorization: Bearer <supabase_jwt>
+Content-Type: multipart/form-data
+file=@/path/to/receipt.jpg
+
+cURL example:
+
+curl -X POST http://localhost:8000/scan \
+ -H "Authorization: Bearer $SUPABASE_JWT" \
+ -F "file=@receipt.jpg"
+
+Response:
+{
+"ok": true,
+"slip": {
+"id": "...",
+"user_id": "...",
+"image_url": "https://...",
+"amount": 250.0,
+"category": "Food",
+"raw_text": "...",
+"created_at": "2025-09-15T10:00:00Z",
+"crop_confidence": 0.8
+}
+}
+
+## Supabase Setup
+
+### Storage Bucket (public or signed)
+
+- Create bucket slips.
+- For public previews, enable public read on the bucket or a specific folder per user. Alternatively, keep private and generate signed URLs server-side.
+
+### Table
+
+Create table slips (adjust types as desired):
+
+create table if not exists public.slips (
+id uuid primary key default gen_random_uuid(),
+user_id uuid not null,
+image_path text not null,
+image_url text,
+raw_text text,
+amount numeric,
+category text,
+crop_confidence real,
+created_at timestamptz not null default now()
+);
+
+alter table public.slips enable row level security;
+
+RLS policies (only owner reads/writes their slips):
+
+create policy "slips select own" on public.slips
+for select
+using (auth.uid() = user_id);
+
+create policy "slips insert own" on public.slips
+for insert
+with check (auth.uid() = user_id);
+
+create policy "slips update own" on public.slips
+for update
+using (auth.uid() = user_id);
+
+### Frontend Config
+
+In Next.js .env.local:
+
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_SUPABASE_URL=...
+NEXT_PUBLIC_SUPABASE_ANON_KEY=...
+
+From the client, include the Supabase session JWT as the Authorization header when calling /scan.
+
+## Design Notes (rules.md alignment)
+
+- Mobile-first UX is handled in the Next.js app; backend is stateless and fast.
+- No sensitive keys in frontend; backend uses Service Role for Storage/DB.
+- Performance: edge detection and OCR happen server-side; images are resized and optimized.
+- Security: RLS ensures users only see their own slips; Storage access can be scoped.
+
+## Dev Tips
+
+- OpenAPI docs: http://localhost:8000/docs
+- If HF model cold-starts and returns 503, retry the request after a few seconds.

backend/__init__.py

@@ -0,0 +1,2 @@
+# Makes backend a package for uvicorn import paths
+

backend/main.py

@@ -0,0 +1,158 @@
+from fastapi import FastAPI, File, UploadFile, HTTPException, Header
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.responses import JSONResponse
+import io
+import os
+import uuid
+from datetime import datetime, timezone
+
+from utils.image_processing import crop_receipt_from_image
+from utils.ocr import run_hf_ocr
+from utils.supabase_helpers import (
+    fetch_user_from_supabase_token,
+    upload_bytes_to_supabase_storage,
+    insert_slip_row,
+)
+
+
+APP_NAME = "Slip Scanner Backend"
+
+try:
+    from dotenv import load_dotenv  # type: ignore
+    load_dotenv()
+except Exception:
+    # Optional dependency; ignore if not present
+    pass
+
+app = FastAPI(title=APP_NAME)
+
+
+frontend_origin = os.getenv("FRONTEND_CORS_ORIGIN", "*")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[frontend_origin] if frontend_origin != "*" else ["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def health():
+    required_env = [
+        "SUPABASE_URL",
+        "SUPABASE_ANON_KEY",
+        "SUPABASE_SERVICE_ROLE_KEY",
+        "SUPABASE_STORAGE_BUCKET",
+        "HUGGINGFACE_API_TOKEN",
+    ]
+    missing = [k for k in required_env if not os.getenv(k)]
+    return {
+        "service": APP_NAME,
+        "status": "ok" if not missing else "degraded",
+        "missing_env": missing,
+    }
+
+
+@app.post("/scan")
+async def scan(
+    file: UploadFile = File(...),
+    authorization: str | None = Header(default=None, convert_underscores=False),
+):
+    # Validate auth header
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Missing or invalid Authorization header")
+
+    user_jwt = authorization.split(" ", 1)[1]
+    user = fetch_user_from_supabase_token(user_jwt)
+    if not user or not user.get("id"):
+        raise HTTPException(status_code=401, detail="Invalid Supabase session")
+
+    user_id = user["id"]
+
+    # Read upload
+    original_bytes = await file.read()
+    if not original_bytes:
+        raise HTTPException(status_code=400, detail="Empty file upload")
+
+    # Crop receipt via edge detection & perspective transform
+    try:
+        cropped_bytes, crop_meta = crop_receipt_from_image(original_bytes)
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail=f"Failed to process image: {exc}")
+
+    # OCR via Hugging Face Inference API
+    try:
+        ocr_text = run_hf_ocr(cropped_bytes)
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"OCR failed: {exc}")
+
+    # Extract naive amount (ZAR or generic currency) and a fallback category
+    amount = _extract_amount(ocr_text)
+    category = _infer_category(ocr_text)
+
+    # Upload cropped image to Supabase Storage
+    bucket = os.getenv("SUPABASE_STORAGE_BUCKET", "slips")
+    object_name = f"{user_id}/{uuid.uuid4()}.jpg"
+    try:
+        public_url = upload_bytes_to_supabase_storage(
+            bucket=bucket,
+            object_path=object_name,
+            content_bytes=cropped_bytes,
+            content_type="image/jpeg",
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"Upload failed: {exc}")
+
+    # Insert DB row into slips table
+    try:
+        inserted = insert_slip_row(
+            {
+                "user_id": user_id,
+                "image_path": object_name,
+                "image_url": public_url,
+                "raw_text": ocr_text,
+                "amount": amount,
+                "category": category,
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "crop_confidence": crop_meta.get("confidence"),
+            }
+        )
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"Database insert failed: {exc}")
+
+    return JSONResponse(
+        {
+            "ok": True,
+            "slip": inserted,
+        }
+    )
+
+
+def _extract_amount(text: str) -> float | None:
+    import re
+
+    if not text:
+        return None
+    # Look for amounts with optional currency symbol/letter (e.g., R250.00, $12.34)
+    candidates: list[float] = []
+    for match in re.finditer(r"(?:R|\$)?\s*(\d{1,3}(?:[\,\s]\d{3})*(?:\.\d{2})?|\d+(?:\.\d{2}))", text, flags=re.IGNORECASE):
+        num_str = match.group(1).replace(",", "").replace(" ", "")
+        try:
+            candidates.append(float(num_str))
+        except ValueError:
+            continue
+    return max(candidates) if candidates else None
+
+
+def _infer_category(text: str) -> str:
+    text_l = (text or "").lower()
+    if any(k in text_l for k in ["fuel", "petrol", "gas"]):
+        return "Fuel"
+    if any(k in text_l for k in ["restaurant", "meal", "food", "dine"]):
+        return "Food"
+    if any(k in text_l for k in ["grocery", "supermarket", "market", "store"]):
+        return "Grocery"
+    return "Uncategorized"
+
+

backend/requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.115.6
+uvicorn[standard]==0.32.0
+python-multipart==0.0.9
+requests==2.32.3
+opencv-python-headless==4.10.0.84
+numpy==2.1.3
+supabase==2.7.4
+starlette==0.41.3
+python-dotenv==1.0.1
+

backend/utils/image_processing.py

@@ -0,0 +1,88 @@
+import cv2
+import numpy as np
+from typing import Tuple, Dict
+import io
+
+
+def crop_receipt_from_image(image_bytes: bytes) -> Tuple[bytes, Dict]:
+    """Detect receipt edges and return a perspective-corrected JPEG.
+
+    Returns (jpeg_bytes, meta)
+    meta: { confidence: float, width: int, height: int }
+    """
+    image_array = np.frombuffer(image_bytes, dtype=np.uint8)
+    img = cv2.imdecode(image_array, cv2.IMREAD_COLOR)
+    if img is None:
+        raise ValueError("Invalid image data")
+
+    orig = img.copy()
+    ratio = 500.0 / max(img.shape[0], img.shape[1])
+    if ratio < 1.0:
+        img = cv2.resize(img, None, fx=ratio, fy=ratio, interpolation=cv2.INTER_AREA)
+
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    gray = cv2.GaussianBlur(gray, (5, 5), 0)
+    edged = cv2.Canny(gray, 50, 150)
+
+    contours, _ = cv2.findContours(edged.copy(), cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+    contours = sorted(contours, key=cv2.contourArea, reverse=True)[:10]
+
+    receipt_contour = None
+    for c in contours:
+        peri = cv2.arcLength(c, True)
+        approx = cv2.approxPolyDP(c, 0.02 * peri, True)
+        if len(approx) == 4:
+            receipt_contour = approx
+            break
+
+    if receipt_contour is None:
+        # Fallback: treat whole image as receipt
+        h, w = img.shape[:2]
+        receipt_contour = np.array([[[0, 0]], [[w - 1, 0]], [[w - 1, h - 1]], [[0, h - 1]]])
+        confidence = 0.2
+    else:
+        confidence = 0.8
+
+    pts = receipt_contour.reshape(4, 2).astype("float32")
+    # Order points: top-left, top-right, bottom-right, bottom-left
+    rect = _order_points(pts)
+    (tl, tr, br, bl) = rect
+
+    width_top = np.linalg.norm(tr - tl)
+    width_bottom = np.linalg.norm(br - bl)
+    max_width = int(max(width_top, width_bottom))
+
+    height_right = np.linalg.norm(br - tr)
+    height_left = np.linalg.norm(bl - tl)
+    max_height = int(max(height_right, height_left))
+
+    dst = np.array(
+        [[0, 0], [max_width - 1, 0], [max_width - 1, max_height - 1], [0, max_height - 1]],
+        dtype="float32",
+    )
+
+    M = cv2.getPerspectiveTransform(rect, dst)
+    warped = cv2.warpPerspective(img, M, (max_width, max_height))
+
+    # Slight contrast enhancement and grayscale for OCR readiness
+    warped_gray = cv2.cvtColor(warped, cv2.COLOR_BGR2GRAY)
+    warped_eq = cv2.equalizeHist(warped_gray)
+
+    # Encode as JPEG
+    success, jpeg = cv2.imencode('.jpg', warped_eq, [int(cv2.IMWRITE_JPEG_QUALITY), 90])
+    if not success:
+        raise ValueError("Failed to encode JPEG")
+
+    return jpeg.tobytes(), {"confidence": float(confidence), "width": int(max_width), "height": int(max_height)}
+
+
+def _order_points(pts: np.ndarray) -> np.ndarray:
+    x_sorted = pts[np.argsort(pts[:, 0]), :]
+    left = x_sorted[:2, :]
+    right = x_sorted[2:, :]
+
+    tl, bl = left[np.argsort(left[:, 1]), :]
+    tr, br = right[np.argsort(right[:, 1]), :]
+    return np.array([tl, tr, br, bl], dtype="float32")
+
+

backend/utils/ocr.py

@@ -0,0 +1,34 @@
+import os
+import requests
+
+
+HF_MODEL = os.getenv("HF_OCR_MODEL", "microsoft/trocr-base-printed")
+
+
+def run_hf_ocr(image_bytes: bytes) -> str:
+    token = os.getenv("HUGGINGFACE_API_TOKEN")
+    if not token:
+        raise RuntimeError("Missing HUGGINGFACE_API_TOKEN")
+
+    # Use Inference API for text recognition
+    url = f"https://api-inference.huggingface.co/models/{HF_MODEL}"
+    headers = {"Authorization": f"Bearer {token}"}
+    response = requests.post(url, headers=headers, data=image_bytes, timeout=60)
+    if response.status_code >= 400:
+        raise RuntimeError(f"HF API error: {response.status_code} {response.text}")
+
+    try:
+        data = response.json()
+    except Exception as exc:
+        raise RuntimeError(f"Invalid HF response: {exc}")
+
+    # trocr returns dicts with 'generated_text'
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        text = data[0].get("generated_text")
+        if isinstance(text, str):
+            return text
+
+    # fallback to raw
+    return str(data)
+
+

backend/utils/supabase_helpers.py

@@ -0,0 +1,71 @@
+import os
+from typing import Dict, Any
+from supabase import create_client, Client
+import requests
+
+
+def _get_supabase_client() -> Client:
+    url = os.getenv("SUPABASE_URL")
+    key = os.getenv("SUPABASE_SERVICE_ROLE_KEY") or os.getenv("SUPABASE_ANON_KEY")
+    if not url or not key:
+        raise RuntimeError("Missing SUPABASE_URL or SUPABASE_*_KEY")
+    return create_client(url, key)
+
+
+def fetch_user_from_supabase_token(jwt: str) -> Dict[str, Any] | None:
+    # Validate JWT via auth endpoint
+    supabase_url = os.getenv("SUPABASE_URL")
+    if not supabase_url:
+        return None
+    resp = requests.get(
+        f"{supabase_url}/auth/v1/user",
+        headers={
+            "Authorization": f"Bearer {jwt}",
+            "apikey": os.getenv("SUPABASE_ANON_KEY", ""),
+        },
+        timeout=20,
+    )
+    if resp.status_code != 200:
+        return None
+    return resp.json()
+
+
+def upload_bytes_to_supabase_storage(
+    bucket: str,
+    object_path: str,
+    content_bytes: bytes,
+    content_type: str = "application/octet-stream",
+) -> str:
+    client = _get_supabase_client()
+    storage = client.storage.from_(bucket)
+    storage.upload(object_path, content_bytes, {
+        "contentType": content_type,
+        "upsert": False,
+    })
+    # Create public URL (assumes bucket is public or policy allows reads)
+    # Handle both string or dict responses across library versions
+    url_candidate = storage.get_public_url(object_path)
+    if isinstance(url_candidate, dict):
+        public_url = (
+            url_candidate.get("publicUrl")
+            or url_candidate.get("public_url")
+            or url_candidate.get("url")
+        )
+    else:
+        public_url = str(url_candidate)
+
+    if not public_url:
+        # Fallback construct (public bucket assumption)
+        base = os.getenv("SUPABASE_URL", "").rstrip("/")
+        public_url = f"{base}/storage/v1/object/public/{bucket}/{object_path}"
+    return public_url
+
+
+def insert_slip_row(row: Dict[str, Any]) -> Dict[str, Any]:
+    client = _get_supabase_client()
+    response = client.table("slips").insert(row).select("*").execute()
+    if not response.data:
+        raise RuntimeError("Insert returned no data")
+    return response.data[0]
+
+