CashTrace - AI Cashflow Copilot for Nigerian SMEs

Inspiration

Running a small business in Nigeria means juggling receipts, bank statements, POS slips, and tax deadlines — often on a low-end Android phone with spotty internet. Most accounting tools are built for Western markets and don't understand Naira formatting, Nigerian bank statement layouts, or FIRS filing deadlines. We wanted to build something that actually speaks the language of Nigerian SMEs.

What it does

CashTrace is an AI-powered cashflow and compliance copilot for Nigerian small businesses. It lets owners:

• Snap a photo of a receipt or upload bank statements (GTBank, Access, Zenith, First Bank, UBA) and POS exports
• Automatically extract and categorize transactions using Gemini AI
• Track cashflow with real-time dashboards showing KPIs, trends, and top expense/revenue breakdowns
• Get AI-generated insights — tax exposure alerts, cashflow risk warnings, cost optimization tips, and NDPR/FIRS compliance reminders
• Work offline on unreliable networks, with automatic sync when back online

Everything is stored in Kobo (integer math) for financial precision, displayed in ₦ with proper formatting, and timestamped in WAT.

How we built it

• Frontend: Next.js 14 (App Router), Tailwind CSS, Zustand for state, PWA with service worker for offline support
• AI Layer: Google Gemini 2.0 Flash/Pro with structured output mode, custom prompts for Nigerian document formats, circuit breaker + exponential backoff for resilience
• Backend: Modular architecture with 13 independent spec-driven modules — auth, document processing, transaction engine, analytics, insights, notifications, and more
• Data: PostgreSQL with full-text search, Redis caching, S3-compatible storage for documents
• Methodology: Spec-driven development with formal correctness properties validated through property-based testing (fast-check)

Challenges we ran into

• Nigerian bank statements have wildly inconsistent PDF formats across banks — getting Gemini to reliably parse all five major banks required extensive prompt engineering and fallback strategies
• Handling financial math without floating point errors meant storing everything in Kobo and converting only at display time
• Designing offline-first UX that queues actions and syncs gracefully on unreliable 2G/3G connections
• Balancing Gemini API costs with extraction quality — we use Flash for simple receipts and Pro for complex multi-page statements

Accomplishments that we're proud of

• 13-module architecture fully specified with 155+ requirements and 179+ correctness properties before writing implementation code
• Circuit breaker pattern that gracefully degrades when Gemini is unavailable instead of failing hard
• Duplicate detection across sources — catches the same transaction appearing on both a receipt and a bank statement
• Nigerian-specific insight engine that understands FIRS deadlines, VAT thresholds, and CAC annual returns

What we learned

• Spec-driven development with property-based testing catches edge cases that unit tests miss — especially around currency math and date boundary handling in WAT timezone
• Gemini's structured output mode is a game-changer for reliable JSON extraction from messy real-world documents
• Building for low-end devices forces better engineering decisions — smaller bundles, skeleton loaders, and offline-first architecture benefit all users

What's next for CashTrace - AI Cashflow Copilot for Nigerian SMEs

• Integration with Nigerian payment gateways (Paystack, Flutterwave) for real-time transaction ingestion
• Multi-language support including Nigerian Pidgin for insight delivery
• Expanding bank format support to cover all Nigerian commercial banks
• WhatsApp bot integration for receipt uploads and quick cashflow checks
• Multi-user access with role-based permissions for businesses with employees

Built With

• fast-check
• google-gemini-api
• nextjs
• node.js
• playwright
• postgresql
• redis
• tailwind-css
• terraform
• typescript
• vitest
• zustand