bookkeeping-mac

What It Does

Personal bookkeeping app — a native Mac replacement for QuickBooks. Tracks transactions across multiple businesses and accounts, categorizes them (auto and manual), generates P&L reports, and runs everything locally with no cloud sync, no monthly fee, and no third-party SaaS dependency.

Ported from the older Python CLI + Flask web dashboard at ~/apps/bookkeeping-web/ (formerly ~/apps/my-books/).

When To Use

• For personal and business bookkeeping across all of James’s entities (Go Kart Park, All Things Handy, James Hurst Live, etc.).
• When you want the data to live on your Mac, not in Intuit’s cloud.
• When you want native dollar-and-cents formatting with no rounding ever.

How It Works

• Original SQLite database at ~/apps/bookkeeping-web/books.db — about 7,432 transactions, 4 businesses, 9 accounts, 46 categories.
• A migration service imports that database on first launch into SwiftData.
• All amounts are stored as positive Double — TransactionType determines sign.
• Category fullName is denormalized as "Parent:Child" (colon separator).
• Duplicate detection via MD5 hash of date|amount|description.
• “Uncategorized” = category == nil AND type != .transfer.

Where It Lives

• Repo: ~/apps/bookkeeping-mac/
• Companion repo: ~/apps/bookkeeping-web/ (Python CLI + Flask web dashboard, data foundation)
• Tech: SwiftUI, SwiftData, Swift Charts, CryptoKit. Zero external dependencies — pure Apple frameworks.
• Project generated by xcodegen from project.yml.

Build And Run

cd ~/apps/bookkeeping-mac
xcodegen generate
xcodebuild -scheme MyBooks build

Or open in Xcode and hit Run.

Build Phases

1. Foundation — Xcode project, models, migration. Done.
2. Dashboard — summary cards, chart.
3. Transactions + Categorization.
4. P&L Report.
5. Accounts + Categories views.
6. CSV Import.
7. AI Assistant — natural-language query against the books.
8. Polish.

Known Gaps / Quirks

• Always show dollars AND cents — never round financial amounts. This is a hard rule throughout the codebase.
• Data is local-only by design. There is no sync to Google Drive or iCloud yet; if you want a backup, copy books.db (or the SwiftData store) by hand.
• The Flask dashboard at ~/apps/bookkeeping-web/ still works — it remains the fallback while the SwiftUI app builds out.
• Renamed from my-books-app on 2026-05-15 (paired with my-books → bookkeeping-web) for naming-SOP compliance: the old name failed the Two-Year Test (ambiguous “books”) and used the junk-drawer -app suffix. The Xcode bundle id is still com.jameshurst.MyBooks — left alone deliberately because changing it invalidates the app’s data store and any keychain entries.