Engineering

The problem with transaction descriptions

Bank transaction descriptions are not designed for humans. A coffee shop visit shows up as SQ *VERVE COFFEE ROASTERS 408-298-XXXX CA. A recurring Netflix charge looks like NETFLIX.COM 866-579-XXXX CA. A Zelle transfer arrives as ZELLE PAYMENT FROM JOHN S with no category information at all.

A naive classifier would either over-rely on keyword matching (fragile, high maintenance) or fire up a cloud LLM (slow, expensive, privacy-hostile). Sieve does neither.

Six ordered stages

Each transaction passes through stages in order. The first stage to produce a confident result wins; subsequent stages are skipped. The six stages are:

1. User corrections — if the user previously recategorized this merchant, that mapping is applied first. User intent always wins.
2. Rules engine — deterministic pattern matching against a library of merchant patterns and bank-specific signals (CC payment detection, payroll recognition, bank fee tags). No model inference needed for well-known patterns.
3. Model inference — a trained classifier runs in WebAssembly or pure JS depending on the environment. Handles novel merchants the rules engine doesn't recognize.
4. Field extraction — pulls structured fields from the description: amount signs, transfer references, merchant names with noise stripped.
5. Post-model reclassification — catches systematic model errors. For example, the model sometimes misclassifies high-value round-number credits as "Income" when they're transfers. This stage corrects those.
6. Confidence review — transactions below the confidence threshold are flagged for manual review rather than silently miscategorized.

The merchant database

Sieve ships with a local merchant database seeded from 715 patterns extracted from the rules engine. Lookups happen against IndexedDB (on desktop) or in-memory (on iPhone), so there's no parsing overhead per transaction. When a merchant is seen for the first time and doesn't match an existing pattern, the model takes over.

Running on iPhone

Swift apps can't run JavaScript natively, so we built a bundler step (npm run build:iphone) that compiles Sieve into a single sift.bundle.js file loaded by a JSEngine.swift wrapper. The entire classification pipeline runs inside a WKWebView JavaScript context — same code, same results, no server needed on mobile.

Why local-first?

Personal finance data is unusually sensitive. Your transactions reveal where you shop, what you eat, where you travel, who you pay, and roughly how much money you have. The mainstream approach — ship it to a SaaS backend and query it via an API — means trusting a startup you've never heard of with some of the most personal data you have.

The local-first model inverts this. The canonical copy of your data lives on your device. The app is a view over that data. Sync is an optional add-on, not the primary architecture.

Desktop: Electron + IndexedDB

The desktop app (Mac and Windows) is an Electron shell wrapping a web app. Transactions are stored in IndexedDB — the same storage API used by web apps, exposed natively in the Chromium renderer. The current schema is version 6:

// DB_VERSION = 6
// Object stores:
//   transactions    — the primary ledger
//   rules           — user-defined categorization rules
//   imports         — import history log
//   accounts        — bank account metadata
//   merchants       — local merchant database (715+ patterns)
//   schema_meta     — version-checked schema manifest

Each DB version bump adds a migration. Migrations are one-way and sequential — version N is always applied before version N+1. The migration runner is tested against real DB snapshots to catch regressions before they ship.

iPhone: SwiftData + CloudKit

On iPhone, transactions are stored in SwiftData (Core Data under the hood) with automatic CloudKit sync for users who opt into iCloud. The sync is end-to-end encrypted by Apple — SiftDo can't read your data even if we wanted to. Cross-device sync (Mac → iPhone) works through the same CloudKit container without any relay server.

Windows: CloudKit JS

Apple's CloudKit isn't available on Windows, so we built a CloudKit JS client (app/js/cloudkit-sync.js) that communicates with iCloud via Apple's CloudKit Web Services API. Windows users who also have a Mac get seamless cross-device sync without installing any Apple software.

The honest trade-offs

Local-first is not free. It makes certain things harder:

• Schema migration is your problem, not the database's. Every field rename or store addition requires a migration script and upgrade path.
• Cross-device conflict resolution requires care. We use last-write-wins for most fields but track per-transaction corrections separately to avoid clobbering user edits.
• No server-side search or aggregation. Every query runs against the local DB. For 50,000 transactions this is fast; for millions it would need rethinking.

For a personal finance app used by one person on two or three devices, these are acceptable trade-offs. The privacy guarantee is real, not marketing copy.

How detection works

SiftDo auto-detects format from the CSV header. The detectFormat() function scans the first line and matches against bank-specific fingerprints. Order matters — some banks share column names, so more specific patterns must come first:

// Capital One 360 vs Capital One credit — both have "transaction date"
// but only 360 has "account number"
if (header.includes('account number') &&
    header.includes('transaction amount')) return 'capitalone360';

// Discover uses "Trans. Date" (abbreviated), Chase uses "Transaction Date"
if (header.includes('trans. date')) return 'discover';

When header detection fails, the parser falls back to column-count heuristics and amount-sign inference. This catches the most common "generic" CSV layout used by regional banks that don't have a named parser yet.

The edge cases that surprised us

• BOM characters. Several banks (Citi, some credit unions) export CSVs with a UTF-8 BOM (\uFEFF) at the start. If you split on comma without stripping it, the first column header fails every equality check.
• Dual-column amounts. Discover and some regional banks use separate Debit and Credit columns rather than a signed Amount. The debit column is a positive number representing money out; credit is money in. Easy to misread.
• Wells Fargo's headerless format. Wells Fargo checking and savings exports have no column headers at all — just raw data rows. Detection relies on column count (5 columns) and the date format in position 0.
• BofA summary rows. Bank of America inserts a 5-row summary block at the top of the export before the real headers. The parser skips these without misidentifying them as transactions.
• Zelle memo fields with unescaped inner quotes. BofA Zelle transfers contain memo text like Payment for "dinner" without proper CSV quoting. The parser uses a repack strategy: it re-escapes the field before passing it to the CSV tokenizer.
• 8+ date formats. Banks use MM/DD/YYYY, YYYY-MM-DD, DD-Mon-YYYY, M/D/YY, and several others. The date handler detects format on the first row and applies it consistently — switching mid-file would corrupt historical imports.

OFX and QFX

The OFX/QFX format (used by Quicken and most desktop finance software) is structured XML-like markup rather than CSV. We built a dedicated parser for it because it's the export format of choice for brokerage accounts (Fidelity, Schwab) and some credit unions. OFX has proper amount signs (+ for credits, - for debits) and a standardized date format — a welcome change after CSV archaeology.

Mint exports

Mint was shut down in January 2024, leaving roughly 3 million users looking for an alternative. Mint exported a transactions.csv file (or a Google Takeout zip containing it). SiftDo detects the Mint format by fingerprinting the Original Description and Transaction Type columns, and maps Mint's positive-amount-with-type-column convention to signed amounts automatically.

The workflow

Every feature starts as a Linear issue with a detailed description: what the feature does, which files it touches, what the edge cases are, and what tests need to pass. Claude Code reads the issue, reads the relevant source files, writes the implementation and the tests, runs them, and fixes any failures — autonomously, on a schedule, while I'm doing other things.

The result is that SiftDo ships features at a pace that would be impossible for one person writing code by hand. The Sieve classification engine (6 stages, 104 tests, TypeScript package with full CI) was completed in a single session. The bank CSV parsers for 30 institutions — each requiring independent detection logic and edge-case handling — were written and tested systematically.

Where it works well

• Well-specified mechanical work — adding a new bank parser, wiring up an IPC handler, writing a Cloudflare Worker endpoint. The AI is better than hand-coding at this scale because it doesn't get tired or make copy-paste errors.
• Test generation — given a function and a spec, Claude Code writes exhaustive tests including edge cases a human would miss (empty input, BOM characters, malformed rows). This is probably the highest-leverage use.
• Refactoring with a test safety net — if tests exist and pass before the refactor, the AI can reorganize code aggressively while the test suite enforces correctness.

Where it still falls short

• Visual and UX decisions — whether a layout feels right, whether an interaction is intuitive. The AI can implement a design but can't evaluate whether it's good.
• Novel architectural decisions — the choice to be local-first, how to handle CloudKit sync conflicts, whether to use IndexedDB or SQLite. These require judgment that comes from experience, not code generation.
• Debugging production issues — when something fails in the wild in a way that's hard to reproduce, human debugging instinct is still faster.

The honest constraint

The bottleneck isn't code generation — it's specification. Every feature the AI ships well was one I had thought through carefully enough to write a clear issue description for. Vague requirements produce vague implementations. The AI is a force multiplier on clarity, not a substitute for it.