Budget Analyse

Personal finance management tool for Dutch ING bank statements with AI-powered categorization, budget tracking, and spending insights. Fully bi-lingual (English and Nederlands) Refer to the wiki for more details

v1.2.0 - Transaction Amount Redesign | Changelog

Features

Core Features

• Multi-account support - Track checking and savings accounts separately
• Automatic categorization - Rules-based + AI-powered transaction categorization
• NIBUD integration - Dutch budget institute reference data for comparison
• Multi-tenancy - Isolated data per user with PostgreSQL schema separation
• Internationalization - Dutch and English language support

Budget Management

• Budget Entry - Set yearly budgets per category with NIBUD references
• Budget Overview - Excel-style 12-month grid (budget vs actual)
• Budget Types - Fixed, rolling, flexible, and target budgets
• Rolling balances - Cumulative underspend tracking for savings categories

Dashboard & Insights

• Widget-based dashboard - Customizable with account balances, envelope health, category progress
• Trends analysis - Income vs expenses, category breakdown, merchant analysis
• Spending velocity - Track spending pace through the month
• Alerts - Budget overspend, unusual patterns, missing recurring transactions

Transaction Management

• CSV import - ING and Revolut bank statement formats
• Duplicate detection - Prevent double imports
• Bulk operations - Multi-select categorization
• Rule creation - Create rules directly from transactions
• Tags - Custom tagging for cross-category grouping

AI-First Categorization (v2.0)

• scikit-learn as THE brain - Primary categorization engine, not a fallback
• Weighted learning - Manual (1.0) > Confirm (0.7-0.9) > LLM (0.3-0.5) > Rule (0.2)
• Recency multipliers - Recent corrections count more (7d=1.0, 30d=0.8, 90d=0.6)
• Adaptive LLM thresholds - Mature tenants need less LLM help
• Rule retirement - Rules automatically retire when AI reaches 95% confidence
• Confidence badges - Visual indicators (silent ≥85%, yellow 50-84%, red <50%)
• Learning dashboard - Model status, accuracy trends, retirement candidates
• Privacy-preserving - Local model training, no data shared externally

Tech Stack

Layer	Technology
Backend	Python 3.11+, FastAPI 0.115+, SQLAlchemy 2.0, PostgreSQL 16
Frontend	React 19, TypeScript 5.9, Vite 7, Tailwind CSS, TanStack Query
AI/ML	scikit-learn (categorization), Anthropic Claude (cloud LLM), Ollama (local LLM)
Infrastructure	Docker & Docker Compose

Quick Start

Requirements

• Docker & Docker Compose
• Git

Start Development

# Clone and start
git clone <repo-url>
cd budget_analyse

# Setup environment variables
cp .env.example .env
# Edit .env with your configuration

./start.sh

# Or manually
docker compose up --build

Access Points

Service	URL
Frontend	http://localhost:5193
Superadmin	http://localhost:5194
API	http://localhost:8020
API Docs	http://localhost:8020/docs
Database	localhost:5452

Default Credentials (Demo)

• Email: [email protected]
• Password: demo123

Project Structure

backend/app/
├── main.py              # FastAPI init
├── models.py            # SQLAlchemy models
├── schemas.py           # Pydantic schemas
├── routers/             # 34 API routers
│   ├── accounts.py      # Multi-account management
│   ├── auth.py          # Authentication
│   ├── budgets.py       # Budget management
│   ├── categories.py    # Category management
│   ├── dashboard.py     # Dashboard API
│   ├── ml.py            # AI/ML endpoints
│   ├── transactions.py  # Transaction CRUD
│   └── ...
└── services/            # Business logic
    ├── ai_categorizer.py        # ML categorization
    ├── anthropic_categorizer.py # Anthropic Claude integration
    ├── training_service.py      # Model training
    ├── import_service.py        # CSV import
    └── rule_service.py          # Rule matching

frontend-react/src/
├── pages/               # 31 page components
│   ├── Dashboard.tsx    # Widget-based dashboard
│   ├── BudgetEntry.tsx  # Yearly budget setup
│   ├── BudgetOverview.tsx # 12-month grid
│   ├── Transactions.tsx # Transaction list
│   ├── Trends.tsx       # Spending analysis
│   └── ...
├── components/
│   ├── dashboard/       # Widget system
│   │   ├── widgets/     # Individual widgets
│   │   ├── WidgetRenderer.tsx
│   │   └── WidgetSettings.tsx
│   └── ui/              # Reusable components
├── hooks/               # 36 data fetching hooks
├── locales/             # i18n translations (en, nl)
└── lib/                 # API client, types, utils

Development Commands

# Start/stop services
./start.sh              # Start all services
./start.sh stop         # Stop services
./start.sh rebuild      # Rebuild images
./start.sh logs [service]  # View logs

# Quality checks
./start.sh quality backend    # Ruff, mypy, bandit, pytest
./start.sh quality frontend   # ESLint, TypeScript, Vitest
./start.sh quality all        # Both

# Testing
cd backend && pytest                    # Backend tests
cd frontend-react && npm run test       # Unit tests
cd frontend-react && npm run test:e2e   # Playwright E2E

Documentation

Folder	Audience	Contents
docs/user/	End users	User guide
docs/developer/	Developers	Architecture, development, UX patterns
docs/product/	Product team	Roadmap, requirements
docs/operations/	Ops	Security, Docker setup

See CLAUDE.md for detailed developer documentation.

Version History

Version	Highlights
v1.2.0	Transaction Amount Redesign (Signed amounts, unified calculation service)
v1.1.0	Bug fixes (NaN serialization, session refresh), CSS standards compliance
v1.0.0	Production ready, AI-First architecture v2.0, 100% UAT pass rate
v0.17.0	Quality & fixes, privacy cleanup, E2E test stability
v0.16.0	UAT Panel Review, GDPR compliance tests
v0.15.0	Repository pattern, durable background jobs, accessibility
v0.12.0	Superadmin application, Revolut CSV support
v0.11.0	AI UX polish: Automatisering, Systeem Inzicht, Logboek, Back-up pages
v0.10.0	Anthropic Claude integration, hybrid AI categorization, feedback loop
v0.9.0	Dashboard widget system, dark mode, UX redesign
v0.8.0	Budget Overview, Trends page, category activation dates
v0.7.0	i18n support, AI categorization service
v0.6.0	Multi-tenancy, authentication, NIBUD categories
v0.5.0	Multi-account support, savings hierarchy

See CHANGELOG.md for detailed version history.

License

See License.md for details.

---

• Developed by Remco van Santen - 2026 *
• Completely AMP coded by Claude code and Gemini for auditing *