-It's not a product โ no real account, no transfer ever leaves the test
-environment. It's an answer to seven concrete engineering questions, each
-one answered with a measurement, not an assumption. See ๐ง below, or the
-full story in [spec.md](spec.md).
+[Demo script](DEMO.md) ยท [Engineering log](spec.md) ยท [Load test report](https://claude.ai/code/artifact/b40504bd-656e-452a-bb32-3e4ec344bd26) ยท [Development diary](DEVLOG.md)
----
+## What the system guarantees
-## ๐ Quick start
+Each row is a property the code enforces, the mechanism that enforces it, and the test or measurement that checks it.
-```bash
-git clone https://github.com/Adwerse/Neo-Bank && cd Neo-Bank
-cp .env.example .env
-docker compose up -d
+| Guarantee | Mechanism | Evidence |
+| --- | --- | --- |
+| An account never goes negative, even under concurrent transfers | `SELECT โฆ FOR UPDATE` on both ledger rows, in ascending id order, before the balance check | 20 concurrent transfers against a 10,000-unit account: exactly 10 succeed ([test](services/ledger-svc/ledger_test.go#L655)) |
+| A deposit or refund delivered twice is posted once | `pg_advisory_xact_lock` on the operation's reference | 20 concurrent calls sharing one reference produce one ledger entry ([test](services/ledger-svc/ledger_test.go#L965)) |
+| A retried transfer with the same idempotency key moves money once | Unique key on `transfers`; a replay returns the stored row | Load test, duplicates profile: exactly 9.00 replays per executed transfer at 10, 30, 60 and 120 virtual users |
+| A crash cannot drop an event, or publish one for a change that never committed | Transactional outbox: the event row is written in the same Postgres transaction as the change | [`outbox.go:84`](pkg/outbox/outbox.go#L84), relay and cleanup tests in `pkg/outbox` |
+| A transfer whose outcome is unknown is resolved from the ledger, not guessed | It stays `pending`; a worker asks `ledger-svc.GetTransactionByReference` | Run for this README: fraud-svc stopped, transfer answered `202 pending`, worker closed it as `failed / timeout_unresolved` 27 s later |
+| A fraud-service outage never lets a transfer through unchecked | Fail-closed: no fraud decision means no ledger call | Same run: the money did not move while fraud-svc was down |
+| Killing the Postgres leader loses no confirmed transaction | Patroni `synchronous_mode` and HAProxy routing by Patroni role | [`failover_test.go`](infra/failover/failover_test.go#L424): four `docker kill` runs, 23.6โ25.4 s of write downtime, every confirmed pair present on the new leader |
+| A balance on screen is never a stale value pushed over the socket | The WebSocket carries only `balance.changed`; the client re-fetches over HTTP | [`notify.go:55`](gateway/notify.go#L55) |
+
+The repository has 251 Go test functions in 37 files. They run against a real Postgres with no database mocks, and they skip themselves when `DATABASE_URL` is unset. CI builds and vets every workspace module; the integration tests need the compose stack and run locally.
+
+## Product tour
+
+The screenshots and the animation come from a local run on 9 October 2026 with two test users, Maya and Liam. Desktop widths get the light theme and phone widths the dark one; the viewport picks the theme, not the OS setting.
+
+### One transfer, two phones
+
+
+
+Maya confirms โฌ42.50 on the left. Liam's phone receives a `balance.changed` signal over the WebSocket, fetches the new balance and history over HTTP, and shows a toast. Nobody reloads anything.
+
+### Onboarding
+
+| Register | Verification code, delivered to Mailpit |
+| --- | --- |
+| 
| 
|
+
+auth-svc sends the six-digit code over real SMTP to Mailpit, a local inbox, so no email leaves the Docker network. Verifying the code proves ownership of the mailbox and nothing more; there is no KYC.
+
+### Money in, money moved
+
+| Card top-up, Stripe test mode | Transfer confirmation |
+| --- | --- |
+| 
| 
|
+
+A deposit has two separate facts with two statuses: Stripe confirmed the card charge (`succeeded`), and the ledger credited the money (`credited`). The UI says "Payment accepted, crediting within a minute" until the second fact is true. The accounts in these screenshots were funded with [`cmd/devtopup`](services/ledger-svc/cmd/devtopup/main.go) instead, because Stripe's checkout runs an invisible hCaptcha that an automated browser cannot pass. The full deposit flow, from PaymentIntent through webhook to the credit worker, and its manual verification are in [spec.md โ Stripe-funded deposits](spec.md#stripe-funded-deposits-transfers-svc-ledger-svc).
+
+
+
+Liam's desktop dashboard a moment after Maya's โฌ120.00 transfer: the toast, the new balance, the money-flow bar and the operation row all arrived without a reload.
+
+### Fraud check, profile, mobile
+
+| A blocked transfer | Profile |
+| --- | --- |
+| 
| 
|
+
+โฌ6,000.00 is over the `amount_threshold` rule (โฌ5,000.00). fraud-svc names exactly one rule per decision, the API returns `rejected / amount_threshold`, and ledger-svc is never called. The recipient is not told the transfer existed.
+
+ |
+ |
+
| Mobile dashboard | +Transfer form and history with filters | +
+
+One completed transfer: 58 spans across five services in 201 ms.
+
+
+
+The reconciliation worker's trace for the transfer that got stuck while fraud-svc was down. It is a separate trace, connected to the original request by a `FOLLOWS_FROM` span link rather than a parent-child relation, because the parent finished long before the worker started. The worker asked ledger-svc for the reference, found nothing, and closed the transfer as `failed`.
+
+
----
+A successful transfer sends two emails, one to each side. A fraud block sends one email to the sender and does not name the rule. notifications-svc retries five times with backoff, then routes the event to `transfer.events.dlq` so one bad message cannot block the partition.
-## ๐๏ธ Architecture
+## Load test
-
+
+
+
+
+
+
+