Household Ledger

01What this has to do

The Google Sheet has been abandoned four times: mid-2024, mid-2025, and again in March 2026. Each time the same way. Recurring bills kept getting logged because there are only a dozen of them and they are predictable. Groceries, gas, and food stopped getting logged because typing every purchase into a phone spreadsheet is more work than anyone sustains.

So the design target is less work per month than the spreadsheet, with better answers. Every decision below is measured against that.

In scope

• One continuous ledger replacing the tab-per-month structure. Trends across years become possible for the first time.
• Bank CSV import that categorizes itself from a rules table you never hand-edit.
• Receipt photos read by a local vision model, split into line items, categorized per item.
• A review queue where a correction takes seconds and never has to be made twice.
• Phone alerts that fire while there is still month left to act, driven by projection and drift rather than by thresholds crossed after the fact.
• A thirty-second daily glance that replaces awareness-through-typing with awareness-through-looking.
• Budgets proposed from what you actually spend.
• Reachable only by two people, over a tunnel, with no open port.

Explicitly out of scope

• Investment tracking, net worth, retirement projections.
• Bill pay, transfers, or anything that moves money.
• Multi-currency. Everything is USD, stored as integer cents.
• Anyone but the two of you. No sharing, no invites, no roles beyond "both of you can do everything."

02Deployment topology

Same shape as the hub dashboard already running at hub.resilientwebsolutions.com, with a different schema and a different allow-list. That system is the working proof this pattern holds.

Model choice is settled by measurement rather than preference. Both models were tested against a synthetic Walmart receipt carrying genuine abbreviated item names. Both extracted 14 of 14 items and every price exactly, summing to the subtotal to the cent. qwen3-vl:8b ran in 88 seconds and got 12 of 14 categories right. gemma4:26b ran in 419 seconds and got all 14, but it is 17 GB against 12 GB of VRAM, so it spills to CPU. The small model fits entirely in VRAM and can share the card with ComfyUI.

That is why the pipeline runs the small model first and escalates only on arithmetic failure. Seven minutes is acceptable when it happens unattended, twice a month.

03Security model

Financial data for a household, so the posture is stricter than a client marketing site.

• Edge authentication. Cloudflare Access holds a policy allowing exactly matthewmcmanness@gmail.com and MarielDryton@gmail.com. Anything else never reaches the origin.
• Origin verification anyway. Middleware validates the Cf-Access-Jwt-Assertion header against the team JWKS, checking the audience tag for this specific app. Defense in depth: a request that somehow bypassed the edge still gets a 403. The hub dashboard's middleware already does this and is the template.
• No open ports. The tunnel dials out. Unlike the AM785 database, which publishes 5433 to the host, this Postgres stays on the Docker network only.
• Authenticated image serving. Receipt photos contain names, card last-four, and purchase history. They are served through a route handler that re-checks the JWT, never from a static directory.
• Identity for attribution. The JWT tells the app which of you is acting, which populates created_by and the audit log. It gates nothing, because you both have full access by design.
• Secrets in Dokploy environment variables. Never in the repository. The repo holds site code only, per the standing rules.
• Audit log. Every category change, rule creation, and import records actor, timestamp, before, and after. Useful for "why is this in the wrong bucket" six weeks later.

04Data model

Postgres via Drizzle. Money is stored as integer cents everywhere, never floating point. This directly fixes a real defect in the current sheet, where amounts are floats and the category column is free text that silently drops a transaction from every total when it is mistyped.

Constraints that matter

• UNIQUE (account_id, external_id) on transactions. This is the deduplication guarantee for repeated CSV imports.
• UNIQUE (image_sha256) on receipts. Photographing the same receipt twice is a no-op.
• category_id is a foreign key. A typo cannot create a category, which is the failure mode that loses money in the current sheet.
• A transaction with is_split = true is excluded from all totals; its children carry the amounts. The parent stays for provenance.

05Architecture

