VuliLedger

An AI-powered voice ledger and receipt OCR engine built with Riverpod 3.x to simplify automated transaction management seamlessly on web and mobile platforms.

Comment

VuliLedger

Your Business, Spoken & Scanned

Unlocking financial clarity for Africa's informal traders through human-centered generative AI.

The Inspiration

Historically, financial invisibility has limited small-scale commerce across Africa's developing markets. In active commercial trading hubs across Thika and Nairobi, micro-vendors handle substantial daily volume but lack the structured documentation needed to prove profitability.

The Cycle of Cash Invisibility

│ The Cycle of Cash Invisibility │ │ No Written Records ──► Cannot Prove Profitability │ │ Trapped from Scaling ◄── Denied Banking & Loans │

The Story of Mama Njeri

Mama Njeri is a tomato vendor who manages a rapid 10kg inventory daily. Because she tracks calculations mentally or on scattered paper scraps, structural cash flow leakages go unnoticed. More importantly, without verifiable accounting transactions, she cannot:

  • Secure bank micro-loans
  • Accurately project upcoming wholesale inventory purchases
  • Scale her storefront She remains locked out of the formal economy. Our development focus "Building Human-Centered, Joy-Driven Solutions Using AI and Low-Code Tools"** inspired the creation of VuliLedger. Derived from the Swahili word "Vuli" (meaning to open or unlock), the platform bridges the gap between high-barrier ledger software and traditional spoken interaction to bring immediate cash flow clarity to underserved business owners. --- ## Core Features ### 1. Voice-to-Ledger Traders record incoming or outgoing cash using their voice in natural language. The internal pipeline structures unmapped sentences directly into valid database models with zero form filling or manual text inputs. User Input: > "Sold 2kg of tomatoes for 200 shillings." Structured Output Engine: json { "type": "income", "item": "tomatoes", "quantity": "2kg", "amount": 200, "currency": "KES", "timestamp": "2026-06-05T14:30:00Z" } --- ### 2. Photo-to-Text Receipt Scanning Wrinkled, handwritten, or blurry supplier receipts are instantly captured and mapped. The vision parsing engine reads distorted lines to extract structural expense indices natively. Structured Output Engine: json { "merchant": "Mama Oti Market", "date": "2026-06-05", "total": 150, "items": ["packaging"], "currency": "KES" } --- ### 3. Visual Financial Health Dashboard A minimalist, glance-able screen custom-tailored for non-technical operators. Today's Profit: +450 KES ✓ Weekly Profit: +2,340 KES ✓ Top Contributor: Tomatoes (40% of Volume) High-contrast, color-coded components allow low-literacy users to evaluate business health at a glance. --- ### 4. Offline Resilience Engineered for volatile network environments. Transactions execute locally on-device instantly without latency. The system queues data points and handles cloud background database synchronization silently once web connectivity is restored. --- ## System Architecture & Technology Stack VuliLedger is engineered with a modular, cost-efficient framework built to run smoothly on constrained local development hardware. ### Data Flow Architecture

│ VuliLedger Data Flow │

│ Voice / Camera Input ──► Gemini 3 Flash API │

│ Firebase Local Cache ◄── Structured JSON Model │

│ ▼ (Auto-Sync when Online) │ │ Firebase Realtime Cloud Database │

Complete Technology Matrix

| Layer | Component | Selection Rationale | | Frontend Platform | Flutter 3.24+ & Dart | Deploys a unified reactive binary to Web, Android, and Desktop targets | | State Management | Riverpod 3.x (Notifiers) | Provides clean separation of UI from asynchronous background business logic | | Cloud Database | Firebase Realtime DB | Native local caching capabilities for reliable offline operational security | | Natural Language AI | Gemini API (Intent) | High-accuracy inference modeling to extract JSON from spoken Swahili/English | | Computer Vision AI | Gemini 3 Flash Vision | Contextual parsing that interprets handwritten text better than traditional OCR |

| Local Encryption | flutter_secure_storage | Protects cached historical financial transactions directly on-device |

Financial Model Engine Verification

To eliminate the risk of precision errors common in floating-point math during ledger compilation, net yields are calculated across localized streams using transaction type folding metrics: $$\text{Profit}{\Delta} = \sum{i \in \text{Income}} \text{Amount}i - \sum{j \in \text{Expense}} \text{Amount}_j$$

double calculateDailyProfit(List<Transaction> transactions, DateTime date) {
  return transactions
    .where((t) => t.date == date && t.type == 'income')
    .fold(0, (sum, t) => sum + t.amount) -
    transactions
    .where((t) => t.date == date && t.type == 'expense')
    .fold(0, (sum, t) => sum + t.amount);
}

Challenges Faced & Engineering Solutions

Challenge 1: Textual Number Interpretation in Voice Parsing

The Problem: Spoken inputs like "two hundred shillings" caused standard intent models to return an empty field or a null value for the transaction amount. The Solution: We enhanced the AI prompt configuration to strictly parse textual words into numerical integer tokens:

String enhancedPrompt = '''
Extract transaction details from: '{voice_text}'
Handle both numeric and spoken numbers (e.g., "200" OR "two hundred" → 200).
Return ONLY JSON: {type: 'income'|'expense', item: string, amount: number, currency: 'KES'}
''';

Challenge 2: Multi-Device Offline Sync Overwrites

The Problem: Logging transactions across multiple offline devices created ledger conflicts and data synchronization gaps during reconnect loops. The Solution: We introduced explicit UI sync states to provide immediate clarity to the user. Transactions are flagged with visual indicators:

if (transaction.syncStatus == 'pending') {
  return Icon(Icons.cloud_off, color: Colors.orange); // Stored locally
} else {
  return Icon(Icons.cloud_done, color: Colors.green);  // Secured in Cloud
}

Challenge 3: Hardware RAM Constraints During Development

The Problem: Building the full cross-platform target application on an 8GB RAM local workstation led to compile-time resource exhaustion and lag. The Solution: We bypassed local IDE bottleneck structures by running lightweight, optimized CLI production build commands:

flutter build apk --no-sound-dart-defines --split-per-abi

Impact & Vision

Immediate Benefits

| Benefit | Description | | Financial Footprints | Moves informal merchants from cash invisibility to continuous, verifiable transaction logging | | Business Strategy | Empowers non-technical operators to audit operational performance and plan inventory changes using real data | | Banking Access | Builds a clear financial track record, allowing traders to qualify for micro-loans and credit systems |

Future Roadmap

│ PHASE 1 │ -> │ PHASE 2 │ -> │ PHASE 3 │ │ - 12-Hour Core Framework │ │ - Native M-Pesa Tracking │ │ - AI Credit Score Engine │ │ - Voice & Vision OCR │ │ - Full Swahili Localization│ │ - Micro-Loan Marketplace │

Final Thought

VuliLedger proves that advanced artificial intelligence does not have to be complicated. By replacing tedious accounting software with an intuitive voice and camera interface, we remove technical barriers to give informal traders the financial inclusion and clarity they deserve.

Project Resources

Built With

  • 3.24+riverpod
  • api
  • charts-flutter
  • coupled-with-a-local-encryption-security-layer-powered-by-flutter-secure-storage.-the-core-data-infrastructure-is-driven-by-an-offline-first-architecture-using-the-firebase-realtime-database
  • dart
  • financial-data-metrics-are-rendered-into-simple
  • firebase
  • flutter
  • flutter-secure-storage
  • gemini
  • gemini-3-flash-vision
  • github
  • glanceable-dashboards-using-the-charts-flutter-package
  • image-picker
  • responsive-interface-across-android-and-web-platforms.-to-handle-the-application's-reactive-features-and-asynchronous-business-logic
  • speech-to-text
  • vuliledger-connects-to-the-google-gemini-api-to-handle-dual-multimodal-tasks:-the-standard-gemini-text-model-extracts-structured-json-payloads-from-unstructured-audio-text-captured-by-the-speech-to-text-hardware-package
  • we-integrated-riverpod-3.x-for-modern-state-management
  • which-provides-native-on-device-disk-caching-that-automatically-syncs-with-google-cloud-once-a-network-connection-is-established.-for-its-artificial-intelligence-components
  • while-gemini-3-flash-vision-processes-image-streams-from-the-image-picker-package-to-effortlessly-read-context-from-blurry-or-handwritten-receipts.-finally
Share this project:

Updates