Archon: The unattended month-end close

An AI agent that closes an owner-operator trucking firm's month end to end, unattended on Google Cloud, and finds the money one batched broker payment was hiding.

Comment

Inspiration

I build back-office software for finance teams. Archon is the month-end close for the firms that software never reaches: an owner-operator trucking firm of three trucks, whose owner does the books at the kitchen table on Sunday night, and who cannot afford the bookkeeper every accounting product quietly assumes.

The reason those books do not get closed is structural, not lazy. A freight broker does not pay per load. It pays once a fortnight: one bank credit covering eight loads, minus a factoring fee charged on the whole batch. The bank shows one number. The books need eight. Nobody unpicks that on a Sunday, so a short payment sits there for a year.

On the month in the demo, $612.85 was quietly leaking, invoiced and never paid, invisible because one payment covered eight loads. Against a margin of $0.223 a mile, that is not noise.

What it does

Archon closes the month unattended. A file lands in Cloud Storage, the bucket notifies Pub/Sub, its push subscription wakes a Cloud Run container, and a Google ADK agent runs eleven steps:

  1. Takes in the month's mail, 27 artifacts, each hashed
  2. Posts the double-entry journal
  3. Splits each remittance back across the loads it settles
  4. Reconciles loads against what the brokers actually paid
  5. Finds what is missing or does not add up
  6. Decides what to do about each exception
  7. Writes the corrective documents
  8. Checks the close against its own gates
  9. Writes the month-end summary
  10. Files the close and marks the period
  11. Writes the owner their month-end letter

Nobody is asked anything at any point. The single human act is approving the letters that would leave for a third party.

The identity the product rests on. One payment of $18,667.65 splits across the eight loads it settles; the $577.35 factoring fee is charged once on the batch, not per load; the residual is asserted at 0.00. If that line does not close, nothing else here is worth reading.

Ten deterministic detectors, not a model's opinion: short pay, payment without document, duplicate charge, amount outlier, tax inconsistency, unpaid load, unreconciled remittance, out of period, unreadable document, unrecognised document. Thresholds are learned from the firm's own books, so it works on a firm's first month with nothing configured.

Seven gates that can refuse the close. An agent may withhold a month it does not trust; it may never grant one the gates refused. A gate with nothing to check reports skipped rather than passing quietly, so the headline count is what was actually verified.

Letters drafted and filed, never sent. There is no counterparty delivery in this submission and the page says so.

How we built it

The design rule the whole thing defends: the agent orchestrates, the ledger computes.

archon.domain is pure Python, no ADK, no Firestore, no FastAPI, no network, and a test asserts that by walking its imports. Gemini is handed a fact sheet of already-computed figures. It is never handed a document and never asked for a total. Run the month under standing policy, then again under an agent told to chase nothing: every figure is identical and only the dispositions differ. That boundary is asserted, not described.

Built on Cloud Run, Cloud Storage, Pub/Sub, Firestore Native, Vertex AI (Gemini 3.7 Flash), Google ADK, declared in Terraform, with Workload Identity Federation for CD so no service-account key exists anywhere. POST /events verifies a Google-signed OIDC token for this service's own audience, minted by one named service account; an anonymous call gets 403.

Everything is evidenced. Each close persists source hashes, a run id, the release that produced it and an eleven-step trail to Firestore. 865 tests run offline with no key and no network. Each of the seven gates is broken on purpose in the suite and asserted red, because a gate nobody has watched fail is a gate nobody should believe.

Challenges we ran into

A store that said yes to everything. get_store() returned a new in-memory store on every call. Nothing written was ever read back, so the idempotency marker was claimed in one throwaway object and looked for in another, and a redelivered Pub/Sub message closed the month twice. Seven hundred tests missed it, because an always-empty store approves every claim. Firestore was never affected, so it was broken exactly where the tests and the demo run, and nowhere a deployment would show it.

A fence that never ran. A superseded worker was supposed to be stopped before it could send the owner's digest. The guard implemented send(); the protocol declares deliver(). It had never once executed. My own test used a double with the wrong method, so its counter stayed at zero and the test passed.

Two gates contradicting each other on the same screen. G5 reported the unreadable scan as none posted, correctly. G4 counted the memo entry that records its arrival and called it a document that posted once. The panel said 27 documents posted and, two rows down, that one of them had not.

A fabricated trend. The "close your own month" feature compared a visitor's uploaded documents against this firm's June, under a heading reading "Against the month before". Not a wrong label a reader could discount, a real trend, computed correctly, between two different companies' books.

Every one of those was fixed with its failing reproduction committed first.

Accomplishments that we're proud of

It closes a month with nobody watching, and it can say no. The remittance identity closes to the cent. The comparison baselines are in the repo: three plain reconciliation strategies recover 0.00 on this month against Archon's 200.00 short-pay recovery, because none of them unpicks a batched payment.

And the honesty is load-bearing rather than decorative. The README has an Honest scope section listing what this does not do, including one persistence race that is narrowed but not closed, written down as open. The page distinguishes gates that ran from gates that were skipped. The demo month is synthetic and labelled synthetic on every screen.

What we learned

A test that has never been watched to fail is not evidence. Two of the worst defects here were sitting under green suites: the store bug hid behind an always-empty store, and the delivery fence hid behind a test double with the wrong method name. Both were found by measuring what actually executed, not by reading code.

Numbers rot in prose. Every count this repository states, tests, detectors, gates, tools, the console block in the README, the figures voiced in the video narration, is now pinned by a test that reads the code and compares. Several of those tests caught drift before a human did.

Skipped is not passed. "7/7 gates passed" when two had no inputs is a stronger claim than the run can carry.

What's next for Archon

The vocabulary here is freight, and this ships one complete freight domain pack rather than a general platform. The next pack is the same shape with different documents. Beyond that: a real approval endpoint with counterparty delivery, multi-currency months, and closing the persistence race properly by putting the ownership check and the write inside one transaction in every store.

Try it

No account, no install: https://archon-70489367760.us-central1.run.app/

Press Guided tour in the top bar for the eight beats in order, or Replay the unattended close to walk the eleven steps of the close that a Cloud Storage object already triggered. Your own month closes a month of your own .txt documents in memory, stored nowhere, never sent to a model.

Bell Ridge Haulage is synthetic. Every firm, broker, supplier and figure is invented, and the counterparty names were checked against public carrier registries to make sure none belongs to a real business.

Built With

Share this project:

Updates

Submission history