TapSure Agentic MVP

---

© 2026 Zero Gravity Engineering (Pty) Ltd. All rights reserved worldwide.

Chief Architect & Author: Zebbediah Winston Beck Genesis Core Team: Founding contributors

NOTICE: All code, designs, and documentation in this repository are the exclusive property of Zero Gravity Engineering (Pty) Ltd. No changes, contributions, or derivative works may be made—even by Genesis Core Team or founding members—unless a Non-Disclosure Agreement (NDA) is signed and approved by the Steering Committee of Zero Gravity Engineering (Pty) Ltd. This policy is binding for all contributors, including core engineers, and applies to all current and future contributions. Any attempt to modify, use, or disclose any part of this application without explicit written consent is strictly prohibited.

Contributors may only join this project by invitation and after signing an NDA.

---

An event-driven multi-agent insurance MVP: upload a receipt, get instant coverage recommendations, and confirm protection.

Stack

• Backend: FastAPI + simple agent modules (OpenAI optional)
• Frontend: Vanilla HTML/CSS/JS (mobile-first)

Quick start

1. Backend

• Create a virtual env
  • Windows (PowerShell) python -m venv .venv .venv\Scripts\Activate.ps1
• Install deps pip install -r backend/requirements.txt
• Configure env copy backend/.env.example backend/.env

  set OPENAI_API_KEY if you want AI OCR/LLM; otherwise fallback heuristics run

• Run API uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2. Frontend

• Open frontend/index.html in a browser, or serve statically (e.g., python -m http.server 5173 -d frontend)
• By default it calls http://localhost:8000

Key endpoints

• POST /api/receipt/analyze (multipart file: receipt)
• POST /api/coverage/recommend (JSON receipt payload)
• POST /api/flow/confirm (JSON selection)
• POST /api/chat (JSON {message})

---

POS-ready automation roadmap (color-coded todo)

Legend:

• = required to be a reliable POS automation product
• = strongly recommended for adoption + ops
• = good polish / later

Product wedge (stop being “generic insurance”)

• Pick 1–2 POS use-cases (e.g., receipt-based protection / reimbursement) and remove everything else from the happy path.
• Define the decision output contract: approve / deny / needs-more-info, with explicit reasons and required evidence.
• Add a “human handoff” lane (merchant support / insurer ops) instead of pretending 100% can be automated.

POS ingestion (how merchants actually feed you data)

• Add a POS webhook/API ingestion route (digital receipt payload) alongside image upload.
• Support idempotency keys + retries (POS systems will resend events).
• Normalize receipt line items (SKU/UPC, category, quantity, price, tax, merchant id, timestamp).
• Build “adapters” per POS/provider (keep core logic provider-agnostic).

Pricing + coverage engine (cost-effective + explainable)

• Make coverage recommendation deterministic-first with transparent formulas + rule traces (LLM only for parsing ambiguous text).
• Add hard constraints: max item value, excluded categories, jurisdiction flags, waiting periods.
• Add configurable rule tables per insurer/merchant program (multi-tenant config, not code changes).
• Add a calibration harness with golden receipts + expected outputs (regression safety).

Automation workflow (end-to-end, not a demo)

• Introduce a first-class Case model: intake → extracted data → decision → policy/confirmation → audit.
• Persist cases (SQLite/Postgres) and make the flow resumable.
• Add outbound webhooks for: decision ready, policy issued, exception required.

Security, privacy, and trust (table stakes for insurers)

• Replace promo-code gating with real auth (merchant API keys / OAuth) + tenant isolation.
• Rate limiting + upload limits + content-type validation + malware scanning strategy.
• PII handling: redaction support, retention policy, deletion endpoint, minimal logging of sensitive fields.
• Add an audit log: who/what/when for every decision and data mutation.

Reliability & ops (so it doesn’t die at checkout)

• Add async processing for OCR/LLM (queue) so POS calls stay fast (<500ms) and results arrive via webhook/poll.
• Add structured logging + request IDs + metrics (latency, error rate, cost per case).
• Add cost controls: LLM call budget per case, caching, and “LLM-off mode” parity tests.

Integration deliverables (what partners expect)

• Publish an integration spec: webhook schemas, auth, retries, idempotency, status codes.
• Provide a reference POS “button” flow: offer → accept → pay → policy issuance.
• Add SDK snippets (JS/Python) + Postman collection for partners.

Notes

• OpenAI is optional. You can run 100% free using:
  • OCR: Tesseract (open-source)
  • LLM: Ollama local models (OpenAI-compatible API)
• This is an MVP for rapid iteration and can be swapped to LangGraph/Temporal later.

Serverless frontend-only mode (no Python, no Ollama)

• Just run a static server; OCR and parsing happen entirely in the browser using Tesseract.js.

  npx serve frontend -l 5173
  

• When the API isn’t reachable, the UI auto-switches to local OCR + local recommendation.
• To re-enable the real backend later, start the API and refresh the page.

Free setup (no paid APIs)

1. Install Tesseract OCR (Windows):
   • Download: https://github.com/tesseract-ocr/tesseract
   • After install, add tesseract.exe to PATH or set TESSERACT_CMD in backend/.env
2. Install Ollama and pull a model:
   • https://ollama.com/download
   • Run in a terminal: ollama pull llama3.1:8b
   • (Optional) For vision models use: ollama pull llama3.2-vision:11b
3. Configure backend/.env: LLM_BASE_URL=http://localhost:11434/v1 LLM_API_KEY=ollama LLM_MODEL=llama3.1:8b

   TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe

4. Start the backend and front-end as above.

---

🟢🟡🔴 Run Everything (scripts, copy/paste)

Legend: 🟢 recommended · 🟡 optional/helpful · 🔴 strict/fail-fast

🟢 1) Install everything (first time)

./install-all.sh

🟢 2) Run backend + frontend-v2 (recommended)

./dev-all.sh

• Backend: http://localhost:8000
• Frontend-v2: http://localhost:5174
• Logs: .logs/backend.log and .logs/frontend-v2.log

🟡 Run with max logging + POS QR enforced (demo mode)

This turns on HTTP logs + frontend API logs and enforces QR-gating.

./dev-all-verbose.sh

🟢 Run just one piece

Backend only:

./dev-backend.sh

Frontend-v2 only:

./dev-frontend-v2.sh

Legacy static frontend only:

./dev-frontend-static.sh

🟡 Kill stuck dev servers/ports

./kill-latent.sh

🔴 Run tests (strict, fail-fast)

./test-all-strict.sh

---

🟢 POS QR demo (anti-abuse flow)

1. Generate a demo receipt image with a signed TSQR1 token QR:

./gen-demo-pos-qr.sh
ls -la backend/fixtures/demo_pos_qr_receipt.png

2. Run the backend with tenant secrets configured:

POS_TENANT_SECRETS='{"demo":"dev-secret"}' \
POS_QR_ENFORCEMENT=on \
./dev-backend.sh

3. Upload backend/fixtures/demo_pos_qr_receipt.png in the UI.

Optional QR diagnostics (prints decoded texts):

./debug-qr.sh backend/fixtures/demo_pos_qr_receipt.png

---

🟡 Useful env toggles

Backend:

• TAPSURE_DEBUG_HTTP=1 (detailed HTTP request/response logs)
• POS_QR_ENFORCEMENT=on|off|auto (default: on)
• POS_REQUIRE_QR=1 (force QR required)
• POS_TENANT_SECRETS='{"demo":"dev-secret"}' (required to verify tokens)
• POS_QR_MAX_AGE_SECONDS=900, POS_QR_MAX_FUTURE_SKEW_SECONDS=60, POS_QR_MAX_BYTES=3000000

Frontend-v2 (read at dev-server startup):

• VITE_API_URL=http://localhost:8000
• VITE_DEBUG_LOGGING=1 (logs every API call in the browser console)
• VITE_POS_REQUIRE_QR=1 (adds X-POS-Require-QR: 1 header for uploads)