#41 - SimpleFIN Bank Sync — Backend + UI - null/BillTracker

**This issue is superseded by the phased implementation plan.** The SimpleFIN-specific scope from this issue is now covered by: - **#44** — Phase 2: Data Sources & Shared Transactions (the table/API foundation) - **#47** — Phase 5: SimpleFIN Provider Sync (the actual SimpleFIN implementation) The full data input roadmap is tracked in #42. --- ## Original Description Add optional SimpleFIN Bridge support so BillTracker can sync read-only bank account and transaction data. Users connect their own SimpleFIN Bridge account, import transactions, and manually match synced transactions to bills. **No bank credentials stored.** Only the SimpleFIN Access URL, encrypted at rest. ### Backend - `server/services/simplefinService.js` — claim tokens, fetch accounts/transactions, normalize data, dedupe by provider transaction ID - `server/routes/bankRoutes.js` - `server/controllers/bankController.js` - `server/db/migrations/` — new tables ### Environment variables ```env BANK_SYNC_ENABLED=false TOKEN_ENCRYPTION_KEY=change-me SIMPLEFIN_SYNC_DAYS=90 ``` ### Database tables **bank_connections** — id, provider, encrypted_access_url, status, last_sync_at, last_error, timestamps **bank_accounts** — id, connection_id (FK), provider_account_id, name, org_name, currency, balance, available_balance, raw_data, timestamps **bank_transactions** — id, account_id (FK), provider_transaction_id, posted_date, transacted_at, amount (cents), description, payee, memo, raw_data, matched_bill_id (FK → bills), ignored, timestamps ### API endpoints ``` POST /api/bank/simplefin/connect POST /api/bank/simplefin/sync GET /api/bank/accounts GET /api/bank/transactions POST /api/bank/transactions/:id/match POST /api/bank/transactions/:id/ignore DELETE /api/bank/simplefin/disconnect ``` ### Frontend Settings → Bank Sync page: connect, sync, disconnect, account list, last sync status/error Transactions panel: list, filter, match, ignore ### Security - Never store bank usernames/passwords - Encrypt provider secrets at rest - Never send secrets to frontend or logs ### Acceptance Criteria - [ ] User can connect SimpleFIN setup token from UI - [ ] Backend stores only encrypted provider access data - [ ] Backend syncs accounts and transactions - [ ] Transactions are deduped correctly - [ ] Frontend lists accounts and transactions - [ ] User can manually match transaction to bill - [ ] User can ignore a transaction - [ ] User can disconnect SimpleFIN - [ ] App works normally when bank sync is disabled - [ ] No SimpleFIN secrets exposed to frontend or logs - [ ] Docker/example env docs updated

null commented

2026-05-16 18:00:57 -05:00

Owner

This issue is superseded by the phased implementation plan.

The SimpleFIN-specific scope from this issue is now covered by:

#44 — Phase 2: Data Sources & Shared Transactions (the table/API foundation)
#47 — Phase 5: SimpleFIN Provider Sync (the actual SimpleFIN implementation)

The full data input roadmap is tracked in #42.

Original Description

Add optional SimpleFIN Bridge support so BillTracker can sync read-only bank account and transaction data. Users connect their own SimpleFIN Bridge account, import transactions, and manually match synced transactions to bills.

No bank credentials stored. Only the SimpleFIN Access URL, encrypted at rest.

Backend

server/services/simplefinService.js — claim tokens, fetch accounts/transactions, normalize data, dedupe by provider transaction ID
server/routes/bankRoutes.js
server/controllers/bankController.js
server/db/migrations/ — new tables

Environment variables

BANK_SYNC_ENABLED=false
TOKEN_ENCRYPTION_KEY=change-me
SIMPLEFIN_SYNC_DAYS=90

Database tables

bank_connections — id, provider, encrypted_access_url, status, last_sync_at, last_error, timestamps
bank_accounts — id, connection_id (FK), provider_account_id, name, org_name, currency, balance, available_balance, raw_data, timestamps
bank_transactions — id, account_id (FK), provider_transaction_id, posted_date, transacted_at, amount (cents), description, payee, memo, raw_data, matched_bill_id (FK → bills), ignored, timestamps

API endpoints

POST   /api/bank/simplefin/connect
POST   /api/bank/simplefin/sync
GET    /api/bank/accounts
GET    /api/bank/transactions
POST   /api/bank/transactions/:id/match
POST   /api/bank/transactions/:id/ignore
DELETE /api/bank/simplefin/disconnect