graystack

Projects / Ledgerline

Ledgerline

Reconciliation you can explain.

A command-line tool that matches invoices to payments, shows you what it would do before it does it, and keeps a record of every decision that nobody can quietly rewrite.

Role
Product design, engineering
Platform
Node.js CLI, plus a browser terminal
Built with
JavaScript modules, node:test
Status
Concept study · working CLI, 20 tests
A Ledgerline dry run: 23 matches and 7 exceptions, nothing written

01 / The problem

Month-end shouldn't depend on trusting a spreadsheet.

Matching invoices to payments is usually a spreadsheet, a lookup formula and a lot of squinting. When something's off, nobody can say which rule matched what, and a cell can be changed with no record it ever happened.

Silent matching

Lookups pair the first thing they find. A payment that could belong to two invoices just goes to one.

Changes without a trace

Overwrite a cell and the old value is gone, along with who changed it and why.

Exceptions as an afterthought

Short payments and strays live in a comment column instead of a list someone owns.

A concept study, honestly framed. Ledgerline is self-initiated, with no client and no formal research. The CLI is real and tested; the companies in the sample files are made up.

02 / Principles

Four habits of a careful bookkeeper, built in.

Each one is a behaviour of the tool, shown here with its real output.

$ ledgerline reconcile invoices.csv payments.csv
ledgerline reconcile  run a2b447b5b1  
…
 Add --apply to save matches, exceptions and an audit entry.

Look before you leap

Every run is a dry run unless you add --apply. You see the full result first; nothing touches disk until you say so.

match,type,invoices,payments,amount,rule
M-004,split,INV-1004,P-5020 P-5021,3200.00,split: 2 payments name INV-1004
M-015,amount-payer,INV-1018,P-5026,1125.00,no reference; only INV-1018 has this amount from Harbor & Main

Every match explains itself

Each match and exception records the rule that produced it. When someone asks "why did this pair up?", the answer is in the file.

EX-03  ambiguous  
  2 open invoices from Northgate Supply have this amount,
  and the payment names none of them.
 h

Don't guess, ask

When two invoices could fit one payment, Ledgerline doesn't pick. It raises an exception and asks a person to accept, write off or hold it, with a note.

$ ledgerline audit --verify
✗ Chain broken. entry 2 was changed after it was written.
  Entries before #2 still check out.

History you can verify

Every action goes into an append-only log where each entry carries the fingerprint of the one before. Edit the past and the chain breaks visibly.

03 / How matching works

Five passes, in a fixed order.

Each pass only sees what the earlier ones left, so the result is the same however the files are sorted. The chips show what each pass found in the sample month of 30 invoices and 29 readable payments.

  1. 1

    Duplicates first

    Same payer, amount, date and reference as an earlier payment. Flagged before it can match anything.

    1 duplicate
  2. 2

    By reference

    The payment names one invoice: INV-1007, INV1007 and "Payment INV 1007" all count. Several payments naming one invoice is a split.

    19 matched1 split1 short1 over
  3. 3

    Combined payments

    One payment names several invoices and covers them all.

    1 combined
  4. 4

    Amount and payer

    No reference, but exactly one open invoice has this amount from this payer, close to its due date. "Harbor and Main LLC" counts as Harbor & Main.

    2 matched1 ambiguous
  5. 5

    Leftovers

    Invoices nobody paid, with how overdue they are, and payments no invoice claims.

    2 unpaid1 unmatched
✓ 23 matches · $59,984.50 · $7,066.35 in question1 row skipped: amount "TBC"

04 / The audit chain

Try rewriting history.

These are three real audit entries, hashed with the same SHA-256 code the CLI uses. Each one stores its own hash and the hash of the entry before it. Change any note below and watch the chain break.

05 / Try it

The real CLI, running in a browser tab.

This terminal imports the same command code as the Node version and gives it a pretend file system in your browser. Same commands, same output, same exit codes. This demo starts fresh each time.

  1. 1

    Dry run, then apply. Run ledgerline reconcile invoices.csv payments.csv, then again with --apply.

  2. 2

    Work the queue. ledgerline review, then answer with a, w or h. A write-off insists on a reason.

  3. 3

    Break the chain. Press "Tamper with the log", then run ledgerline audit --verify.

Prefer a real terminal? The CLI has no dependencies and needs Node 18 or newer.

Download the CLI (.zip)Open the terminal full size

06 / Screens

A session, start to finish.

Captured from the browser terminal. The Node CLI prints the same lines, in colour.

Dry runInputs, skipped rows, matches by type, and every exception with a plain-language note.
ReviewOne exception at a time, with the invoice and payment lines side by side.
StatusWhat's open, on hold and resolved, mirrored in the side panel.
Audit logWho did what, when, and each entry's hash.
Tamper detectedOne word changed in the log, and verify names the entry.
DarkThe ledger page has a night edition too.

07 / How it's built

One codebase, two runtimes.

The matching core never touches a file, a terminal or a clock. Everything comes in through one small object, so Node and the browser plug in their own and run identical logic.

  • ~690lines across core, commands and audit
  • 20tests on node:test, all passing
  • 0dependencies to install
  • 3exit codes, so CI can fail on open exceptions
  1. A pure coreParsing and matching take text in and return results out. That's what makes 20 fast tests possible, including "same result whatever the row order".
  2. Money in whole centsAmounts are integers from the moment they're read, so totals never drift by a fraction of a cent.
  3. SHA-256 in plain JavaScriptA small synchronous implementation, checked against Node's own crypto, so the same hashing runs in the CLI and the page above.
  4. Decisions tied to inputsA run is identified by a hash of both files and the options. Re-run the same inputs and decisions carry over; change a file and the run starts fresh, with the old decisions still in the log.
  5. Helpful failuresWrong column names, a missing file or a bad flag each get a specific message and a hint, never a stack trace.
commands.js · the boundaryView source
// io = {
//   fs: { read(path) -> string|null, write(path, text), append(path, text), list() -> string[] },
//   out(line)            print one line: a string, or an array of [text, style] parts
//   ask(question)        optional; resolves to the typed answer (enables interactive review)
//   now()                ISO timestamp
//   actor                who is running the command
// }
app/terminal.js · the browser's side of itView source
const io = { fs: fsApi, out: print, ask, actor: "you", now: () => new Date().toISOString() };
npm testreal output
# tests 20
# pass 20
# fail 0

08 / What I'd test next

What real books would teach it.

Ledgerline has only met its own sample data. These are the first things I'd check with a real finance team.

How often is "ambiguous" the right call?

Refusing to guess is safe, but too many ambiguous exceptions makes review a chore.

Test: replay a quarter of real exports
Is the default window right?

45 days after the due date suits most clients. Slow payers might need more.

Test: measure late payments by client
Do reviewers trust the notes?

Plain-language notes should speed up decisions. They need to be checked against how accountants actually phrase things.

Test: think-aloud review sessions
Where should the log live?

A hash chain proves edits happened, not who made them. Signing entries or storing the head elsewhere would close that gap.

Next: signed checkpoints