wanderbooks/plan/gui.md

ledger-gui — design

Phase 4 of the roadmap (plan/roadmap.md). A desktop app (egui/eframe) for the people who own the books and the accountant who checks them. Same audience as QuickBooks, none of its visual language.

What it is for

It answers the questions an owner actually has, then shows the evidence:

• How much money do we have, and how long does it last? Cash today, the trend, burn, runway, what's coming due.
• Are we making money? Revenue, spending, and profit by month; what changed and why.
• Where does the money go? Spending by category and vendor, over time.
• Who owes whom? Payables, receivables, cards, money owed to members.
• Is anything wrong or missing? Entries without receipts, drafts never posted, unreconciled accounts, uncategorized tax lines, 1099 vendors with no W-9, past periods left open, a journal that fails verification.
• Can I trust this number? Every number drills down to the lines that make it, each line to its entry, each entry to its rendered receipt and its complete journal history (who did what, when, hash-chained).

An accountant gets the same data at full depth: statements with interval columns and comparisons, the general ledger, trial balance, the raw journal with its verification status.

Principles

1. Answer first. Every screen leads with the answer in words and one big number, then the chart, then the table, then the raw data.
2. Everything drills down. Any amount is a link. Navigation is a history stack (back/forward, like a browser) with a breadcrumb.
3. All the data, nothing hidden. Withdrawn attachments, reversals, drafts, every journal event: visible, marked for what they are.
4. Read-only by construction. The GUI has no write path: it reads the hash-chained journal and the blob store and builds its own in-memory view (ledger_store::Snapshot). Changes happen through the agent (MCP). Where the GUI finds something to fix, it offers a ready-to-paste prompt for the agent ("Attach the receipt for entry 12 — Anthropic, $7.40").
5. Live. It follows the journal: a change made by the agent appears within a second, highlighted as new.
6. Numbers are typography. Tabular figures everywhere (Inter with tnum frozen in), right-aligned, parentheses for negatives in statements, a minus sign elsewhere, never a float.
7. No accounting logic in the GUI. Statements, balances, and series come from ledger-core (new reports land there, where MCP can use them too). The GUI arranges and draws.

Screens

• Overview — KPI tiles with sparkline and change vs. the prior period (cash, runway, revenue, spending, net income, owed by / owed to); cash over time; income vs. spending by month; spending by category; needs-attention list; recent activity from the journal.
• Cash — every cash and card account with balance and trend; inflows and outflows by month; burn and runway; known upcoming outflows (recurring entries, bills due, schedules).
• Profit — P&L by month as chart and table, spending breakdown with month-over-month change, by class.
• Transactions — the register of every entry: search, filters (account, vendor, class, date, status, receipt yes/no, amount), and a detail pane with lines, the rendered receipt (PDF pages, images), vendor, reversal links, and the entry's journal history.
• Reports — P&L, balance sheet, cash flow, trial balance, general ledger, members' equity, tax summary, A/R and A/P aging, 1099 worksheet. Date presets, interval columns (total / month / quarter / year), comparison to the prior period or year. Every amount drills down.
• Accounts — the chart with balances and tax categories; an account opens its register with a running balance and a balance chart.
• Documents — every receipt and company document, rendered, with its category, entry link, and withdrawal status.
• Company — profile, members and capital, periods, fixed assets, amortization schedules, recurring entries, vendors and 1099 status.
• Journal — the raw event log, filterable, each event expandable to its JSON, with the hash-chain verification result.

Global: command palette (Ctrl+K) to jump to any account, entry, vendor, document, or report; back/forward (Alt+←/→); light and dark themes.

Architecture

