Documentation

Quick Start

LockMargin is a portable desktop application. No installer, no cloud account, no subscription.

1. Download the latest release (LockMargin Early Access) from the download page.
2. Extract the .zip archive to any folder on your machine.
3. Run LockMargin.exe. The app launches immediately — no setup wizard, no registration.
4. Press Ctrl+K (Windows) or Cmd+K (macOS) to open the Command Palette and start creating clients, projects, or invoices.
5. Optionally enable AES-256-GCM encryption via Settings → Security → Initialize Encryption.

Tech Stack

LockMargin is built with modern, battle-tested technologies:

Clients

Manage your clients with full CRUD operations, encrypted sensitive fields, and soft delete.

Encrypted Fields

When encryption is enabled, the following client fields are encrypted with AES-256-GCM before storage:

• bank_account_encrypted — Bank account details
• tax_id_encrypted — Tax identification number
• contact_info_encrypted — Contact information

Commands

All client actions are available through the Command Palette (Ctrl+K):

• create_client — Add a new client
• get_clients / get_clients_with_stats — List clients with optional financial stats
• get_client_financial_dossier — View revenue, expense, and invoice totals per client
• update_client / delete_client — Edit or soft-delete a client
• import_clients_csv — Bulk-import clients from CSV
• restore_client / permanently_delete_client — Manage deleted records

Projects

Organize work into projects with stages, budget tracking, and health scoring.

Project Stages

Each project can have multiple stages with different billing types:

• Fixed — Fixed-price stage
• Retainer — Recurring monthly fee
• Hourly — Billed by time entry

Project Health

LockMargin calculates a project health score (health_score) based on budget vs. actual spend, timeline, and stage completion. Access via calculate_project_health or the dashboard.

Commands

• create_project / delete_project / update_project_status
• get_projects_with_stats — Projects with budget, health, and stage progress
• create_stage / update_stage / delete_stage

Time Tracking

Track time with categories, session timers, and automatic billing status.

Active Timer

Start and stop a timer from the dashboard. The active session persists even if the app is closed.

Commands

• start_timer / stop_timer / get_active_timer — Timer session management
• create_time_entry / get_time_entries / update_time_entry / delete_time_entry
• get_unbilled_time_entries — Find time not yet invoiced
• create_time_entry_category / get_time_entry_categories

Expenses

Track business expenses with categories and receipt file attachments.

• create_expense / get_expenses / update_expense / delete_expense
• Combined with the recurring engine for auto-recurring expenses

Invoices

Full invoicing with payment tracking, PDF generation, and email delivery.

Invoice Features

• Create invoices manually or from time entries (create_invoice_from_time)
• Partial payments via create_invoice_payment (supports Stripe, credit, manual)
• PDF generation with generate_invoice_pdf and save_pdf_file
• Email invoices via SMTP with send_invoice_email and email log
• Reusable invoice templates (create_invoice_template)
• Discount support on invoices and line items

Invoice Statuses

Invoices support a status workflow: draft, sent, paid, overdue, cancelled, refunded.

Quotes & Proposals

Quotes

Create estimates and quotes with tax and discount support. Quotes can be converted to invoices on acceptance.

• create_quote / get_quotes / get_quote / delete_quote
• update_quote_status — Track through draft, sent, accepted, rejected
• convert_quote_to_invoice — One-click conversion on acceptance

Proposals

Scope documents for larger engagements, with line items and status tracking.

• create_proposal / get_proposals / get_proposal
• update_proposal_status

Recurring Engine

LockMargin's most distinctive feature: a reactive recurring engine that does not use cron jobs. Instead, recurring items are generated on demand when they become due — triggered by app launch or manual check.

How It Works

• Define recurring schedules for both invoices and expenses
• On app launch or explicit trigger, find_due_recurring_items checks which items are past due
• mark_recurring_items_generated records the generation to prevent duplicates
• Works fully offline — no server connection needed

Commands

• create_recurring_invoice / get_recurring_invoices / generate_recurring_invoices
• create_recurring_item_cmd / list_recurring_items_cmd — Unified engine for both invoices and expenses
• generate_due_recurring / toggle_recurring — Expense-side recurring management

Tax Rates

Define tax rates per country and apply them to invoices and quotes.

• create_tax_rate / get_tax_rates / get_tax_rate
• update_tax_rate / delete_tax_rate
• get_default_tax_rate — Set and retrieve default tax rate for new invoices

Client Credits

A credit-based payment system for invoicing. Clients can prepay credits, which are applied to invoices as payments. Supports multiple credit types per client with balance tracking.

• Model: ClientCredit — credit_type, amount_cents, balance_cents, source, reference_type
• Used for retainer billing, prepaid blocks, and deposit management

Dashboard & Metrics

The dashboard (Dashboard v4) provides real-time financial and operational metrics computed locally from your data.

Core Metrics

Dashboard Components

• Attention Items: Alerts for overdue invoices, low runway, project health warnings
• Active Projects: Budget progress and health score per project
• Cash Flow Chart: Date-wise inflow, outflow, and balance visualization

Runway & RHR

Runway Calculation

LockMargin's signature metric: get_runway_with_personal. Unlike SaaS tools that show only your bank balance, LockMargin calculates how many months you can operate based on:

• Current balance (business accounts)
• Average monthly burn rate (business + personal expenses)
• Pending invoices and projected revenue

Revenue-to-Hour Ratio (RHR)

RHR (rhr_cents) measures your revenue per hour worked. Track this over time to understand if your hourly rate is keeping pace with expenses.

Encryption Guide

LockMargin uses AES-256-GCM encryption with system keychain storage. Your encryption key is never stored in the database or in files.

How Encryption Works

1. Key Derivation: A master key is derived using PBKDF2-HMAC-SHA256 with 100,000 iterations and a random salt.
2. Key Storage: The master key is stored in your system keychain (Windows Credential Manager via the keyring crate).
3. Salt Storage: The salt is stored in the encryption_metadata table — separate from the key itself.
4. Field Encryption: Each encrypted field uses a unique nonce. Encrypted fields include bank accounts, tax IDs, contact info, payment method details, and OAuth tokens.

Setup

Go to Settings → Security and click Initialize Encryption. The app will generate and store your key. Use check_encryption_status to verify.

Tested

6 unit tests passing: roundtrip encryption/decryption, unique outputs per encryption, wrong key rejection, invalid base64 handling, deterministic key derivation, and different salt isolation.

Soft Delete & Audit Log

Soft Delete

All major entities support soft delete with a deleted_at timestamp:

• Clients (clients.deleted_at)
• Projects (projects.deleted_at)
• Time entries (time_entries.deleted_at)
• Expenses (expenses.deleted_at)

Use get_deleted_clients and restore_client (and equivalents for other entities) to recover deleted records. permanently_delete_client removes data entirely.

Audit Log

LockMargin maintains an immutable audit trail (audit_log table) recording every action:

• Action types: CREATE, UPDATE, DELETE, EXPORT
• Tracked data: entity type, entity id, changes_json (diff snapshot), idempotency key

Export & Backup

PDF Export

• export_projects_pdf / export_invoices_pdf / export_clients_pdf
• generate_invoice_pdf / save_pdf_file — Generate and save invoice PDFs

CSV Export

• export_projects_csv / export_clients_csv / export_invoices_csv

Backup & Restore

• create_backup — Create a full backup of your SQLite database
• list_backups — List available backups
• restore_backup — Restore from a backup file
• delete_backup — Delete old backup files

CSV Import

Bulk-import clients from a CSV file using import_clients_csv. The app validates and processes the data locally — nothing is sent to a server.

CSV exports include all fields (excluding encrypted data which exports as ciphertext). Use CSV export for reporting, accounting handoff, or migration planning.

Command Palette (Ctrl+K / Cmd+K)

The Command Palette is the primary navigation and action interface in LockMargin. Press Ctrl+K (Windows/Linux) or Cmd+K (macOS) to open it.

21 actions organized into 4 categories:

• Create — New client, project, invoice, expense, quote, proposal
• Navigation — Go to Dashboard, Clients, Projects, Invoices, Settings
• Settings — Encryption, export, backup, preferences
• Help — Documentation, about, shortcuts reference

Built with cmdk 1.1.1 for fast, keyboard-first interaction.

Commands Reference

Complete list of backend commands available through the Tauri IPC bridge. Access any command via Ctrl+K or the menu.

Database Overview

LockMargin uses a local SQLite database with 33 tables managed by 47 migration files. The database is stored entirely on your machine under the app data directory.

Development Status

Current Release

Early Access — Release preparation phase. Latest commit: daf20b4 — Sprint 8: Stealth/Privacy Mode.

Completed Sprints

• Sprint 1: Core CRUD (clients, projects, invoices)
• Sprint 2: Time Tracking + Expenses
• Sprint 3: Invoicing + Recurring + Quotes
• Sprint 4: Dashboard + Export + Search
• Sprint 5: Polish + Smart Features
• Sprint 6: Credit-based payment system
• Sprint 7: Real AES-256-GCM encryption
• Sprint 8: Stealth/Privacy Mode

Upcoming Sprints

• Sprint 9: Data portability (JSON/YAML export/import)
• Sprint 10: Multi-currency support
• Sprint 11: Reporting engine (P&L, tax reports)