Local-first finance
Clarity
A desktop finance workspace built around CSV statements and a local Markdown vault. Clarity carries forward a lesson from MyBursar: the way people are willing to share data should shape the product.
- Next.js
- React
- JavaScript
- Node.js
- Electron
- Markdown
- Recharts
A source record with an account, date, amount, and type. Purchases, refunds, income, and transfers have distinct reporting behavior.
Local vault · Stale-write rejection · Recoverable backups · Optional external AI
01 / Context
What it solves
While building MyBursar, I heard that people were uncomfortable sharing their bank passwords. Canadian bank connections through Plaid were also unreliable in my experience. People leaned more on CSV statements, but working with those files on a phone was awkward.
Clarity takes that workflow seriously. It gives statement import and review a desktop workspace, without requiring a bank connection or a Clarity account. The aim is to make a deliberate monthly review easier, rather than promise an automatically synchronized view of every account.
These observations informed the product; they are not a claim that every bank connection behaves the same way. Separate Canadian consumer research also points to the importance of control over financial data. The FCAC’s 2022 survey, published in 2023, found that revoking consent and security protections mattered to respondents considering open banking. That is useful context, not validation of Clarity itself.
FCAC: Consumer protection in open banking (2023 report; 2022 survey)
02 / Product shape
From statements to a deliberate review
The workflow starts with the records a person chooses to bring in. Every later summary depends on that coverage.
- 01Export a CSV statement from the bank
- 02Map columns and review transactions before import
- 03Resolve categories, duplicates, and transaction types
- 04Review spending and adjust category budgets
- 05Record balance snapshots and preserve a backup
03 / Requirements
What the system needs to handle
- Make CSV mapping reusable across repeated imports.
- Keep transfers out of spending and deduct refunds from the relevant spending totals.
- Preserve source transactions when allocating a purchase across categories.
- Keep the core usable offline without a hosted account or database.
- Reject stale edits and provide recoverable copies of local records.
- Make incomplete statement coverage visible instead of implying that every total is complete.
04 / Architecture
Engineering decisions
Readable files as the storage boundary
Clarity stores structured tables in Markdown files that can also be opened in Obsidian or a text editor. The vault is a folder the user can keep and move independently of the application.
Alternative considered. SQLite would provide stronger transactional and query primitives. Markdown makes direct inspection and portability simpler for this product.
Trade-off. The application takes responsibility for parsing, validation, locking, and recovery. Per-file replacement is not a transaction across the entire vault.
A local service inside the desktop app
Electron launches the local Node/Next.js service, while React handles the review workflow. This reuses the web application in a desktop package and keeps filesystem work behind a service boundary.
Trade-off. Electron adds runtime size and packaging work. Desktop releases also need platform-specific signing and testing.
Separate the ledger from category allocations
Splitting a purchase changes how spending is attributed, not how much money moved. Allocations feed category reports while the original transaction remains the ledger record. Refunds can be split using the same distinction.
Trade-off. Edits must validate allocation totals and protect existing splits during bulk updates.
Treat AI as optional categorization
The core workflow does not depend on AI. When configured, categorization uses selected merchant descriptions, known categories, and reviewed examples. Responses are constrained to the existing category model.
Trade-off. Selected text leaves the device for OpenAI. The privacy boundary must be explained even though amounts and balances are not included.
05 / Trust
Reliability and privacy
Local storage removes a hosted-data dependency. It still needs defenses against accidental overwrites, broken imports, and misunderstood totals.
Reject stale writes
Revision hashes let the service detect an edit based on an older vault state and reject it rather than silently overwrite newer work. Saves are serialized, and a vault lock limits competing writers.
Keep a path back
Temporary-file writes and renames protect individual file replacement. Retained backups and ZIP export/restore support recovery, but do not make a multi-file save fully atomic.
Review imports before committing them
Column mapping, transaction review, duplicate fingerprints, and statement history make repeated imports easier to inspect. Coverage warnings keep missing statements visible.
State the privacy limits
The vault is plaintext, not encrypted by Clarity. Device security and backup choices matter. A cloud-synced vault also lives with that provider; optional AI processing and GitHub update checks use the network.
06 / Reasoning
Trade-offs
- CSV imports avoid dependence on a live bank connection, but require recurring effort from the user.
- Readable Markdown is portable, but sacrifices database-level transactions and efficient ad hoc queries.
- Manually recorded balance snapshots are explicit, but are not automatic bank reconciliation.
- One currency per vault keeps reporting simple; changing the currency setting does not convert amounts.
- A desktop workspace makes statement review less cramped, while native mobile capture remains outside the current focus.
07 / Status
Current status
The current implementation includes statement import and history, category budgets, transaction splits, saved filters, bulk editing, balance snapshots, and backup/export tools. These are implemented workflows, not a claim of broad production adoption.
Preview installers are published through GitHub. The rolling latest release receives stable download filenames after a successful release build. Installers are unsigned; Apple silicon has been launch-tested, while native-device validation for Intel Mac and Windows remains pending. Consult release notes for the features included in a particular build.
08 / Reflection
What MyBursar changed about my approach
- A data connection is only useful if people are comfortable using it. Concern about bank passwords became a product constraint, not just onboarding copy.
- When people fall back to CSV, the import workflow deserves attention. Moving that work to a desktop gives mapping, review, and correction more room.
- Local storage changes the reliability problem. There is less hosted infrastructure to operate, but file ownership, stale edits, and recovery become application responsibilities.