Architecture

How Ledgerful works locally.

Ledgerful reads your repo, analyzes it entirely on your machine, and writes real evidence to disk. The local engine, the loopback dashboard, and this public site are three distinct surfaces — a future hosted control plane is planned and always marked as such, never shown as already live.

What goes in, what runs locally, what comes out.

Before the surfaces and the diagram below, here is the actual workflow — with real, redacted evidence beside each output, not a mockup.

READS

Your repo. Nothing more.

Ledgerful reads your local git repository: the working tree, diffs against a base ref, commit history, and its own local config and state under .ledgerful/. It does not read files outside the repo, and source code, diffs, and commit messages are not uploaded anywhere by default.

ANALYZES

A deterministic local engine.

scan, verify, and audit run entirely on your machine — deterministic checks against repo state, no network calls by default. The ask workflow is the one path that can leave the box, and only when you configure and select a cloud model; it is a separate, explicitly configured mode, not part of the default analysis.

PRODUCES

Three real outputs, each with real evidence.

A scan can produce a risk summary, a verification plan, and a signed provenance record written to the ledger; the dashboard can turn ledger history into a SOC2-style evidence export. Below is real, redacted output captured from each — the same artifacts shown on the homepage.

Verification plan

Verification Plan  Source: Auto-Policy  Runner: cargo test  • Check for whitespace errors in staging area  • Check for whitespace errors in working tree  • Run buildVerification Steps:  • git diff --cached --check (timeout: 400s)  • git diff --check (timeout: 400s)  • npm run build (timeout: 400s)Dry run mode: verification plan displayed above. No commands were executed.

Verification plan — captured 2026-07-03, engine v0.1.7, sample repoledgerful verify --dry-run

Signed provenance record

tx_id:        6341380a-5a23-4b12-a1f3-19bd54630296category:     BUGFIXentity:       invoice-tax-rate-fixchange_type:  Modifysummary:      Add TX region tax rate; tighten session validity checkreason:       Closed a billing gap and a session edge case found during reviewcommitted_at: 2026-07-03T05:05:33.663336200+00:00signed:       yessignature:    382829cdca90ba3d844fc376f34ebbf559ccaf58d92ba3267d1046ef28a5602837a3f8368c3a2e4fc7cefcb39fba75b5b06c83233ec67cdf448fccc121eb3202

Signed provenance record — one real row from the verified sample-soc2 exportledger.csv — signed entry

Evidence export manifest

{  "generatedAt": "2026-07-03T05:47:57.608023+00:00",  "files": [    { "name": "ledger.csv", "sha256": "5fd8b59fa895489acbe6a848e3c1614d0c02a63da98ea1d077c9f79323753669", "size": 1039 },    { "name": "verification_history.csv", "sha256": "56ef6d6ace5d5bd1381b764ec3d0398c30c7225219aec22c0029e65cf6ed0e84", "size": 57 }  ],  "entryCount": 3}

Evidence export manifest — tamper-evidence hashes, sample-soc2 exportmanifest.json

Surfaces and the local-first boundary

The host runs the engine and dashboard. The public web is static and does not host a control plane. The hosted mode is planned and is shown dashed.

YOUR MACHINE

SURFACE 01 · ENGINEledgerful CLIscan · ledger · audit · verify · mcpsync is feature-gated · --features sync

SURFACE 02 · DASHBOARDEmbedded UIlaunch token → in-memory Bearer authloopback only · no external bind

LOCAL-FIRST BOUNDARYsource code · diffs · keys · ledger · auditall on host · no upload by default · telemetry is opt-in

SURFACE 03 · PUBLIC WEBledgerful.devstatic · docs · pricingno hosted auth

PLANNED · NOT LIVEHosted control planetenancy · audit · identity

Your machine hosts the engine (CLI) and the embedded dashboard, grouped inside the “YOUR MACHINE” boundary. Nothing in that boundary uploads by default; the dashboard binds to 127.0.0.1only and telemetry is opt-in. Outside the boundary, the public web is a static site with no hosted backend. The hosted control plane, shown with a dashed border and labeled “planned · not live,” does not exist yet.

The three surfaces today

Each surface has an explicit state. No hosted or enterprise capability is presented as live before the control plane exists.

SURFACE 01Available

Local CLI and engine

The Ledgerful binary runs entirely on your machine. The default build owns the ledger, scan, audit, verify, web (daemon), and MCP command surfaces. Local sync is feature-gated and requires a --features sync build. No remote service is required for normal operation.

Runs on host · no network calls by default

SURFACE 02Local-only

Embedded loopback dashboard

The dashboard is a local web UI served by the Ledgerful daemon, bound to 127.0.0.1:52001 with an ephemeral session token. It is not accessible from the internet or other machines on your network.

Binds 127.0.0.1:52001 · one-time launch token → Bearer auth

SURFACE 03Available

Public marketing and docs

This site. Static, deployable on Vercel, no hosted backend. Public docs describe the local product; they do not run a hosted control plane.

Static · Vercel deployable · no authenticated state

Operating modes and their data flow

Five modes describe what crosses the local-first boundary. Scan, ledger, audit, verify, dashboard, and export stay local. Feature-gated sync also stays local when compiled with --features sync; cloud model context and aggregate telemetry are separate configured paths.

Mode	What crosses the boundary	Status
Local default	Ledgerful runs on your machine, reads from your repo and local files, writes to .ledgerful/. Source code never leaves the host. No remote calls for scan, ledger, audit, or export.	Available
Local team sync	With a sync-enabled build, signed and encrypted bundles are written to a directory you choose. You control the transport (a shared drive, a USB stick, or any other dir://-compatible path). Nothing broadcasts.	Beta
Telemetry (opt-in)	Disabled by default. When enabled, structured usage events are sent to a Supabase ingest endpoint. Source code, file content, diffs, and commit messages are never transmitted.	Available
Configured cloud model	The ask workflow can send sanitized, truncated impact and retrieved codebase context to Gemini, Ollama Cloud, or OpenRouter when that provider is configured and selected. Local-model operation does not use this path.	Available
Hosted control plane	A future hosted mode will add tenancy, hosted audit log, GitHub App callbacks, billing, and SSO/SCIM/RBAC. None of this is shipped today — see /pricing for explicit state labels.	Hosted planned

Telemetry, when enabled, sends the aggregate schema documented on the trust page. Separately, configured cloud-model ask workflows can send sanitized, truncated context to the selected provider. See the trust page for the full telemetry schema.

DETAIL · DAEMON BIND

The dashboard is loopback-only.

The local daemon binds exclusively to http://127.0.0.1:52001. CORS is restricted to localhost and 127.0.0.1 on any port — cross-origin requests from remote or hosted domains are rejected. The launch URL carries an ephemeral ?token=<hex> once. The dashboard captures it in memory, strips it from the browser URL, and sends subsequent API requests with Authorization: Bearer <hex>. Tokens are per-session and are never persisted to disk.

DETAIL · KEYS & EXPORT

Keys and evidence export stay on disk.

An Ed25519 key pair is generated on first use via OS entropy. The signing key and verifying key are stored as hex-encoded files at ~/.ledgerful/keys/private.key and ~/.ledgerful/keys/public.pem (Windows: %USERPROFILE%\.ledgerful\keys\). The SOC2 evidence ZIP is generated entirely from local data; the manifest, signature, hashes, ledger CSV, verification history, and ADR files never leave the host during export.

Hardware-backed key storage, hosted KMS, SSO/SCIM, and RBAC are enterprise planned. They require the future hosted control plane and are not implemented in the local daemon.