💰 PyFinFlow

🚀 Personal finance management web app with integrated AI

📱 Demo • 📋 Features • 🛠️ Installation • 📖 Technical Docs • 🤝 Contribute

---

🌟 Why PyFinFlow?

Feature	Description
🎯 Smart	Automatic amount detection (US/EU format)
📊 Visual	Interactive charts with Plotly
🤖 AI	Financial assistant with RAG + multi-provider (Ollama, HuggingFace, Gemini)
💾 Persistent	PostgreSQL (prod) + SQLite (dev) with Repository Pattern
🔒 Secure	bcrypt + JWT + rate limiting + role-based access
🧪 Tested	224 tests passing (unit + integration)
📖 Documented	Full Swagger/ReDoc API documentation
🌍 i18n	Spanish, English
💱 Multi-currency	ARS, USD, EUR, BRL with live conversion

---

📱 Demo

🚀 Live public demo:

Link	URL
🖥️ Web app	https://pyfinflow-ai.vercel.app
🔌 API (Swagger)	https://pyfinflow-api.onrender.com/docs
❤️ Health check	https://pyfinflow-api.onrender.com/health

To try it without signing up: open the app and click "Explore demo" — you instantly get a demo account with sample transactions, budgets and goals (public registration is disabled in the demo).

For local development: http://localhost:3000 (frontend) + http://localhost:8000/docs (API).

---

📸 Screenshots

Desktop - Dashboard	Desktop - New Transaction	Desktop - History

Desktop - Charts	Desktop - Budgets	Mobile

---

┌─────────────────────────────────────────────────────────────┐
│  💰 PyFinFlow                                 [Dashboard]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│   │   INCOME     │  │   EXPENSES   │  │   BALANCE    │    │
│   │  $ 150,000   │  │   $ 45,000   │  │  $ 105,000   │    │
│   └──────────────┘  └──────────────┘  └──────────────┘    │
│                                                             │
│   📈 Expense Trends    |    🍰 By Category                │
│   ┌──────────────────┐      |    ┌──────────────────┐     │
│   │  ▓▓▓▓▓▓░░░░░░    │      │    │   ████░░░░░░    │     │
│   │  ▓▓▓▓▓▓▓▓░░░░    │      │    │   ██████░░░░    │     │
│   └──────────────────┘      |    └──────────────────┘     │
│                                                             │
│   📝 Recent Transactions                                  │
│   ┌─────────────────────────────────────────────────────┐│
│   │ 🟢 Salary          $ 80,000    15/03/2024            ││
│   │ 🔴 Supermarket     $ 15,000    14/03/2024            ││
│   │ 🔴 Transport       $ 5,000     14/03/2024            ││
│   └─────────────────────────────────────────────────────┘│
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

✨ Features

🏠 Core

• ✅ Transaction recording with smart amount detection
• ✅ Dashboard with real-time metrics
• ✅ Currency: Argentine Pesos (ARS)
• ✅ Date filters with validation
• ✅ Interactive Plotly charts with tooltips
• ✅ Pagination in history (1000+ transactions)

💰 Financial Management

• ✅ Monthly budgets per category with visual alerts
• ✅ Savings goals with visual progress
• ✅ In-app alerts when budget exceeded
• ✅ Complete history with search, filters, editing

💾 Data & Sync

• ✅ Local SQLite persistence
• ✅ Backup/Import JSON
• ✅ PDF report export
• ✅ Supabase authentication (optional)
• ✅ Offline mode without account

🏷️ Categories

• ✅ Predefined: Food, Housing, Transport, etc.
• ✅ Custom: Create your own categories

🤖 AI Assistant

• ✅ Floating chat with personalized responses
• ✅ HuggingFace Zephyr for intelligent analysis
• ✅ Local fallback without internet

🎨 UI/UX

• ✅ Responsive design (mobile + desktop)
• ✅ Mobile-first navigation: sidebar lateral en escritorio (≥1024px) y bottom tab bar + header limpio en móvil/tablet (<1024px)
• ✅ Mobile: header simplificado (logo + ajustes) con barra de navegación inferior de 5 destinos (Inicio, Transacciones, Presupuestos, Metas, Chat)
• ✅ Headers de página y filtros que se apilan en pantallas pequeñas (sin desbordes horizontales)
• ✅ Animations micro-interactions
• ✅ Onboarding tutorial
• ✅ Skeleton loaders
• ✅ PWA installable as app

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl + N	New transaction
Ctrl + H	Go to History
Ctrl + D	Go to Dashboard

