"Say what you sold. Understand what you built."
EasyLedger is a voice-first transactional sales ledger and interactive dashboard builder designed for small merchants, drink-stall operators, and retail kiosk owners. Powered by the AssemblyAI Voice Agent API, Fastify, and PostgreSQL, EasyLedger enables merchants to record sales naturally by voice, correct mistakes conversationally with an immutable audit trail, query sales performance, and customize live visual analytics dashboards.
Small business owners and kiosk operators juggle customer orders, cash handling, and physical inventory simultaneously. Keeping sales records on paper ledgers or generic spreadsheet apps creates heavy cognitive friction:
- Attention is divided: Typing numbers into a phone or writing on paper pulls the merchant away from serving paying customers.
- Mistakes create confusion: Crossing out lines or editing cells destroys operational audit history and causes end-of-day cash reconciliation discrepancies.
- Raw lists lack insight: Long transaction tables fail to quickly answer essential business questions: "What was my best-selling juice today?" or "How does this week compare to last week?"
- Natural Voice Logging: Merchants speak sales transactions in plain language while handling orders.
- Two-Phase Confirmation Engine: EasyLedger treats voice as an input stream, not an unquestioned database writer. Voice proposals are calculated in exact minor currency units (cents / integer rupiah) and displayed as a structured receipt before explicit merchant confirmation.
- Conversational Mistake Correction: Saying "Actually, eight orange juices, not ten" updates the existing record with an immutable revision history rather than creating duplicate sales.
- Voice-Driven & Direct Dashboard Builder: Merchants can ask questions or use drag-and-drop controls to arrange KPI cards, revenue line charts, and product volume bar charts powered by Apache ECharts.
-
Zero Floating-Point Financial Arithmetic: All currency calculations use exact integer arithmetic, completely eliminating floating-point rounding bugs ($0.10 + $0.20 \neq
$0.30000000000000004$ ). - Graceful Fallback & Accessibility: Full WCAG 2.1 AA compliant keyboard and touch controls ensure continuous operation if microphone access is unavailable or in loud environments.
| Component | URL | Status | Notes |
|---|---|---|---|
| Web Application | https://easyledger-web.onrender.com | Live | React 18, Apache ECharts, Voice Streaming |
| Backend REST & Tool API | https://easyledger-api.onrender.com | Live | Fastify, Node.js, PostgreSQL |
| GitHub Repository | https://github.com/dragonsterm/EasyLedger | Public | Open-Source under MIT License |
| Presentation Video | Included in submission (easyledger-hackathon-demo.mp4) |
Ready | 2m 29s end-to-end golden journey walkthrough |
Judges can explore the hosted application immediately:
-
Sandbox Email:
demo@easyledger.local -
Sandbox Password:
demo12345 -
Quick Voice Test: Click Voice Entry (or press the microphone button) and say:
"Today I sold 10 orange juices at $1.50 each and 6 mango juices at $1.80 each."
-
Follow-up Correction:
"Actually, make that eight orange juices."
EasyLedger connects client-side microphone streams to the AssemblyAI Voice Agent API. The voice agent interprets merchant intent, extracts entity parameters (products, quantities, unit prices, date ranges), and invokes registered tools through our secure backend tool gateway:
| Tool Name | Purpose | Merchant Voice Example | Backend Execution Contract |
|---|---|---|---|
propose_sales |
Parses sales items, matches catalog products, and calculates total in exact minor units | "I just sold four cold brew coffees for twelve dollars total." | Generates an uncommitted proposal with unique ID and SHA-256 payload hash; returns formatted receipt. |
propose_correction |
Identifies an existing sale record and stages an auditable adjustment | "Actually, change that to three cold brews, not four." | Compares old vs. new state; stages revision without mutating the database until confirmed. |
create_product |
Adds a new product to the merchant's catalog by voice with spoken price parsing | "Add Avocado Juice priced at twenty thousand rupiah to my catalog." | Validates name and minor-unit price (e.g. "20k", "twenty k"); creates catalog entry and refreshes views. |
query_sales |
Aggregates revenue, unit volume, and product breakdowns across date ranges | "What was my total revenue yesterday compared to today?" | Executes deterministic parameterized SQL aggregation; returns exact BigInt totals. |
update_dashboard |
Modifies dashboard layouts (add, edit, move, resize, remove widgets) | "Add a bar chart showing sales by product to my dashboard." | Validates layout boundaries (max 20 widgets) and updates the active canvas state. |
save_dashboard |
Persists the current canvas layout to the database | "Save this view as my Daily Sales Journal." | Optimistic locking via compare-and-swap on version numbers. |
set_day_coverage |
Marks a trading day as verified complete or open | "Mark today's ledger as closed." | Audited coverage state preventing missing-vs-zero misinterpretations. |
| Layer | Technology | Version / Specification |
|---|---|---|
| Voice Infrastructure | AssemblyAI Voice Agent API | Real-time bidirectional voice agent with registered tool calling |
| Frontend Framework | React 18 + Vite | Modular TypeScript architecture with minimal dependencies |
| Data Visualization | Apache ECharts 6.1 | Responsive line charts, product volume bar charts, and KPI widgets |
| Layout Engine | react-grid-layout | Responsive drag-and-drop canvas with collision detection |
| Backend Server | Node.js + Fastify 5.12 | High-throughput async HTTP server with JSON Schema validation |
| Database | PostgreSQL 16 (Render Managed) | Relational database with strict foreign keys and transactional migrations |
| Authentication | Session Tokens + bcrypt | Tenant-scoped session cookies with rate limiting and origin checks |
| Integrity & Security | SHA-256 + BigInt Arithmetic | Exact minor-unit currency calculations and idempotent mutation receipts |
| Accessibility | axe-core + WCAG 2.1 AA | Full manual keyboard and touch fallbacks |
| Hosting & Cloud | Render Cloud Platform | Containerized multi-stage Docker build + Render Managed PostgreSQL |
┌──────────────────────────────────────────┐
│ Merchant │
│ (Voice Microphone / Touch Display) │
└────────────────────┬─────────────────────┘
│
Audio Stream (Web Audio) / HTTP Touch UI
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ EasyLedger Web Client │
│ - React 18 Single-Page Application (Vite) │
│ - VoiceControl Panel (AssemblyAI WebSocket streaming adapter) │
│ - Interactive Dashboard Canvas (Apache ECharts + react-grid-layout) │
│ - Manual Ledger Table & Catalog Manager (WCAG 2.1 AA accessible) │
└──────────────┬───────────────────────────────────────────────┬──────────────┘
│ │
WebSocket Audio Streaming HTTP REST / JSON
│ │
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ AssemblyAI Voice Agent API │ │ Fastify API Server │
│ - Real-time STT streaming │ │ - Tenant-scoped auth │
│ - Turn-taking & intent │ │ - Idempotency middleware │
│ - Registered Tool Calling ├────────────────►│ - Exact BigInt arithmetic │
└─────────────────────────────┘ HTTP Tools │ - Optimistic concurrency │
└──────────────┬──────────────┘
│
Parameterized SQL
│
▼
┌─────────────────────────────┐
│ PostgreSQL Database │
│ - businesses, users │
│ - products, catalog │
│ - sales_records (append) │
│ - sale_revisions (audit) │
│ - dashboards & widgets │
└─────────────────────────────┘
To protect merchants from noisy transcriptions or unintentional mutations, EasyLedger enforces a strict two-phase state machine:
[ IDLE ]
│
▼ Spoken input
[ LISTENING ] ──► (AssemblyAI Voice Agent)
│
▼ Entity extraction & tool selection
[ PROPOSING ] ──► (Backend Tool Gateway calculates exact totals)
│
▼ Visual & audio receipt preview
[ AWAITING CONFIRMATION ]
│
├── Merchant cancels ──► [ PROPOSAL CANCELLED ] (Zero ledger changes)
│
└── Merchant confirms ("Yes" / Touch confirm)
│
▼
[ COMMITTED ] ──► (Atomic PostgreSQL write with SHA-256 idempotency token)
│
▼
[ REAL-TIME SYNC ] ──► (ECharts & Ledger table update instantly)
- Node.js: v20.x or higher
- PostgreSQL: v15.x or higher (local instance or cloud database URL)
- AssemblyAI API Key: Required for live voice streaming (get one at assemblyai.com)
git clone https://github.com/dragonsterm/EasyLedger.git
cd EasyLedgernpm install
cd apps/web && npm install && cd ../..Create a .env file in the root directory:
cp .env.example .envEnsure your .env contains the required keys:
PORT=3000
DATABASE_URL=postgresql://postgres:password@localhost:5432/easyledger
ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
COOKIE_SECRET=at_least_32_characters_random_secret_string
CORS_ORIGIN=http://localhost:5173
NODE_ENV=developmentRun the automated migration runner to apply database schemas and synthetic demo data:
npm run db:migrateRun backend and frontend concurrently:
# Terminal 1: Backend API
npm run start:dev
# Terminal 2: Web Client
cd apps/web && npm run dev- Web Client:
http://localhost:5173 - API Server:
http://localhost:3000
Verify domain logic, API routes, and database integrity:
npm testAll 65 automated tests verify:
- Exact BigInt currency arithmetic (IDR & USD).
- Idempotent sales creation and mistake correction.
- Multi-tenant data isolation and rate limiting.
- Dashboard optimistic locking and 20-widget boundary rules.
- 10,000 synthetic records performance benchmark (p95 < 1s).
This repository follows a structured, auditable documentation methodology compatible with Obsidian Vault and Graphify:
| Document | Purpose |
|---|---|
docs/00-Home.md |
Documentation index and navigation map |
docs/01-Product-Brief.md |
Product vision, target persona, and the golden journey |
docs/02-SRS.md |
Formal Software Requirements Specification (functional & non-functional) |
docs/03-Architecture.md |
End-to-end component topology and communication boundaries |
docs/04-Decisions.md |
Architectural Decision Records (ADRs) |
docs/05-Data-Model.md |
Exact money arithmetic, schema DDL, and audit revision rules |
docs/06-Agent-and-API.md |
AssemblyAI tool definitions and REST API contracts |
docs/07-Dashboard-and-UX.md |
ECharts integration, layout builder, and design tokens |
docs/08-Security-and-Operations.md |
Multi-tenant isolation, bcrypt hashing, and rate limiting |
docs/09-Verification.md |
Test plan, acceptance criteria, and synthetic data verification |
docs/18-Hackathon-Rules.md |
Official lablab.ai x AssemblyAI hackathon compliance matrix |
DESIGN.md |
Design token specifications and typography standards |
EasyLedger was built specifically for the AssemblyAI Voice Agent Hackathon hosted by lablab.ai:
| Judging Criterion | Focus & Requirement | EasyLedger Evidence & Implementation |
|---|---|---|
| Application of Technology | Effective, deep, and correct integration of AssemblyAI Voice Agent API | Native WebSocket voice streaming, structured tool calling (propose_sales, propose_correction, query_sales, update_dashboard), and turn-taking without third-party LLM bloat. |
| Business Value & Practical Utility | Real-world problem solving for a defined audience with clear product-market fit | Directly addresses the daily operational pain point of micro-merchants and food kiosks. Reduces sales entry time from 30+ seconds to a 4-second spoken sentence. |
| Presentation & Demo | Pitch clarity, technical storytelling, and working video demo | High-fidelity 1080p demo video demonstrating real voice input, mistake correction, and instantaneous ECharts visual reflection. |
| Technical Execution & Completeness | System stability, architecture robustness, deterministic data handling, and online prototype | Exact integer cents arithmetic, immutable revision tracking, 65 automated tests passing with 100% coverage on core rules, and fully hosted prototype on Render. |
Built by Team TokenMaxxing:
- Jauza Ilham Mahardhika Putra — Full-Stack Engineering, Frontend Architecture, ECharts & Layout Engine, AssemblyAI Streaming Integration.
- Badar Rahman — Backend Architecture, Database Schema & Migrations, Exact Money Arithmetic Engine, Verification & Hackathon Delivery.
- Deterministic Financial Engine: Calculated 10,000+ synthetic sales records with zero floating-point discrepancies using native BigInt integer cents.
- True Conversational Correction: Users can revise quantities or prices mid-session without creating phantom records or destroying revision trails.
- Deep AssemblyAI Tool Calling: Voice agent directly drives database aggregation tools and dashboard canvas updates.
- Complete Test Coverage: 65 automated unit, domain, and API integration tests passing in CI/CD.
- Zero AI Slop: Clean, purposeful UI engineered for fast legibility, minimal clutter, and WCAG 2.1 AA accessibility.
EasyLedger is open-source software licensed under the MIT License.
MIT License
Copyright (c) 2026 EasyLedger contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- AssemblyAI for providing real-time Voice Agent infrastructure and sponsoring the hackathon.
- lablab.ai for organizing the global Voice Agent Hackathon challenge.
- Render for cloud hosting services powering the web app, API, and PostgreSQL database.
- Apache ECharts for the declarative, high-performance charting engine.
EasyLedger: Sales, made clear.