Five layers, with dependencies pointing inward only. The domain layer knows nothing about Postgres, Ollama, HTTP, or Next.js. Services depend on interfaces rather than concrete adapters. Wiring happens in one composition root.

The practical payoff is that the interesting logic (money splitting, rule matching, receipt reconciliation, transaction splitting) stays pure and testable without a database, a network, or a running model.

graph TD
    UI["Delivery: routes, server actions, React screens"]
    SVC["Services: use cases"]
    PORT["Ports: interfaces"]
    DOM["Domain: entities and value objects"]
    ADP["Adapters: Drizzle, Ollama, disk, gws"]

    UI --> SVC
    SVC --> PORT
    SVC --> DOM
    ADP -.implements.-> PORT
  

Domain layer

Immutable value objects and entities with behavior. No I/O, no framework imports, no async.

Ports

Interfaces the services depend on. Every one has a Drizzle or network adapter in production and a trivial in-memory fake in tests.

Adapters

The categorization engine

This is the heart of the system, built as a chain of responsibility. Each strategy either answers confidently or declines and passes along. The first confident answer wins. The order is deliberate: deterministic before probabilistic, always.

interface CategorizationStrategy {
  readonly name: string
  readonly minConfidence: number
  categorize(req: CategorizationRequest): Promise<CategorizationResult | null>
}

// CategorizationRequest  { text, merchant, amount, date, source }
// CategorizationResult   { categoryId, confidence, strategy, ruleId?, rationale? }

Services

06Awareness and alerts

The ledger is plumbing. This section is the product.

A budget exists to change the next purchase. Manual entry used to be the mechanism that made that happen: typing a number forces you to look at it. Automating capture removes that mechanism, so the awareness has to be rebuilt deliberately out of feedback rather than out of data entry. An earlier draft of this plan buried all of it in a late phase, which was the wrong call and is corrected here.

Three signals

Every alert and every headline number derives from one of three computations. They answer different questions and they fail in different ways, so all three earn their place.

Drift is the signal no manual system has ever given you, and it may be the most valuable of the three. Food was budgeted at $74 against roughly $667 of real monthly spending. A budget that wrong is decoration rather than a constraint, and no amount of diligent typing would have revealed it, because a running total compared against a fictional target teaches nothing. A rolling median flags it in the second week.

Projection matters because thresholds arrive too late. Being told you have reached 80% of the grocery budget on the 27th is a report. Being told on the 9th that the current rate lands about $180 over is a warning you can still act on.

Alert design

The failure mode for every notification system is teaching the recipient to ignore it. These rules exist to prevent that, and they are as much a part of the design as the computation.

• Fire on projection rather than a raw threshold. A predicted overspend is actionable. A percentage crossed is trivia.
• Once per category per month. The second alert about the same category is what teaches you to mute the app.
• Nothing after the 25th. Past that point the month is decided and the message becomes a report, which belongs in the Sunday digest.
• An absolute dollar floor. No alert for a projected $6 overage on a $40 category. Percentage-only rules produce noise on small lines.
• A grace period at the start of the month. Nothing fires before the 6th, because three days of data projects wildly and would cry wolf every month.
• Every alert names the action. "Groceries projects to $1,180 against $1,000. About $180 over with 19 days left" beats "Groceries alert."
• Acknowledgeable. Tapping the alert records it, so the same condition stays quiet and the dashboard shows it as seen.

Everything fires from a single daily evaluation at 07:00, inside the window when you are already awake. One evaluation, at most a couple of messages, and silence on a normal month.

The daily glance

Separate from alerts, and the direct replacement for the awareness that manual entry used to provide. A single phone-sized screen showing yesterday's spending line by line, the month-to-date total against pace, and the one category furthest off track. Thirty seconds, no typing, and it carries far more signal than writing down a single $4.12 purchase ever did, because it shows the whole picture instead of one line of it.

Optional friction, kept where it does work

