BancaVoz

BancaVoz is a voice-first bookkeeping MVP empowering informal market sellers to securely record sales, expenses, and credit hands-free using an idempotent, append-only ledger.

Comment

Inspiration## Inspiration

Informal market sellers in Mozambique, like sellers everywhere, run on cash, memory and trust. Their hands are busy serving customers, so sales get rebuilt from memory at closing time, and credit given to regulars (fiado) is one of the easiest records to lose. A seller can talk while handling goods and cash, so I built a bookkeeping service you can speak to.

What it does

BancaVoz is a voice-first bookkeeping MVP. A seller records sales, expenses, customer credit and payments, asks for a summary, checks stock and top sellers, and reverses the latest entry. It works through a FastAPI service, an MCP server mounted at /mcp over Streamable HTTP, or a browser simulator with a microphone fallback.

How I built it

  • Python and FastAPI for the API, with a pinned version of the official MCP SDK mounted in the same app, so tool calls and plain HTTP run against one service.
  • Money safety first. Amounts arrive as decimals and are stored as integer minor units, $\text{minor units} = \text{amount} \times 10^{d}$, where $d$ is the currency's decimal places, so rounding errors cannot creep into totals.
  • Idempotent writes and an append-only ledger. A repeated command does not double-book, and an undo is a reversal entry, so corrections leave a trail.
  • A deterministic simulator that works without AWS credentials, so every flow can be tested offline.
  • A dependency-free web console: semantic HTML, local CSS and ES-module JavaScript, with bearer-token auth.
  • Tests for money conversion, idempotency, merchant scoping, undo, auth, the simulator and MCP listing and calls. SQLite for local use, and a Docker image.

Challenges I ran into

  • Making money handling safe before making it clever.
  • Mounting the official MCP SDK inside a FastAPI app and keeping its version pinned.
  • Keeping the console honest: credit balances, a ledger listing and console writes are marked unavailable because their backend endpoints do not exist yet.
  • Testing limits: Alexa+ connectivity is not verified, and live PostgreSQL, external HTTPS and the full six-utterance acceptance run are still open.

What I learned

  • A voice interface is only as forgiving as its ledger. Idempotent writes and reversible entries matter more than clever parsing.
  • A simulator that needs no credentials makes every flow repeatable and testable.
  • Writing down what is not done (docs/GAPS.md, FRICTION_LOG.md) is part of shipping.

What's next

  • Backend endpoints for credit balances and a ledger listing, so the console can show and write them.
  • Validate PostgreSQL hosting, HTTPS and an external smoke test.
  • Test against real Alexa+ access and with real sellers.

Built With

Share this project:

Updates

Submission history