Finalog

Presenting... Finalog, the financials logger - a streamlined pipeline for transcribing transactions directly to your spreadsheet!

The backbone of the app runs in Python using OpenCV + mss for screen capture and image segmentation, PyQt6 for GUI elements, and Gemini for transaction processing. It functions primarily based on macOS's iPhone Mirroring capabilities, allowing users to initiate scans of their phone screens. Since it is screen capture, Gemini will attempt to parse out any transactions in the captured image.

Quickstart

Install the app via pip!

pip install finalog

The initial setup will run on start. Please ensure you have the following:

• Gemini API key
• Google Sheets ID
• Google Sheets JSON key credentials file

See more info below if you do not have the Google Sheets API info (it is optional)

Configure Google Sheets

The Google Sheets integration works with this set procedure. Follow all steps, it seems complex but is not trust 👍

1. Enable the API
   • Go to the Google Cloud Console and create a new project.
   • Navigate to APIs & Services > Library, then search for "Google Sheets API".
   • Select the API and click Enable.
2. Configure a Service Account
   • Click the back arrows back to the API & Services homepage
   • Navigate to the Credentials tab, and click Create Credentials > Service account in the top-center of screen
   • Fill out the name, ID, and description for the account
   • Go to the Keys Tab - click the Keys Tab at the top of the page
   • Add a new key: click the Add Key dropdown and select Create new key
   • Choose JSON: Select JSON as the key type and click Create
   • Download and Save: The JSON file will automatically download to your computer. Store it securely, as !! this is the only copy you will ever get !!
3. Configure YOUR spreadsheet
   • Copy the Service Account email to your clipboard
   • Share your spreadsheet to this email as an Editor
   • Keep your saved JSON key credentials in a known location and ensure you know the path to the JSON credentials file

Run config to setup API keys and other settings!!

finalog config

---

The Finalog app (web + desktop)

Beyond the CLI capture tool above, Finalog is also a full app: a Next.js + Tailwind + TypeScript frontend (also packaged as an Electron desktop app), a FastAPI backend, and Supabase (Postgres + Auth) for data and accounts.

app/
  frontend/   Next.js (App Router, static export) + Electron shell
  backend/    FastAPI — Supabase data layer + Gemini image parsing
db/           schema.sql (reference) · seed.sql (demo data, per-user)
deploy/       nginx.conf — single-port reverse proxy (frontend + /api)

Data flow: the browser signs in with Supabase Auth (JWT), sends it to the backend as a Bearer token; the backend verifies it and scopes every query to that user. See app/frontend/README.md, app/backend/README.md, and app/DEPLOY.md for the deep dives.

Prerequisites (one-time)

1. Supabase — create a project, then in the SQL editor run db/seed.sql (creates the tables + demo data). Create the seed user (Dashboard → Authentication → Add user, e.g. you@example.com), and set Auth → URL Configuration → Site URL to your domain. Grab from Settings → API: Project URL, the publishable key, the secret key.
2. Backend app/backend/.env (copy from .env.example):

   SUPABASE_URL=https://<ref>.supabase.co
   SUPABASE_SECRET_KEY=sb_secret_…
   SUPABASE_SCHEMA=app          # or public, matching where seed.sql created the tables
   GEMINI_API_KEY=…             # for screenshot/receipt parsing
   API_PREFIX=                  # leave EMPTY — nginx strips /api
   

3. Frontend app/frontend/.env.local:

   NEXT_PUBLIC_API_URL=/api     # relative → same-origin via the proxy (no CORS)
   NEXT_PUBLIC_SUPABASE_URL=https://<ref>.supabase.co
   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_…
   

Run — local dev (frontend + backend only)

Two terminals; the frontend talks straight to the backend.

# backend  → http://localhost:8000
cd app/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --reload --port 8000          # docs at /docs

# frontend → http://localhost:3000
cd app/frontend
npm install
npm run dev

For pure local dev set NEXT_PUBLIC_API_URL=http://localhost:8000 and API_PREFIX= empty, and add http://localhost:3000 to the backend's FRONTEND_ORIGINS.

Run — full stack behind one port (the deploy topology)

nginx puts the frontend and backend behind a single port so it's same-origin (no CORS) and Cloudflare/AWS only reaches one endpoint:

nginx :9009 ─┬─ /api/*  → backend  :9011   (/api stripped)
             └─ /*      → frontend :9015

# 1 — backend (API_PREFIX empty)
cd app/backend && source .venv/bin/activate
uvicorn app:app --host 127.0.0.1 --port 9011

# 2 — frontend (build the static export, serve it)
cd app/frontend && npm run build && npx serve out -l 9015

# 3 — nginx (from the repo root)
nginx -c "$(pwd)/deploy/nginx.conf" -g 'daemon off;'

# 4 — expose it (Cloudflare Tunnel → http://localhost:9009)
cloudflared tunnel run <tunnel-name>

Then open your domain (or http://localhost:9009 to test without the tunnel). Full proxy/deploy notes — including the AWS path — are in deploy/README.md and app/DEPLOY.md.

Desktop (Electron)

cd app/frontend
npm run electron:dev     # Next dev + Electron window together
npm run electron:build   # packaged installers (dmg/zip · nsis · AppImage)