If deliberate friction turns out to matter, it belongs only on spending where a decision actually exists. Bills, mortgage, insurance, and utilities post silently, because there is nothing to influence. Discretionary purchases can require a morning tap to confirm each one: five seconds, no typing, and every discretionary purchase still gets looked at individually. Built as a setting rather than decided now.

Push delivery

Alerts go to your phone through ntfy, which already drives the Uptime Kuma alerts, so both apps are installed and the habit exists. It supports priority levels, tags, and tappable action buttons that can deep-link into a specific screen.

Charts

Each chart earns its place by supporting a decision. Anything that only looks like a dashboard is left out.

The median-band trend chart is the one the current spreadsheet structurally cannot produce. A tab per month means there is no way to compare across months without rebuilding the comparison by hand every time.

07How the pieces connect

Receipt, photograph to ledger

sequenceDiagram
    participant P as Phone
    participant API as Upload route
    participant PL as ReceiptPipeline
    participant V1 as qwen3-vl 8b
    participant V2 as gemma4 26b
    participant CE as CategorizationEngine
    participant RC as ReconciliationService
    participant DB as Postgres

    P->>API: photo (multipart)
    API->>PL: ingest(bytes, user)
    PL->>DB: store image, receipt PENDING
    Note over PL: timer fires, every 15 min
    PL->>V1: extract(image)
    V1-->>PL: items, totals
    PL->>PL: reconciles?
    alt sums to subtotal
        PL->>CE: categorizeMany(items)
        CE-->>PL: categories and confidence
    else does not sum
        PL->>V2: extract(image)
        V2-->>PL: items, totals
        PL->>PL: reconciles?
        Note over PL: still failing, NEEDS_MANUAL, stop
    end
    PL->>RC: matchReceiptToBank(receipt)
    RC->>DB: split the bank line into categories
    RC-->>PL: matched
    PL->>DB: receipt POSTED
  

Correction, and why it compounds

graph LR
    A["You change one dropdown"] --> B["ReviewService.applyCorrection"]
    B --> C["Transaction or LineItem updated"]
    B --> D["RuleLearner.proposeFrom"]
    D --> E{"Conflicts?"}
    E -->|no| F["Rule saved"]
    E -->|yes| G["Shown to you, held back"]
    F --> H["Engine re-runs over the queue"]
    H --> I["Other matching items clear themselves"]
    F --> J["Every future import matches automatically"]
  

That last edge is the entire argument for building this. You buy roughly the same hundred-odd items in rotation, so once the rules table has seen them, new items become genuinely rare. Expect around twenty-five decisions in week one, six by week four, and one to three a month by the third month.

08Screens

The review screen gets disproportionate design effort because it is the only screen whose speed determines whether the system lives. Everything else is read-mostly.

09Scheduled jobs

systemd --user timers, matching the existing convention on this box. No crontab.

Sunday 06:00 keeps clear of the 05:00 personal Gmail purge and lands inside the 4 to 6am window when you are actually up.

10Backup and recovery

This is your own data rather than a client's, so losing it carries more weight.

• Nightly pg_dump to ops/backups/budget/, same pattern as the AM785 database dumps, with 30 days retained.
• The receipt image volume is archived on the same schedule. Images cannot be reproduced; the database can at least be rebuilt from CSV re-imports, but a lost photo is lost.
• One offsite copy. A local-only backup does not survive the thing most likely to destroy the server.
• A restore is tested once, at build time, and written down. An untested backup is a guess.

11Testing

The layering exists so the valuable tests need no database and no model.

Vitest, matching the hub dashboard's setup. The vision extractor is tested against saved fixture images and their known-correct output, so model behavior can be re-checked after any model upgrade without re-photographing anything.

12Build phases

Sequenced so something usable exists early. A half-finished app is worse than the working spreadsheet, and this budget has been abandoned four times already, so shipping a small complete thing beats a large incomplete one.

13Open decisions

These need answers from you. Most are small; the first one is large.