• ledger-store::Snapshot: read-only. Verifies the journal chain, replays it into a Ledger, projects it into an in-memory SQLite with the same code the writer uses, reads blobs. refresh() applies only new journal lines (or reloads if the file was rewritten).
• ledger-config (moved out of ledger-mcp): wanderbooks.toml.
• ledger-gui:
  • data — a loader thread follows the journal (notify-driven, polling as the fallback) and sends new snapshots.
  • model — view models built from a snapshot (pure, unit-tested).
  • ui/* — one module per screen; widgets (money, tiles, sparkline, tables, charts); theme; receipts (PDF via hayro, images via image; textures cached by blob hash).
  • Tests: model unit tests, egui_kittest screenshots of every screen against a fixture book.
• Web build later: the model is plain data, so a server can ship it.

Status (2026-10-28)

Built 2026-10-12 (the first version): every screen above, the palette, history, themes, live updates (a store write reaches the view model in ~30 ms), receipt rendering for PDFs and images, a deterministic demo company (wanderbooks gui --demo; also the screenshot fixture), and a screenshot test (SHOT_DIR=… cargo test -p ledger-gui --test screens, optionally SHOT_BOOKS, SHOT_ONLY, SHOT_DARK).

Built since, by the "Served" plan (plan/served.md):

• The data root is the only source (D-44): wanderbooks gui <book> opens a book of the data root, read-only, its settings from the journal and its vault from its own vault/ and keys/; --data-dir and --books-toml are gone. The viewer holds the books open (a lease of kind app) and still opens with the server stopped.
• The Books menu (P2 slice 8, D-19): Back up now, Restore…, New books…, Connect Claude Code, Connect Codex, Close the books, each handed to the server through the same functions the command line uses; the Export menu (the CPA package, the 1099 worksheet, Save a copy, Save the W-9), each a new file in Downloads. The viewer writes nothing of the books (tests/read_only.rs, tests/owner_menu.rs).
• The format-upgrade dialog (D-39): asked at every open of waiting books, a standing notice, the owner passphrase typed in the viewer.
• Color schemes (D-19's menu): the viewer's own family and twenty editor families, 80 schemes, each at WCAG AA contrast, worn live on hover (tests/schemes.rs, docs/color-schemes.md).
• Needs attention is the engine's (U0b, D-53): one function in ledger-package::attention over PackageBooks, read by the viewer and by books.start; the viewer only maps each item's target to a route, and the_viewer_and_books_start_see_the_same_attention proves the two lists equal. Principle 4's "ready-to-paste prompt" now comes from that engine.
• Pages added: Invoices & Bills (Money in, Money out, a document's page with its timeline, overview tiles; P4b S2) and Save invoice PDF (S3); Projects and a project's snapshot (D-43); parties with roles, W-9 and the TIN clipboard copy (D-29); fixed assets with the tax-basis figures (P3); reconciliation; the journal page describing every event in plain words.
• Compatibility tests: tests/old_books.rs (books an earlier version wrote open to their figures), tests/newer_journal.rs (a newer journal says "update wanderbooks", never half-read), tests/view_model.rs (every figure shown is the engine's).

Landed 2026-10-29: the invoice page shows sends (S5), a discount-deadline column and the tie-out badge (S6), write-offs on the timeline (S7), documents grouped by category and subject (P6). S4.5 adds the number, terms, bill-to and the issued copy to Save.

Landed 2026-10-29 (P11b): the agent dock along the bottom of the window (Claude Code or Codex in the book's books home, over a PTY with alacritty_terminal; collapsible and resizable; the choice remembered; Linux checked, macOS by CI, Windows not offered until its ConPTY checks are recorded; dock.rs, tests/dock.rs) and the first-run page (no books yet: the private folder, the owner passphrase, the first books, an agent, then the books open; welcome.rs, tests/welcome.rs), which is what lets an installed app onboard with no terminal. Both go through the Owner; the viewer still writes nothing of the books.

Next, in the plan's order: S4.5's page changes; P4's draft states in Needs attention; P11a (the installed app: the viewer is its face, with "Check for updates" in the menu; P11b, the dock and the first run, is landed, above). Not planned: a web build, which belongs to the hosted service (plan/served.md section 11, a browser viewer); the remote viewer replica (D-51: a backup clone opened read-only serves instead). Still open from the first version's list: a cash forecast with a confidence band, receipt zoom and multi-page navigation, keyboard navigation in lists, virtualized lists for very large books.