>
Download

Documentation

Learn everything you'll ever need to get the most out of BillKit

>
Data Management

BillKit stores all your data locally on your Mac. This guide explains how data is organised, where it's stored, how to maintain it, and how to completely reset the application if needed.

How BillKit Stores Data

Core Data Database

Core Data is stored on your system at:

~/Library/Containers/CodelDev.BillKit/Data/Library/Application Support/BillKit/

What's stored:

  • Businesses, categories, vendors, expenses
  • Media file metadata (file paths, processing status)
  • Audit logs
  • User settings and preferences

Format: SQLite database (Core Data)

Size: Varies based on data volume:

  • Small dataset (100 expenses): ~1-5 MB
  • Medium dataset (1,000 expenses): ~10-50 MB
  • Large dataset (10,000 expenses): ~100-500 MB

Access: Managed by BillKit automatically. You don't need to interact with database files directly.

Invoice Files

Invoices can be located on your system at:

~/Library/Containers/CodelDev.BillKit/Data/Documents/businesses/[business-uuid]/invoices/

Structure:

Documents/
└── businesses/
    ├── 12345678-1234-1234-1234-123456789abc/  (Business UUID)
    │   └── invoices/
    │       ├── file1.pdf
    │       ├── file2.png
    │       └── file3.jpg
    └── 87654321-4321-4321-4321-cba987654321/  (Another Business UUID)
        └── invoices/
            └── file4.pdf

What's stored:

  • Original invoice files uploaded or processed
  • PDFs, PNGs, JPEGs, converted HEIC files

Notes

  • Naming: Files keep their original names (e.g. "Invoice_Amazon_2025.pdf")
  • Size: Depends on invoice count and file sizes - can range from a few MB to several GB
  • Access: Download individual files via expense detail views, or bulk export via Export Data screen (Pro tier)

Settings and Preferences

Settings are stored on your machine at:

~/Library/Containers/CodelDev.BillKit/Data/Library/Preferences/

What's stored:

  • Appearance mode, currency, date/time format
  • Fiscal year start, log retention period
  • AI provider selection
  • Window size and position
  • Filter persistence (last used filters per view)

Notes

  • Format: macOS UserDefaults (plist files)
  • Size: Negligible (<1 MB)

API Keys

Your API Keys are stored in the macOS Keychain using system-level secure storage

What's stored:

  • Claude API key (if configured)
  • OpenAI API key (if configured)

Notes

  • Security: Encrypted by macOS, not accessible without user authorisation

Database Maintenance

Automatic Maintenance

BillKit performs automatic maintenance on app startup:

Database corruption check:

  • Validates Core Data store integrity
  • Attempts automatic recovery if corruption detected
  • Shows error dialog if recovery fails

Orphaned file cleanup:

  • Finds invoice files not linked to any expense
  • Logs orphaned files (doesn't auto-delete - user must manually clean)

Audit log pruning:

  • Deletes logs older than retention period (Settings → Log Retention)
  • Runs silently in background

No user action required - these maintenance tasks happen automatically.

Manual Database Optimisation

Currently, BillKit does not offer manual database compression or optimisation tools. The Core Data framework handles this automatically.

If database grows very large:

  1. Export data to CSV/JSON
  2. Delete old expenses (if no longer needed)
  3. Restart BillKit (triggers cleanup)

Disk Space Management

Checking BillKit Storage Usage

To see how much space BillKit uses:

  1. Open Finder
  2. Navigate to ~/Library/Containers/
  3. Find the BillKit container folder (search for "BillKit")
  4. Right-click and select "Get Info"
  5. View "Size" field

Breakdown

  • Application Support/BillKit/ - Database files (~1-500 MB)
  • Documents/businesses/ - Invoice files (varies widely)
  • Preferences/ - Settings (<1 MB)

Reducing Storage Usage

Option 1: Delete old businesses

  1. Click "Businesses" in the sidebar
  2. Right-click the unused business
  3. Choose "Delete Business"
  4. All expenses, categories, vendors, and invoice files for that business are deleted

Option 2: Delete old expenses

  1. Filter expenses by date range (e.g. over 7 years old)
  2. Select expenses to delete
  3. Bulk delete
  4. Invoice files orphaned (remain on disk until manual cleanup)

Option 3: Shorten log retention

  1. Settings → General → Log Retention Period
  2. Set to 30 or 90 days
  3. Restart BillKit (old logs deleted)

Backing Up Your Data

Automatic Backups (Time Machine)

  • Automatically backs up entire BillKit container folder
  • Includes database, invoice files, settings, API keys
  • Restore from Time Machine if data lost

To enable Time Machine:

  1. System Preferences → Time Machine
  2. Enable automatic backups
  3. Choose backup disk

Manual Backups

Complete backup (includes invoice files):

  1. Open Finder
  2. Navigate to ~/Library/Containers
  3. Find BillKit container folder (CodelDev.BillKit)
  4. Right-click and select "Compress"
  5. Creates ZIP archive
  6. Copy ZIP to external drive, cloud storage, or network location

In-App Backup Creation (Recommended)

BillKit includes a built-in backup feature that creates a single ZIP file containing all your data:

To create a backup:

  1. Click "Create Backup" in the sidebar (under Data Management section)
  2. Review what will be included:
    • All businesses, expenses, vendors, and categories
    • All invoice files and attachments
    • Application settings and preferences
    • API keys excluded for security - must be re-entered after restore
  3. Click the "Create Backup" button
  4. Choose save location (external drive, cloud storage, etc.)
  5. BillKit creates a ZIP file named billKit-backup-YYYY-MM-DD-HH-MM-SS.zip

Backup contents

  • Database with all expense data
  • Business invoice files (organized by business)
  • Application settings (appearance, currency, date formats, etc.)
  • Manifest file with backup metadata (version, date, file count, size)

Backup size: Varies based on data volume:

  • Small dataset (100 expenses, few invoice files): 1-10 MB
  • Medium dataset (1,000 expenses, many invoices): 50-200 MB
  • Large dataset (10,000+ expenses, many large PDFs): 500+ MB

Advantages over manual backup:

  • Single file (easy to store and transfer)
  • Includes metadata for verification
  • Validated structure (guaranteed to restore correctly)
  • One-click creation
  • No need to navigate Finder folders

Restoring from Backup

Restoring from Time Machine

To restore BillKit data:

  1. Quit BillKit
  2. Open Time Machine
  3. Navigate to backup date
  4. Browse to ~/Library/Containers/CodelDev.BillKit
  5. Click "Restore"
  6. Overwrite current container folder
  7. Restart BillKit

Result

BillKit reverts to backed-up state (all expenses, businesses, settings restored).

Restoring from Manual Backup

To restore from ZIP backup:

  1. Quit BillKit
  2. Open Finder → ~/Library/Containers/
  3. Delete current BillKit container folder (CodelDev.BillKit) (or rename to CodelDev.BillKit.Old)
  4. Extract backup ZIP into Containers folder
  5. Restart BillKit

Result

BillKit loads data from backup.

Restoring from In-App Backup (Recommended)

To restore from BillKit backup ZIP:

  1. Click "Restore Backup" in the sidebar (under Data Management section)
  2. Either:
    • Drag and drop the backup ZIP file onto the drop zone, OR
    • Click the drop zone to browse and select the backup file
  3. Review the selected backup:
    • Filename and size displayed
    • Warning: "Restoring will replace ALL current data. This cannot be undone."
  4. If you're sure, click "Restore Backup" button
  5. BillKit shows restore progress:
    • Validating backup file
    • Extracting backup
    • Backing up current data (for rollback if needed)
    • Restoring database
    • Restoring invoice files
    • Restoring settings
    • Reloading data
  6. BillKit automatically restarts after successful restore
  7. After restart, all data from backup is loaded

Restore duration

  • Small backup: 10-20 seconds
  • Medium backup: 30-60 seconds
  • Large backup: 1-3 minutes

Important notes

  • API keys not included: You must re-enter your Claude or OpenAI API key after restore (Settings → AI)
  • Current data replaced: Everything is replaced with backup data (no merging)
  • Automatic rollback: If restore fails, BillKit automatically rolls back to your previous data (no data loss)
  • Version compatibility: BillKit checks backup version and rejects incompatible backups with clear error message

After restore

  • All expenses, businesses, vendors, categories from backup are loaded
  • Invoice files restored to correct locations
  • Settings restored (appearance, currency, fiscal year, etc.)
  • Subscription status remains active (if Pro tier)
  • Must reconfigure AI API key

If restore fails

  • BillKit automatically rolls back to your data before restore attempt
  • Error message shows specific problem (corrupted file, incompatible version, etc.)
  • Your current data is never lost during restore attempts
  • Try different backup file or restore from Time Machine

Recommendation

Use in-app restore for BillKit backup ZIPs. It's safer and easier than manual container folder restoration.

Resetting BillKit

When to Reset

Reset BillKit if you want to:

  • Start completely fresh (all data deleted)
  • Sell your Mac (clear all financial data)
  • Fix severe corruption (last resort)
  • Test BillKit without affecting production data

Warning

Reset is permanent and irreversible. All data is deleted. Back up first if you might need it later.

What Reset Deletes

Resetting the app deletes:

  • All businesses
  • All categories (including system defaults)
  • All vendors (including system defaults)
  • All expenses
  • All invoice files (from disk)
  • All audit logs
  • All user settings (appearance, fiscal year, etc.)
  • API keys (from Keychain)
  • Subscription status reset to Basic tier (if local-only tracking)
  • Restore points (temporary rollback backups are deleted)

What is not deleted:

  • BillKit application itself (stays installed)
  • Subscription billing continues (must cancel separately via payment provider)

Result

BillKit returns to "first launch" state as if freshly installed.

How to Reset

To reset all app data:

  1. Click "Reset App Data" in the sidebar (under System section)
  2. A warning screen appears showing:
    • Count of businesses, categories, vendors, expenses to be deleted
    • List of what will be removed
    • "This action cannot be undone" warning
  3. Click "Reset App Data" button
  4. BillKit deletes everything
  5. App returns to businesses list view prompting you to create a business.

Duration

Typically, resetting the app takes a few seconds for small datasets and up to 1-2 minutes for large datasets (10,000+ expenses, many invoice files).

Data Privacy and Security

Local-Only Storage

BillKit does not use cloud sync

  • All data stays on your Mac
  • No cloud servers store your financial data
  • No syncing between devices
  • No online accounts or logins

Advantages

  • Complete privacy
  • No data breaches (no cloud target)
  • Works offline
  • Fast (no network latency)

Disadvantages

  • No automatic sync to other devices
  • Backup is your responsibility
  • Data lost if Mac fails without backup

Encryption

  • Database is not encrypted at rest (standard SQLite files on disk)
  • Invoice files are not encrypted at rest (standard PDF/image files on disk)
  • API keys are encrypted in macOS Keychain (system-level encryption)

If you need encryption

  • Enable FileVault (full-disk encryption) on macOS
  • Store backups on encrypted drives

Deleting Data Securely

Before selling/recycling your Mac:

  1. Export all BillKit data (for your records)
  2. Reset BillKit app data
  3. Delete BillKit application
  4. Empty Trash
  5. Use macOS Recovery → Erase Mac (secure erase)
Activity Tracking
Troubleshooting Guide
>