← Back to Projects
bridge

Monarch Money Bridge

Monarch Money is great — but it doesn't natively support foreign banks or currencies. This bridges that gap: share single receipts or batch upload up to 20 images at once from your phone. It OCRs them with Gemini AI, converts currencies at exact historical rates, and seamlessly syncs transactions directly into your Monarch account.

Python FastAPI PostgreSQL Gemini 3 Batch Mode (v2.5) Async Worker Pool Frankfurter API PWA Fernet Encryption
View on GitHub
Status ✅ Live (Self-hosted)
Type PWA + API Server
Batch Mode Up to 20 Receipts (v2.5)
Platform Mobile / Web
AI Engine Gemini 3 (OCR + Hinting)
Backend FastAPI + PostgreSQL

✨ Core Features

⚡

Multi-Receipt Batch Mode (v2.5)

Upload up to 20 receipt images at once via file picker or drag-and-drop. Preview thumbnails in an interactive staging strip with per-item removal and dynamic queue additions.

🚦

Controlled Concurrency & Session Reuse

Processes batch queues through an async semaphore worker pool to prevent API rate limits, while sharing pre-authenticated Monarch sessions across workers for optimal speed.

📊

Continuous Live Progress Tracking

Real-time aggregate progress bar computing weighted sub-step completion with 400ms polling, live item cards (Queued, Scanning, Synced, Duplicate, Failed), and step logs.

✏️

Post-Batch Review & In-Place Editing

Interactive detail modal on batch cards allowing one-click star toggling, date corrections with automatic forex recalculation, category selection, and force-sync for duplicates.

⭐

Starred & Favorite Merchants

Mark and prioritize frequently used merchants for fast lookup, one-click selection, and automated suggestion prioritization across workflows.

🌍

Automatic Currency Conversion

Detects EUR, GBP, and other foreign currencies — automatically converts them to USD using historical exchange rates (Frankfurter API) for the exact transaction date.

🧙‍♂️

AI OCR with Merchant Hinting

Gemini 3 extracts Merchant, Date, and Amount. Contextualizes scans with historical merchant mappings for confidence-based canonical naming and instant category assignment.

🤖

Auto-Mapping Engine & Category Sync

Define custom rules to auto-rename merchants and assign Monarch categories (with emojis 🍔). Preserves original amounts and forex metadata directly in Monarch notes.

📱

Native Share Sheet & PWA

Installed as a standalone PWA appearing in your phone's native Share menu for direct single-tap camera roll sharing with instant Service Worker interception.

✍️

Manual Entry Mode

Quickly add transactions by hand — Amount, Currency, Date, Merchant — without needing a receipt photo, with full multi-currency and auto-conversion support.

🔒

Secure & Resilient Architecture

Credentials encrypted at rest with Fernet. Persistent failed-transaction queue with one-click retry, and stealth Ghost Cookie authorization returning 404 to unauthorized scanners.

🛠️ Architecture & Pipeline Workflows

🔄

Dual Ingestion Pipelines

Supports both single-image instant share (Hash → De-duplication → OCR → Conversion → Push) and concurrent batch queues (Async Semaphore → Shared Session → Background Processing → Streaming Status).

🧠

Context-Aware Merchant Hinting

Supplies Gemini with sorted historical merchant mappings before scanning. Matches canonical names with ≥75% confidence and automatically resolves mapped categories.

🛡️

Persistent Recovery Queue

Failed scans or network interruptions are stored in a dedicated database queue (failed_transactions) with review modal, inline editing, and one-click retry support.

👻

Stealth Ghost Mode & Security

Fernet encryption for all stored credentials and a 10-year device activation cookie mechanism that returns HTTP 404 to arbitrary web crawlers and port scanners.

← Back to Projects