---

🛠️ Installation

Requirements

• Python 3.12+ / Node 20+
• PostgreSQL 16 (optional, SQLite by default) + pip + npm

Step by step

# 1. Clone
git clone https://github.com/MarceloAdan73/pyfinflow-AI.git
cd pyfinflow-AI

# 2. Backend
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # configure DATABASE_URL, JWT_SECRET, OLLAMA_URL
uvicorn app.api.main:app --reload --port 8000
# Swagger: http://localhost:8000/docs

# 3. Frontend
cd frontend
npm install
npm run dev
# App: http://localhost:3000

# 4. Demo data (optional)
python scripts/seed_demo.py

🚀 Public deploy

Production stack: Backend → Render (FastAPI + PostgreSQL) · Frontend → Vercel (Next.js).

Step 1 — Backend on Render

1. Push to the main branch the files: requirements-prod.txt and render.yaml
2. On Render → New → Blueprint → connect the repo
3. Render automatically provisions the web service + PostgreSQL (uses render.yaml)
4. Copy the service URL, e.g. https://pyfinflow-api.onrender.com
5. Optional — enable cloud AI on Render:
   • In the service, Environment → add HF_TOKEN and/or GEMINI_API_KEY
   • AI_PROVIDER_PRIORITY=huggingface,gemini (already in render.yaml)

Verify: GET https://pyfinflow-api.onrender.com/health and /docs

Step 2 — Frontend on Vercel

1. On Vercel → Add New Project → import frontend/
2. Framework preset: Next.js (Vercel auto-detects it)
3. Environment Variables:

   NEXT_PUBLIC_API_URL=https://pyfinflow-api.onrender.com
   

4. Deploy → you get https://pyfinflow-ai.vercel.app

next.config.ts has a rewrite to localhost:8000 only for local development. In production the frontend calls the backend directly via NEXT_PUBLIC_API_URL, so no config changes are needed for the deploy.

Step 3 — CORS (automatic configuration)

The backend reads CORS_ORIGINS from the environment. render.yaml sets it to https://pyfinflow-ai.vercel.app. If the Vercel URL changes, update that var.

Step 4 — Public test

1. Open the app → click "Explore demo" (public registration is disabled)
2. Create a transaction
3. Check budget alerts
4. Import assets/demo_import.csv
5. Chat with the AI (if you configured cloud keys)

Legacy Streamlit deprecated (not recommended).

---

🏗️ Technical Architecture

pyfinflow-AI/
├── app/
│   ├── api/              # FastAPI + routers (auth, transactions, budgets, goals, ai) + schemas
│   ├── core/             # config, auth (bcrypt/JWT), database (SQLAlchemy), cache, metrics
│   ├── ai/               # RAG, vector_store (ChromaDB), providers (Ollama/HF/Gemini)
│   ├── services/         # budget_alerts, csv_import
│   └── repositories/     # Repository Pattern (postgres_repo, factory)
├── frontend/             # Next.js 16 + React 19 + Tailwind v4 + next-intl (es/en)
├── alembic/              # Migrations (001_initial_schema, 002_chat_messages)
├── tests/unit/           # 224 tests
├── scripts/seed_demo.py  # Demo data (~70 txns, budgets, goals)
├── docker-compose.yml    # app + PostgreSQL + Redis + ChromaDB
├── pyproject.toml        # ruff + pytest
└── ROADMAP_SAAS.md       # Roadmap Phases 0-10

---

📖 Technical Documentation

Tech Stack

Layer	Technology	Version
Backend	FastAPI + SQLAlchemy + Alembic	0.139 / 2.0 / 1.13
Frontend	Next.js + React + Tailwind + next-intl	16.2 / 19 / 4
DB	PostgreSQL 16 (prod) / SQLite (dev)	16
AI	Ollama + ChromaDB + HuggingFace + Gemini	local/cloud
Auth	bcrypt + JWT + rate limiting	12 rounds / 1h access
Cache	Redis (fallback in-memory)	7
Testing	Pytest + Ruff	8 / 0.2

Database Schema

-- Transactions
CREATE TABLE transactions (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    description TEXT,
    date TEXT NOT NULL,
    currency TEXT DEFAULT 'ARS',
    user_id TEXT,
    created_at TEXT
);

-- Budgets
CREATE TABLE budgets (
    id INTEGER PRIMARY KEY,
    user_id TEXT,
    category TEXT NOT NULL,
    limit_amount REAL NOT NULL
);

-- Savings Goals
CREATE TABLE savings_goals (
    id TEXT PRIMARY KEY,
    user_id TEXT,
    name TEXT NOT NULL,
    target REAL NOT NULL,
    saved REAL DEFAULT 0,
    deadline TEXT,
    category TEXT
);

-- Custom Categories
CREATE TABLE custom_categories (
    id INTEGER PRIMARY KEY,
    user_id TEXT,
    type TEXT NOT NULL,
    name TEXT NOT NULL
);

Smart Amount Detection

The app automatically detects formats:

"15000"           → 15000    # Simple
"15000 ARS"       → 15000    # With text
"1.500,50"       → 1500.50  # European
"1500.50"        → 1500.50  # American

AI Assistant API

# Query HuggingFace
response = consultar_ia("How much did I spend on food?", context)

# Local fallback (no internet)
response = consultar_ia_local(question, context)

---

🧪 Testing

# Run all tests
python -m pytest tests/ -v

# With coverage
python -m pytest tests/ -v --cov=app --cov-report=html

# Run specific test file
python -m pytest tests/unit/test_formatters.py -v

Results: 224 tests passing ✅

Module	Tests	Coverage
test_auth.py	18	bcrypt, JWT, rate limiting, roles
test_api.py	34	All REST endpoints (auth, transactions, budgets, goals, metrics, demo login)
test_ai_api.py	10	AI endpoints (chat, history, insights, suggestions, status)
test_ai.py	30	Providers, fallback, analytics, chat memory
test_repositories.py	13	CRUD operations (users, transactions, budgets, goals)
test_formatters.py	22	Number parsing, currency formatting, ID generation
test_vector_store.py	14	ChromaDB indexing, search, deletion
test_rag_engine.py	5	RAG pipeline, message building
test_alerts.py	5	SMTP alerts, critical errors
test_config.py	11	Settings types and defaults
test_cache.py	7	Redis fallback, rate limiting
test_metrics.py	6	Request tracking, Prometheus format
test_budget_alerts.py + test_budget_alerts_api.py	21	Budget alerts 80%/100%
test_csv_import.py + test_csv_import_api.py	18	CSV import (EU/US, ;/, aliases)

---

⚙️ Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL/SQLite connection string	sqlite:///./pyfinflow_dev.db
JWT_SECRET	Secret key for JWT tokens	change-me-in-production
OLLAMA_URL	Ollama server URL	http://localhost:11434
HF_TOKEN	HuggingFace token (optional)	-
GEMINI_API_KEY	Google Gemini key (optional)	-
SMTP_HOST	SMTP server for alerts	-
ALERT_EMAIL_TO	Alert recipient email	-

Seed Demo Data

python scripts/seed_demo.py
# Creates: 2 users (admin/demo), ~70 transactions, budgets, goals
# Login: POST /auth/login → {"username": "demo", "password": "demo123"}

In the public demo, clicking "Explore demo" on the login page creates/logs the demo account automatically (endpoint POST /auth/demo).

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

🔮 Roadmap

• Multi-currency (ARS, USD, EUR, BRL) — Phase 7
• API documentation (Swagger/ReDoc) — Phase 3
• Demo seed data — scripts/seed_demo.py
• 224 tests + Ruff 0 — Phase 4-5
• Budget alerts 80%/100% — Phase 8.1
• CSV import (EU/US, 2MB/1000 rows) — Phase 8.2
• Production deploy (Vercel + Render) — Phase 10
• PWA offline — Phase 8.3
• Excel/PDF export — Phase 8.2

---

🤝 Contribute

# 1. Fork
# 2. Create branch
git checkout -b feature/new-feature

# 3. Commit
git commit -am 'Add new feature'

# 4. Push
git push origin feature/new-feature

# 5. Pull Request

---

📄 License

MIT License - See LICENSE

---

🙏 Acknowledgments

• FastAPI - REST API Framework
• Next.js - Frontend Framework
• SQLAlchemy - ORM
• PostgreSQL - Database
• ChromaDB - Vector Store for RAG
• Ollama - Local AI inference
• HuggingFace - AI Models
• Tailwind CSS - Styling
• Shadcn/UI - UI Components

---

⭐ If you like the project, give it a star!

Made with ❤️ by PyFinFlow Team