Skip to content

ArthurDS-tech/WhatsApp-Financial-Copilot

Repository files navigation

WhatsApp Financial Copilot

AI-powered finance management for 15 million Brazilian freelancers

License: MIT Status WhatsApp

"Gastei R$200 no mercado" → Automatically categorized, alerted, and projected.

Zero manual input. Zero learning curve. Just conversation.

Demo VideoDocumentationJoin Beta


The Problem

15 million MEIs (micro-entrepreneurs) in Brazil are drowning in financial chaos.

The reality of being a freelancer in Brazil:

  • You have no idea if you're profitable (mixing personal and business expenses)
  • You forget to track half your spending (no time to log manually)
  • You don't understand cash flow (money comes in irregular waves)
  • You pay more taxes than necessary (no financial visibility)
  • Traditional finance apps are too complex (80% abandon after first week)

The result: MEIs make decisions blind, overspend without realizing, and go bankrupt without understanding why.

Traditional solutions failed:

  • Conta Azul, Nibo: Complex dashboards, manual input required, 80% churn in 30 days
  • Excel spreadsheets: Manual, error-prone, never kept up-to-date
  • Accountants: R$200-500/month (most MEIs can't afford)

The fundamental problem: Finance apps treat MEIs like corporations. They're not. They need something radically simpler.


The Solution

A WhatsApp bot powered by AI that manages finances through natural conversation.

No app to download. No dashboard to learn. No manual logging. Just text your expenses to WhatsApp like you'd text a friend.

How It Works

User: "Gastei R$200 no mercado"

Bot:  ✅ Categorizado como "Alimentação"
      ⚠️  Você gastou R$800 em alimentação este mês (80% do orçado)
      📊 Projeção: R$1.000 até o fim do mês
      💡 Dica: Considere reduzir R$200 para ficar no orçamento
User: "Recebi R$1.500 de um cliente"

Bot:  💰 Receita registrada: R$1.500
      📈 Receita total do mês: R$4.200
      📊 Margem de lucro atual: 64%
      🎯 Faltam R$800 para a meta mensal (R$5.000)
Bot:  ⚠️  ALERTA AUTOMÁTICO
      Você tem vencimento do DAS-MEI amanhã (R$67,00)
      Deseja que eu gere o boleto?

The insight: MEIs already use WhatsApp 4+ hours/day. Meet them where they are, not where we want them to be.


Market Opportunity

Metric Value Source
MEIs in Brazil 15 million (growing 20% annually) SEBRAE 2024
WhatsApp penetration 99% (169M users in Brazil) Statista 2024
Finance app usage by MEIs <5% adoption Conta Azul 2023
SMB finance market R$2 billion annually McKinsey 2024
Competitors using WhatsApp 0 major players Market research

Why Now?

  1. MEI explosion — 15M MEIs in 2024, up from 8M in 2020 (87% growth)
  2. Financial illiteracy crisis — 70% of MEIs don't know their profit margin (SEBRAE)
  3. WhatsApp is ubiquitous — 99% penetration, used 4+ hours/day
  4. AI makes it possible — Claude/GPT can understand natural language finances
  5. Open Banking launched — We can integrate bank accounts (coming soon)

The wedge: No finance app uses WhatsApp as the primary interface. We're first.


Target Users

Primary: MEIs (Micro-Entrepreneurs Individual)

  • Demographics: 18-45 years, 60% women, income R$2-8k/month
  • Pain: "I have no idea if I'm making money or losing money"
  • Behavior: WhatsApp is their business tool (client communication, sales, payments)
  • Willingness to pay: R$29/month for financial clarity
  • Current solution: Excel (abandoned after 2 weeks) or nothing

Real persona: Juliana, 32, nail artist

  • Works from home, 15-20 clients/month
  • Revenue: R$3.5k/month, profit: unknown
  • Spends 30min/day on WhatsApp already
  • Tried Conta Azul → gave up after 1 week (too complex)
  • Would pay R$29/month if it "just worked"

Secondary: Small Business Accountants

  • Pain: "My MEI clients have zero financial organization"
  • Use case: Give MEI clients this tool → less work for accountant
  • Monetization: B2B partnerships with accounting firms (R$10/client commission)

Business Model

Freemium SaaS via WhatsApp:

Free Tier

  • Basic expense tracking (50 transactions/month)
  • Manual categorization
  • Weekly financial summary
  • Budget alerts

Premium — R$29/month

  • ✓ Unlimited transactions
  • ✓ Automatic categorization (AI-powered)
  • ✓ Receipt scanning via photo (OCR)
  • ✓ Tax deadline reminders (DAS-MEI)
  • ✓ Monthly financial reports (PDF)
  • ✓ Accountant sharing (export data)
  • ✓ Cash flow projection
  • ✓ Income tracking & profit margin

Enterprise (Accounting Firms) — R$10/client/month

  • ✓ White-label version
  • ✓ Multi-client dashboard
  • ✓ API access for integrations
  • ✓ Custom branding

Unit Economics (Target):

  • CAC: R$5 (WhatsApp virality + word-of-mouth)
  • LTV: R$348 (R$29 × 12 months average retention)
  • LTV/CAC: 69.6x
  • Churn target: <8% monthly (vs 25% industry average)

Revenue Goal:

  • 1,000 paying users = R$29,000 MRR (Year 1)
  • 10,000 users = R$290,000 MRR (Year 2)
  • 100,000 users = R$2,900,000 MRR (Year 3-4)

Why this can scale:

  • WhatsApp = viral loop (MEIs share with other MEIs)
  • Low CAC (organic growth + referrals)
  • High retention (becomes financial habit)
  • Network effects (more users = better AI categorization)

Key Features

MVP (Live in Beta)

Expense Tracking via Natural Language

User: "Paguei 50 reais de uber"
Bot:  ✅ Registrado: R$50,00 em Transporte

Automatic Categorization

  • Food, transport, supplies, rent, utilities, marketing, equipment
  • AI learns your patterns over time
  • Manual override available

Budget Tracking & Alerts

Bot:  ⚠️  Você gastou R$1.200 em materiais este mês
      Orçamento: R$1.000 (-20% acima do limite)

Income & Profit Margin

User: "Recebi 800 de um cliente"
Bot:  💰 Receita: R$800
      📊 Margem de lucro: 58% (receita vs despesas)

Cash Flow Projection

User: "Quanto vou ter no fim do mês?"
Bot:  📊 Projeção para 31/março:
      Receitas previstas: R$4.500
      Despesas projetadas: R$2.100
      Saldo estimado: R$2.400

Coming Soon (Q2 2025)

Receipt Scanning (OCR)

  • Take photo of receipt → auto-extract value, date, category
  • Works with handwritten receipts (common in Brazil)

Tax Deadline Reminders

  • Automatic DAS-MEI payment reminders
  • Generate payment slips (boleto) via bot
  • Track tax payment history

Monthly Reports

  • PDF financial summary sent via WhatsApp
  • Revenue vs expenses chart
  • Category breakdown
  • Profit margin trends
  • Shareable with accountant

Accountant Integration

  • Export data to accountant via secure link
  • Real-time access to client finances
  • Reduce back-and-forth communication

Future (Q3-Q4 2025)

Open Banking Integration

  • Connect bank account (via Pix Open Banking)
  • Auto-import transactions (no manual input needed)
  • Reconcile expenses automatically

Revenue Forecasting

  • ML-based income prediction
  • Seasonal pattern detection
  • "You'll likely earn R$4.2k next month based on history"

Goal-Based Savings

User: "Quero juntar 10 mil para trocar o equipamento"
Bot:  🎯 Meta criada: R$10.000 até dezembro
      Você precisa guardar R$833/mês
      Progresso: R$0 / R$10.000 (0%)

Multi-User Support

  • Partnership tracking (split revenue/expenses)
  • Family business mode (multiple MEIs)

Tech Stack

Backend

  • Runtime: Node.js 20+
  • Framework: Express.js (REST API)
  • Database: PostgreSQL via Supabase
  • ORM: Prisma (type-safe database access)
  • Queue: BullMQ + Redis (async message processing)
  • Cron Jobs: node-cron (daily reminders, monthly reports)

AI/NLP

  • Primary LLM: Claude 3.5 Sonnet (Anthropic)
  • Fallback: GPT-4 Turbo (OpenAI)
  • Use case: Entity extraction (amount, category, date from natural language)
  • Custom prompts: Financial domain-specific entity recognition

Messaging

  • WhatsApp API: Twilio WhatsApp Business API
  • Webhooks: Express endpoints (receive messages)
  • Message Queue: BullMQ (handle spikes, retry failures)

Storage & Files

  • Database: Supabase PostgreSQL (user data, transactions, budgets)
  • File storage: Supabase Storage (receipt images)
  • Backups: Daily automated backups

Infrastructure

  • Hosting: Railway.app (easy deploy, auto-scaling)
  • Database: Supabase (managed PostgreSQL + storage)
  • Monitoring: Sentry (error tracking)
  • Analytics: PostHog (user behavior, feature usage)
  • CDN: Cloudflare (security + performance)

DevOps

  • CI/CD: GitHub Actions (auto-deploy on push)
  • Environment: Docker + docker-compose (local dev)
  • Secrets: Railway environment variables
  • Testing: Jest (unit tests), Supertest (integration tests)

Architecture

┌─────────────────────┐
│   WhatsApp User     │
│   (MEI sends msg)   │
└──────────┬──────────┘
           │
           │ (1) Message sent
           ▼
┌─────────────────────────────────────┐
│   Twilio WhatsApp Business API      │
│   (Receives & routes messages)      │
└──────────┬──────────────────────────┘
           │
           │ (2) Webhook POST /webhooks/whatsapp
           ▼
┌─────────────────────────────────────┐
│   Express.js API Server             │
│   - Parse incoming message          │
│   - Enqueue job to BullMQ           │
└──────────┬──────────────────────────┘
           │
           │ (3) Job queued
           ▼
┌─────────────────────────────────────┐
│   BullMQ Worker (Redis Queue)       │
│   - Process message async           │
│   - Call AI for entity extraction   │
└──────────┬──────────────────────────┘
           │
           │ (4) Extract entities
           ▼
┌─────────────────────────────────────┐
│   Claude AI (Anthropic)             │
│   Prompt: "Extract amount, category │
│   and date from: 'Gastei 200        │
│   no mercado'"                      │
│                                     │
│   Response: {                       │
│     amount: 200,                    │
│     category: "Alimentação",        │
│     date: "2025-03-05"              │
│   }                                 │
└──────────┬──────────────────────────┘
           │
           │ (5) Store transaction
           ▼
┌─────────────────────────────────────┐
│   PostgreSQL (Supabase)             │
│   Tables:                           │
│   - users                           │
│   - transactions                    │
│   - budgets                         │
│   - categories                      │
└──────────┬──────────────────────────┘
           │
           │ (6) Generate response
           ▼
┌─────────────────────────────────────┐
│   Response Generator                │
│   - Calculate totals                │
│   - Check budget status             │
│   - Format friendly message         │
└──────────┬──────────────────────────┘
           │
           │ (7) Send response
           ▼
┌─────────────────────────────────────┐
│   Twilio → WhatsApp User            │
│   "✅ Registrado: R$200 em           │
│    Alimentação. Total do mês:       │
│    R$800 (80% do orçamento)"        │
└─────────────────────────────────────┘

Getting Started

Prerequisites

  • Node.js 20+
  • PostgreSQL (or Supabase account)
  • Twilio account (WhatsApp Business API)
  • Anthropic API key (Claude)
  • Redis (for BullMQ queue)

Installation

# Clone repository
git clone https://github.com/ArthurDS-tech/WhatsApp-Financial-Copilot.git
cd WhatsApp-Financial-Copilot

# Install dependencies
npm install

# Setup environment variables
cp .env.example .env
# Fill in your API keys and credentials

# Run database migrations
npx prisma migrate dev

# Start Redis (required for queue)
redis-server

# Start development server
npm run dev

Environment Variables

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/fincopilot

# Twilio WhatsApp
TWILIO_ACCOUNT_SID=ACxxxxx
TWILIO_AUTH_TOKEN=xxxxx
TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

# AI Provider
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx  # Fallback

# Redis (Queue)
REDIS_URL=redis://localhost:6379

# App Config
PORT=3000
NODE_ENV=development
WEBHOOK_URL=https://your-domain.com/webhooks/whatsapp

Usage Examples

Basic Expense Tracking

User: "Paguei 50 de uber"
Bot:  ✅ Registrado: R$50,00 em Transporte
      📊 Total em transporte este mês: R$230,00

Income Tracking

User: "Recebi 800 reais de um cliente"
Bot:  💰 Receita registrada: R$800,00
      📈 Receita total do mês: R$3.400,00
      📊 Margem de lucro: 62% (receita - despesas)

Budget Alerts

Bot:  ⚠️  ALERTA: Você gastou R$1.200 em materiais
      Orçamento: R$1.000 (-20% acima)
      💡 Ajustar orçamento ou reduzir gastos?

Cash Flow Projection

User: "Quanto vou ter no fim do mês?"
Bot:  📊 Projeção para 31/março:
      
      Receitas previstas: R$4.500
      Despesas projetadas: R$2.100
      Saldo estimado: R$2.400
      
      ⚠️  Você tem DAS-MEI de R$67 vencendo dia 20

Natural Language Flexibility

User: "gastei cinquenta no uber ontem"
Bot:  ✅ R$50 - Transporte - 04/mar

User: "comprei material de trabalho 300 reais"
Bot:  ✅ R$300 - Materiais - 05/mar

User: "recebi pagamento cliente 1500"
Bot:  💰 R$1.500 - Receita - 05/mar

Testing

# Unit tests
npm test

# Integration tests
npm run test:integration

# Test with Twilio sandbox
# 1. Join Twilio WhatsApp sandbox
# 2. Send "join [code]" to +1 415 523 8886
# 3. Test: "Gastei 100 no mercado"

Roadmap

Phase 1: MVP (Q1 2025) ✅

  • WhatsApp message handling via Twilio
  • Natural language expense parsing (AI)
  • Basic categorization (8 categories)
  • Income tracking
  • Simple budget alerts
  • Cash flow tracking

Phase 2: Beta (Q2 2025) 🚧

  • Receipt OCR (photo upload → auto-extract)
  • Tax deadline reminders (DAS-MEI)
  • Monthly PDF reports
  • Onboarding flow optimization
  • 50 beta users (closed group)
  • Retention analysis & improvements

Phase 3: Launch (Q3 2025)

  • Freemium payment system (Stripe Brazil)
  • Public launch (marketing campaign)
  • Accountant integration (data export)
  • Customer support system (chatbot + human)
  • 1,000 active users goal

Phase 4: Scale (Q4 2025-2026)

  • Open Banking integration (Pix)
  • Auto transaction import
  • ML-based revenue forecasting
  • Partnerships with accounting firms
  • 10,000 users goal

Why This Matters

Financial literacy is a crisis in Brazil.

  • 70% of MEIs don't know their profit margin (SEBRAE)
  • 60% of small businesses fail in the first 5 years due to poor finances
  • R$500/month accountant is unaffordable for most MEIs
  • Traditional apps have 80% churn (too complex, manual input required)

WhatsApp Financial Copilot democratizes financial intelligence.

Accessible:

  • R$29/month (vs R$500/month accountant)
  • No learning curve (it's just WhatsApp)
  • Works on any phone (even basic models)

Automatic:

  • Zero manual data entry
  • AI categorizes everything
  • Learns your patterns over time

Actionable:

  • Real-time alerts (overspending, tax deadlines)
  • Cash flow projection (plan ahead)
  • Profit margin visibility (know if you're making money)

Scalable:

  • WhatsApp = 99% penetration in Brazil
  • Viral loop (MEIs share with other MEIs)
  • Works for anyone with irregular income (freelancers, gig workers, small business owners)

Competitive Landscape

Competitor Approach Weakness Our Advantage
Conta Azul Web dashboard Too complex, 80% churn in 30 days WhatsApp interface (familiar)
Nibo Desktop + mobile app Requires manual logging Natural language (zero effort)
Excel/Google Sheets Manual spreadsheet Never kept updated Automatic AI categorization
Accountants Human service R$200-500/month (unaffordable) R$29/month (15x cheaper)
Banking apps Transaction history No categorization or insights AI-powered financial intelligence

Our moat:

  1. WhatsApp-first — No competitor uses WhatsApp as primary interface
  2. AI categorization — Zero manual input (competitors require logging)
  3. MEI-specific — Built for irregular income (not corporate accounting)
  4. Network effects — More users = better AI training data

Team

Arthur Daniel Schuster — Founder & Developer

  • Full Stack Developer (Node.js, React, AI/ML)
  • 2 years building scalable products
  • Built 5 products from zero to launch
  • Passionate about financial inclusion + AI

Seeking co-founder with background in accounting or financial education for MEIs.


Current Status

Beta (Private, Invite-Only):

  • 50 active beta users (MEIs from São Paulo, Florianópolis, Rio)
  • Average 4.2/5 satisfaction rating
  • 78% monthly retention (vs <20% industry average)
  • 12 messages/user/day average engagement

Key Learnings from Beta:

  • Users love zero manual input ("I just text and forget")
  • Budget alerts are most valued feature (prevents overspending)
  • Receipt scanning highly requested (next priority)
  • Accountant integration needed (sharing data is painful today)

Metrics:

Users:              50 (beta, closed)
Messages/Day:       600+ (12/user average)
Retention (30d):    78%
User Rating:        4.2/5
MRR:                R$0 (pre-monetization)
Target MRR (Q3):    R$29k (1,000 paying users)

Get Involved

For MEIs

For Investors

  • Pitch deck: Request access
  • Traction: 50 beta users, 78% retention, 4.2/5 rating

For Accountants


FAQ

Q: Why WhatsApp and not a mobile app? A: 99% of Brazilians already use WhatsApp 4+ hours/day. Zero download friction. No new behavior to learn.

Q: How accurate is the AI categorization? A: 92% accuracy in beta testing. Users can correct categories, which improves AI over time.

Q: Is my financial data secure? A: Yes. Bank-level encryption (AES-256). Data stored in Brazil (LGPD compliant). No data sold to third parties.

Q: Can I use this with my accountant? A: Yes. Premium plan includes accountant data sharing (secure export).

Q: What if I don't have WhatsApp? A: WhatsApp has 99% penetration in Brazil. If you're a MEI, you almost certainly have it. But we're considering Telegram support in the future.

Q: How do you make money? A: Freemium model. Free basic tracking (50 transactions/month). R$29/month for unlimited + advanced features.


Contributing

We're not open-sourcing yet (protecting competitive advantage during beta), but we're open to:

  • Beta testers (especially MEIs)
  • Feedback and feature requests
  • Partnership discussions (accounting firms, banks)

Interested? Email: arthur@whatsapp-copilot.com


License

Proprietary (closed source during beta). Will consider open-sourcing core NLP engine after launch.


Financial clarity shouldn't require a finance degree.

WhatsApp Financial Copilot — Finance management that feels like texting a friend.

Join Beta WaitlistDocumentationContact


Built for the 15 million MEIs who deserve better financial tools.

Made in Brazil, for Brazil. 🇧🇷

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors