Skip to content

ehsanwwe/budgetmate

BranchesTags

Repository files navigation

💰 BudgetMate — بادجت‌میت

Your Personal Persian AI Finance Assistant

دستیار مالی شخصی هوشمند فارسی‌زبان

License Python Node FastAPI Next.js TypeScript TailwindCSS SQLite Status PRs Welcome

Inspired by Cleo AI — but private, local, and Persian-first.

English • فارسی

🌟 Overview

BudgetMate is a privacy-first personal finance app inspired by Cleo AI, built specifically for Persian-speaking users. Unlike Cleo, it never connects to any bank account — you manually enter your budget, track expenses, set savings goals, and chat with an AI advisor that gives money advice in Persian based on your data.

Why BudgetMate?

  • 🔒 100% Privacy — no bank integration, your data stays on your machine
  • 🇮🇷 Persian-first — full RTL UI, Jalali calendar, Persian numerals throughout
  • 🤖 AI-powered — chat with a financial advisor that knows your budget and spending
  • 🔌 Pluggable AI — switch between OpenClaw, Ollama (local), or Anthropic with a single env var
  • 👨‍💼 Built-in admin panel — manage users, view stats, block accounts
  • 📱 Mobile-first responsive design — works beautifully on any screen size

📸 Screenshots

Add your screenshots here

Login Dashboard Chat
Login Dashboard Chat
Transactions Goals Admin Panel
Transactions Goals Admin

✨ Features

For Users

  • 🔐 Phone + OTP login (mock OTP for development: 123456)
  • 📊 Dashboard with budget summary, spending pie chart, and 7-day trend
  • 💸 Transaction tracking with categories, filters, and search
  • 🎯 Savings goals with progress tracking and contributions
  • 💬 AI chat with streaming responses, grounded in your real financial data
  • 📅 Jalali calendar support throughout
  • 🌙 Smooth animations and modern gradient UI

For Admins

  • 📈 Stats dashboard — total users, active users, transaction counts
  • 👥 User management — search, view details, block/unblock
  • 📋 Activity logs — full audit trail of important actions
  • 🔒 Separate admin authentication with its own JWT scope

Technical

  • 🚀 FastAPI backend with auto-generated OpenAPI docs
  • ⚡ Server-Sent Events (SSE) for streaming AI responses
  • 🗄️ SQLAlchemy 2.x + Alembic migrations
  • 🎨 Next.js 14 App Router with React Server Components
  • 💅 shadcn/ui components, fully customized for RTL
  • ✅ Type-safe end-to-end (TypeScript + Pydantic v2)

🏗️ Architecture

┌────────────────────────────────────────────────────────────┐
│                      Next.js 14 Frontend                   │
│  (App Router · TypeScript · Tailwind · shadcn/ui · RTL)    │
└────────────────────────┬───────────────────────────────────┘
                         │ REST + SSE
                         ↓
┌────────────────────────────────────────────────────────────┐
│                       FastAPI Backend                      │
│   (Auth · Budgets · Transactions · Goals · Chat · Admin)   │
└──┬──────────────────────┬──────────────────────────────────┘
   │                      │
   ↓                      ↓
┌─────────┐    ┌─────────────────────────────────┐
│ SQLite  │    │   AI Provider (pluggable)       │
│   DB    │    │  ┌──────────┐  ┌──────────┐    │
└─────────┘    │  │ OpenClaw │  │  Ollama  │    │
               │  └──────────┘  └──────────┘    │
               │  ┌──────────────────────────┐  │
               │  │       Anthropic          │  │
               │  └──────────────────────────┘  │
               └─────────────────────────────────┘

🛠️ Tech Stack

Backend

  • FastAPI 0.115 — modern async Python web framework
  • SQLAlchemy 2.x — ORM with full type support
  • Alembic — database migrations
  • Pydantic v2 — data validation
  • python-jose — JWT authentication
  • bcrypt — password hashing
  • httpx — async HTTP for AI provider calls
  • sse-starlette — Server-Sent Events for streaming

Frontend

  • Next.js 14 (App Router)
  • TypeScript 5
  • TailwindCSS 3.4 (with logical properties for RTL)
  • shadcn/ui — accessible component primitives
  • lucide-react — icon library
  • recharts — charts and data visualization
  • zustand — state management
  • axios — HTTP client
  • react-hook-form + zod — form validation
  • dayjs + jalaliday — Jalali calendar
  • @fontsource/vazirmatn — Persian web font

🚀 Getting Started

Prerequisites

  • Python 3.11 or higher
  • Node.js 20 or higher
  • Git
  • Windows PowerShell or any Unix-like shell

1. Clone the repository

git clone https://github.com/yourusername/budgetmate.git
cd budgetmate

2. Backend setup

cd backend

# Install dependencies (no venv needed)
pip install --user fastapi "uvicorn[standard]" sqlalchemy alembic pydantic "pydantic-settings" "python-jose[cryptography]" "passlib[bcrypt]" bcrypt httpx python-dotenv sse-starlette python-multipart

# Or use requirements.txt
pip install --user -r requirements.txt

Create backend/.env:

OPENCLAW_URL=http://your-openclaw-host:port
OPENCLAW_TOKEN=your_token_here
AI_PROVIDER=openclaw
PRIMARY_MODEL=ollama/gemma4:26b
FALLBACK_MODELS=ollama/qwen3-coder:30b,ollama/qwen3-coder:latest,ollama/gemma3:12b,ollama/qwen3:14b,openai/gpt-4o-mini
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_admin_password
OTP_MOCK_CODE=123456
JWT_SECRET=<generate with: python -c "import secrets; print(secrets.token_hex(32))">
JWT_ALGORITHM=HS256
DATABASE_URL=sqlite:///./budgetmate.db
CORS_ORIGINS=http://localhost:3000

Development SQLite note: backend/budgetmate.db is the canonical local database. Relative SQLite URLs are normalized by the backend config relative to backend/, so starting FastAPI or Alembic from the repo root or from backend/ uses the same DB file. A root-level budgetmate.db may exist from older relative-path runs and should not be deleted unless you explicitly decide to clean it up.

Run migrations and start the server:

alembic upgrade head
python -m uvicorn app.main:app --reload --port 8000

Backend will be available at: http://localhost:8000
API docs: http://localhost:8000/docs

3. Frontend setup

In a new terminal:

cd frontend
npm install

Create frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1

Run the dev server:

npm run dev

Frontend will be available at: http://localhost:3000

4. Login and test

  1. Open http://localhost:3000
  2. Enter any phone number (e.g., 09120000000)
  3. Use OTP code: 123456
  4. You're in! Set a budget, add transactions, chat with the AI.

For the admin panel:

  1. Open http://localhost:3000/admin
  2. Username: admin
  3. Password: (whatever you set in .env)

🔌 Switching AI Providers

BudgetMate supports three AI providers. Change AI_PROVIDER in backend/.env and restart the server:

Option 1: OpenClaw (default)

AI_PROVIDER=openclaw
OPENCLAW_URL=http://your-host:port
OPENCLAW_TOKEN=your_token

Option 2: Local Ollama

Make sure Ollama is running:

ollama serve
ollama pull gemma4:26b

Then:

AI_PROVIDER=ollama
PRIMARY_MODEL=gemma4:26b

Option 3: Anthropic Claude

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
PRIMARY_MODEL=claude-sonnet-4-5

📁 Project Structure

budgetmate/
├── backend/
│   ├── app/
│   │   ├── core/           # config, auth, security, seed
│   │   ├── db.py           # SQLAlchemy Base + engine
│   │   ├── models/         # User, Budget, Transaction, Goal, ...
│   │   ├── schemas/        # Pydantic request/response models
│   │   ├── routers/        # auth, budgets, transactions, chat, admin, ...
│   │   ├── services/
│   │   │   └── ai.py       # AI provider abstraction
│   │   └── main.py         # FastAPI app entry
│   ├── alembic/            # database migrations
│   ├── .env                # backend secrets (gitignored)
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/            # Next.js App Router pages
│   │   ├── components/     # UI components + shadcn/ui
│   │   ├── lib/            # api client, formatters, utils
│   │   └── store/          # zustand stores
│   ├── .env.local          # frontend env (gitignored)
│   └── package.json
├── docker-compose.yml      # one-command full stack
├── CLAUDE.md               # AI agent resume guide
└── README.md

🐳 Docker (optional)

Run the full stack with one command:

docker compose up --build

Backend on :8000, frontend on :3000.

🔧 API Reference

All API endpoints are documented and testable at http://localhost:8000/docs (Swagger UI).

Key endpoints

Method Endpoint Description
POST /api/v1/auth/request-otp Request OTP for a phone number
POST /api/v1/auth/verify-otp Verify OTP and get JWT
POST /api/v1/auth/admin/login Admin login
GET /api/v1/me Current user info
GET /api/v1/budgets/current Get current month budget
GET /api/v1/transactions/summary Spending summary for current month
POST /api/v1/chat/message Send a message to AI
GET /api/v1/chat/stream Stream AI response (SSE)
GET /api/v1/admin/stats Admin dashboard stats

🧪 Testing

# Backend smoke test
cd backend
python -m pytest

# Frontend type check + build
cd frontend
npm run build

🗺️ Roadmap

  • Real SMS OTP integration (Kavenegar, Twilio)
  • Recurring transactions
  • Multi-currency support
  • Budget categories with custom rules
  • Export to CSV / Excel
  • Receipt OCR via vision models
  • Mobile apps (React Native)
  • PostgreSQL support for production
  • Telegram bot integration

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feat/amazing-feature)
  5. Open a Pull Request

For major changes, please open an issue first to discuss what you'd like to change.

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

🌟 معرفی

