Match WhatsApp orders to mobile money payments, flag suspicious confirmations, and keep an auditable double-entry record.
Built for Kiroween 2026 (Frankenstein category).
See .kiro/specs/chat-ledger/ for requirements, design, and tasks.
License: Apache-2.0
Prerequisites: Java 21, Maven 3.9+, Docker.
# 1. Copy the environment template and fill in the placeholders
cp .env.example .env
# Edit .env — replace every <replace-…> placeholder with real values
# 2. Start PostgreSQL
docker compose up -d
# 3. Build and run all module tests
mvn verify
# 4. Start the application
mvn -pl web spring-boot:run
# Open http://localhost:8080/health| Module | Responsibility |
|---|---|
ledger-core |
Double-entry accounts, immutable entries, balance invariant |
extraction |
Order parser, payment templates, optional AI extractor |
ingestion |
HTTP endpoints, HMAC verification, idempotency, rate limits |
matching |
Scoring engine, match thresholds, overrides, ledger postings |
suspicion |
Advisory rule set: duplicate TX, name mismatch, time anomaly … |
web |
Board UI (Thymeleaf + HTMX), simulators, CSV export, auth |
GitHub Actions runs on every push:
mvn verify— builds all modules and runs tests.mvn -P security-check verify -DskipTests— OWASP dependency vulnerability scan (fails on CVSS ≥ 7; pull requests and daily).- The image, in three jobs: build it to an archive and run the whole deployment stack and its smoke test on it; scan the archive with
Trivy (fails on a fixable HIGH or CRITICAL finding); on
mainonly, push that same archive toghcr.io/deval123/chat-ledger, from a job that runs no third-party code. Every action is pinned by commit SHA.
A separate Uptime workflow checks the public demo every 30 minutes.
- Secrets are loaded from environment variables only. See
.env.example. - Phone numbers are stored hashed with a per-tenant salt plus the last 4 digits.
- Ledger entries are append-only at the database level; corrections use reversals.
- See
.kiro/steering/security.mdfor the full security policy.
https://ledger.nkap.dev opens a demo workspace in one click. There is no sign-up and no demo password: each visitor gets a workspace of made-up data for 30 minutes, with seven scenarios to run (the scenarios page).
The demo uses synthetic data only. No real phone numbers, names, or operator wording appear anywhere in the repository.
Warm-up. The demo runs on an always-on server, so there is no cold start for visitors. Right after a deploy or a restart, the application takes up to a minute to start (Cloudflare answers 502 until then), and the first pool of demo workspaces about one more minute to fill ("All demo workspaces are in use" until then).
How it is deployed (a Docker Compose stack behind its own Cloudflare tunnel, on a server shared with another project):
deploy/RUNBOOK.md.
There is no sign-up page. An operator creates a workspace and its first seller, then more users, with two
one-shot commands. They connect as a separate database login (PROVISION_DB_* in .env.example) that can
only run the two provisioning functions. The new user's password is typed at a prompt or piped on standard
input; it is never accepted as an argument or an environment variable.
java -jar web/target/web-*.jar provision-tenant --workspace river-shop --name "River Shop" --email seller@example.test
java -jar web/target/web-*.jar provision-user --workspace river-shop --email helper@example.test --role HELPER
A database created before the provisioner role existed needs the role and the grants once, as the database superuser (migration V013 already created the functions):
CREATE ROLE chatledger_provisioner NOLOGIN;
GRANT EXECUTE ON FUNCTION provision_tenant(text, text, text, text), provision_user(text, text, text, text)
TO chatledger_provisioner;
-- and a login role that is a member of it, with a password you generate
- Every tenant table has row-level security and every query is scoped by tenant; ledger and audit rows can never be updated or deleted.
- Passwords are Argon2id. Sign-in failures all look the same, and sign-in is throttled per account, per address and per concurrent password check. There is no sign-up page: an operator provisions workspaces and users.
- Sessions use a
__Host-cookie (Secure, HttpOnly, SameSite=Strict), expire after 30 minutes idle and 12 hours in total, and every POST needs a CSRF token (htmx pages carry it as ahx-headersattribute on<body>). - A strict content security policy is sent with every response. Templates may not contain inline scripts, styles, event handlers or unescaped output; a test reads every template.
- Request bodies are limited (4 KiB login, 16 KiB JSON, 64 KiB otherwise) and must be clean UTF-8 without control characters.
- Secrets come from environment variables only.
mvn -Psecurity-check verifychecks dependencies for known vulnerabilities. - Not yet in place: TLS and trusted-proxy settings (deployment, task 13), so HSTS and per-address limits behind a proxy need that step.
- Order text from chat messages is untrusted data: it is re-validated, parsed by a strict deterministic parser (no pattern is built from it), stored with bound parameters only, never logged, and escaped on output. Phone numbers are stored only as a keyed hash plus the last four digits.