← back to the LedgerLamp brief
LedgerLamp · System diagrams

The facts,
not the document.

A privacy-first command center for bills, cards, and financial notices — built on deterministic rules, with no bank links and no AI in the loop. Four diagrams on how it keeps your facts and forgets your documents — and how it's built to add AI safely later. One visual language throughout: amber is the live path, dashed amber is planned.

01 / 04 — THE SIGNATURE FLOW

Many doors,
one human gate.

Live intake is three doors — paste an email, snap a bill on your phone, or bulk-paste a batch — plus more planned ones. They funnel into one normalized intake_item, get their fields pulled by a deterministic pattern-matcher, and stop at a single review gate. Nothing auto-commits: you approve every field before it reaches the ledger, or reject it to the archive.

NARROW WAIST · MANY DOORS → ONE QUEUE → ONE GATE → LEDGER NOTHING AUTO-COMMITS — YOU APPROVE EVERY WRITE PASTE EMAIL /intake/paste.php subject · sender · body SNAP A BILL /intake/snap.php photo never leaves device PLANNED INTAKE EML upload · IMAP poll webhook Snap: photo is rendered in-browser, never POSTed to the server. ONE QUEUE intake_item normalized · pending raw_body held EXTRACT · DETERMINISTIC Candidate fields regex pattern-match amount · due · min · biller HUMAN REVIEW You approve every field, before anything is written ✓ approve ✕ reject approve LEDGER Cards · Bills + snapshot on write + audit row reject REJECTED · ARCHIVED live path planned intake rejected → archived
02 / 04 — PRIVACY BY ARCHITECTURE

Keep the facts.
Forget the document.

The raw pasted text is held only until you approve the structured fields — then raw_body is nulled out. LedgerLamp keeps the amount, the due date, the biller; it does not keep the document. Photos never reach the server, full card numbers are never stored, and you choose how long anything lives. With one exception, named here rather than buried: the extraction audit trail keeps the short snippet the model cited for each field — the evidence that makes a proposal checkable after the fact — and those rows are not yet covered by the retention setting. Found in our own audit, ticketed, and disclosed while it is still true.

KEEPS THE FACTS, NOT THE DOCUMENT RAW_BODY LIFECYCLE ON CAPTURE raw_body · full text facts · amount · due · biller APPROVE you confirm ✕ nulled on approve AFTER APPROVAL raw_body → NULL · document gone facts · kept THREE PRIVACY INVARIANTS PHONE SNAP rendered in-browser as base64 read on-device · typed by you ✓ never uploaded · discarded on save CARD NUMBERS last-four only CHAR(4) · schema-enforced ✓ full number never stored YOU CHOOSE · RETENTION raw docs: none – 12 months structured: 3 – 12 months ✓ your household, your rules kept · safe discarded · gone
03 / 04 — THE PAYOFF

From cryptic bill
to ranked to-do.

Account fields run a fixed gauntlet of rules — no external calls, no model — and come out as a severity-sorted to-do list, each item expandable into plain-English "why this matters" and a recommended action. The engine's smartest move: it separates due date from statement-close date, the distinction most people conflate.

ACCOUNT balance · limit due date close date APR · promo APR autopay state min payment last-four DETERMINISTIC RULE GAUNTLET verified facts only · 0 external calls due-date triage → overdue / ≤7d urgent statement close → ≤5d · bureau balance utilization tiers → 79/49/29/9% bands autopay → off / unknown = warn promo APR → ≤45d urgent · deferred int. missing-data → min pay, close date → sorted urgent → warning → info RANKED TO-DO URGENTPromo APR ends in 21d — deferred interest risk WARNINGCloses in 3d — pay before close (bureau balance) INFOUtilization 34% — target under 9% for optimized scoring each expands → "why this matters" + recommended action UTILIZATION LADDER · EACH RUNG SHOWS THE PAY-DOWN TO THE NEXT > 79% · URGENT 49–79% · WARNING 29–49% · INFO 9–29% · INFO < 9% · IDEAL ✓ pay $X to next → pay $X to next → pay $X to next → pay $X to next → urgent warning info every insight carries a deterministic confidence stamp
04 / 04 — THE FORESIGHT · PART SHIPPED

Built to add AI
safely.

Every replaceable part sits behind an interface, so a later version can swap in without a rewrite. The headline upgrade: an LLM extractor proposes, a separate deterministic auditor disposes — it scores each field against the source and routes anything low-confidence back to the same human gate from chapter one. The auditor only flags; it never writes. That split is now live and running in production. The five interface sockets below it are still planned — drawn dashed to say so.

EXTRACTION SPLIT LIVE — SOCKETS BELOW STILL PLANNED THE EXTRACTION UPGRADE · OPERATOR PROPOSES, AUDITOR DISPOSES INTAKEraw textfrom any door OPERATOR · LLMproposes fieldsprobabilistic · live AUDITOR · CODEscores each fielddeterministic · live VERDICTflags, never actslow-conf → human ✓ reconciles flag HUMAN REVIEW · LIVE (CH.1)you still approve→ ledger The auditor only flags — it never writes. The human gate stays. FIVE INTERFACE SOCKETS · SWAP V1 → V2 WITHOUT A REWRITE V1 · NOW V2 · PLANNED EmailIntake Manual paste / snap EML upload · IMAP / Mailgun webhook Extraction regex extractCandidates() LLM extractor + deterministic auditor Insight DeterministicInsightProvider LLM insight narrator DocumentStorage (interface only) encrypted blob store Reminder ReminderPlanner · Queue scheduled dispatch (runner exists, no scheduler) V1 · live deterministic planned · LLM / AI low-confidence flag → human