بادجت‌میت یک اپلیکیشن مدیریت مالی شخصی است که با الهام از Cleo AI ساخته شده، اما با تمرکز کامل بر حریم خصوصی و زبان فارسی. برخلاف Cleo، هیچ‌گاه به حساب بانکی شما متصل نمی‌شود — شما به‌صورت دستی بودجه‌تان را وارد می‌کنید، هزینه‌ها را ثبت می‌کنید، اهداف پس‌انداز تعریف می‌کنید و با دستیار هوشمندی که از داده‌های مالی شما باخبر است، به فارسی گفت‌وگو می‌کنید.

چرا بادجت‌میت؟

  • 🔒 حریم خصوصی کامل — هیچ اتصال بانکی نیست، داده‌ها روی سیستم شما باقی می‌مانند
  • 🇮🇷 فارسی از پایه — رابط راست‌چین کامل، تقویم جلالی، اعداد فارسی
  • 🤖 هوش مصنوعی مالی — مشاوره مبتنی بر بودجه و خرج‌های واقعی شما
  • 🔌 هوش مصنوعی قابل سوئیچ — بین OpenClaw، Ollama (محلی) یا Anthropic
  • 👨‍💼 پنل ادمین داخلی — مدیریت کاربران، آمار، بلاک کردن
  • 📱 طراحی موبایل‌اول — روی هر اندازه صفحه‌ای زیبا است

✨ امکانات

برای کاربر

  • 🔐 ورود با شماره موبایل و کد OTP (کد آزمایشی: ۱۲۳۴۵۶)
  • 📊 داشبورد با خلاصه بودجه، نمودار دایره‌ای و روند ۷ روز اخیر
  • 💸 ثبت و مدیریت تراکنش‌ها با دسته‌بندی، فیلتر و جستجو
  • 🎯 اهداف پس‌انداز با نمودار پیشرفت
  • 💬 گفت‌وگو با هوش مصنوعی، پاسخ‌های جاری (streaming)
  • 📅 پشتیبانی کامل از تقویم جلالی
  • 🌙 انیمیشن‌های نرم و رابط مدرن

برای ادمین

  • 📈 داشبورد آمار — تعداد کاربران، کاربران فعال، تراکنش‌ها
  • 👥 مدیریت کاربران — جستجو، مشاهده جزئیات، بلاک/آنبلاک
  • 📋 لاگ فعالیت‌ها

🚀 راه‌اندازی

پیش‌نیازها

  • Python نسخه ۳.۱۱ یا بالاتر
  • Node.js نسخه ۲۰ یا بالاتر
  • Git

۱. کلون کردن مخزن

git clone https://github.com/yourusername/budgetmate.git
cd budgetmate

۲. راه‌اندازی بک‌اند

cd backend
pip install --user -r requirements.txt

فایل backend/.env را با مقادیر مناسب پر کنید (نمونه در بخش انگلیسی).

alembic upgrade head
python -m uvicorn app.main:app --reload --port 8000

بک‌اند روی http://localhost:8000 در دسترس است.
مستندات API: http://localhost:8000/docs

۳. راه‌اندازی فرانت‌اند

در ترمینال جدید:

cd frontend
npm install

فایل frontend/.env.local بسازید:

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
npm run dev

فرانت‌اند روی http://localhost:3000 در دسترس است.

۴. ورود و تست

۱. به http://localhost:3000 بروید
۲. هر شماره موبایلی را وارد کنید (مثلاً ۰۹۱۲۰۰۰۰۰۰۰)
۳. کد OTP: ۱۲۳۴۵۶
۴. وارد داشبورد می‌شوید!

برای پنل ادمین:

۱. http://localhost:3000/admin
۲. نام کاربری: admin
۳. رمز عبور: (مقداری که در .env تنظیم کردید)

🔌 سوئیچ بین Providerهای هوش مصنوعی

سه provider پشتیبانی می‌شود. متغیر AI_PROVIDER را در backend/.env تغییر دهید و سرور را restart کنید:

  • openclaw (پیش‌فرض) — سرور OpenClaw اختصاصی
  • ollama — Ollama محلی روی localhost:11434
  • anthropic — Claude از Anthropic (نیاز به API key)

🤝 مشارکت

از مشارکت شما استقبال می‌شود! مراحل:

۱. مخزن را Fork کنید
۲. شاخه جدید بسازید (git checkout -b feat/something)
۳. تغییرات را commit کنید
۴. push کنید و Pull Request باز کنید

📜 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است.

Made with ❤️ for Persian users

⭐ Star this repo if you find it useful!

About

Persian-first AI personal finance assistant inspired by Cleo AI — private, local, RTL, with manual budgeting, expense tracking, savings goals, admin panel, and AI financial chat.

Topics

personal-finance sqlite nextjs expense-tracker budgeting rtl persian jalali-calendar tailwindcss ai-assistant ollama finance-ai openclaw

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages