A sophisticated web application for importing bank statements, intelligent transaction categorization, and comprehensive financial analytics. Built with AI-powered vendor intelligence and a modern, responsive interface.
- Smart Vendor Detection: Advanced pattern matching extracts clean vendor names from messy bank descriptions
- Smart Rules Engine: Create custom rules for automatic transaction categorization and vendor assignment
- Intelligent Learning: System learns from your corrections and applies them retroactively
- Auto-Categorization: AI categorizes transactions based on vendor patterns and user-defined rules
- Confidence Scoring: 3-tier confidence system (High/Medium/Low) for vendor accuracy
- Interactive Dashboard: Real-time charts with Chart.js showing spending trends and category breakdowns
- Monthly Comparisons: Track spending patterns across months with percentage changes
- Weekly Analysis: Discover spending patterns by day of the week
- Top Vendors: Identify your biggest expenses with detailed vendor analytics
- Budget Intelligence: Smart budget status indicators (On Track/Approaching Limit/Over Budget)
- Monthly Budget Tracking: Set and monitor budgets for each category with visual progress indicators
- Real-time Budget Status: Color-coded progress bars (green/amber/red) showing budget utilization
- Smart Alerts: Dashboard notifications for categories approaching limits or over budget
- Interactive Budget Setting: Modal-based budget creation and editing with validation
- Budget Analytics: Track budget adherence over time with variance analysis
- Intelligent Date Handling: Budget calculations use latest month with data vs. current calendar month
- Smart Rules System: Create conditional rules for automatic transaction processing
- Bulk Operations: Select and approve multiple vendors at once
- Inline Editing: Edit transaction details directly in tables without page refreshes
- Collapsible Views: Expand vendor rows to see all related transactions
- Smart Merging: Merge duplicate vendors with automatic transaction consolidation
- Real-time Updates: All changes apply immediately across the system
- Intelligent Processing: Upload → AI Analysis → Smart Review → Automatic Import
- Duplicate Detection: Automatic detection and handling of duplicate transactions
- Vendor Management: Comprehensive vendor approval and editing system
- CSV Import/Export: Backup and restore vendor configurations
- Dark/Light Theme: Automatic theme detection with theme-aware charts
- Responsive Design: Perfect experience on desktop, tablet, and mobile
- Smooth Animations: Subtle hover effects and transitions throughout
- Accessibility: High contrast colors and keyboard navigation support
- Current month financial overview with spending vs income
- Interactive 6-month spending trend chart
- Category breakdown donut chart with hover percentages
- Budget Overview: Real-time budget progress with overall status and alerts
- Categories Needing Attention: Automatic alerts for over-budget and approaching-limit categories
- Top vendors, weekly patterns, and recent activity widgets
- Quick action buttons for common tasks
- Comprehensive transaction list with advanced filtering
- Inline editing with real-time validation
- Top Vendors Analysis: Category-specific vendor insights with spending breakdowns
- Time-Period Filtering: Top vendors respect selected month/date range for accuracy
- Category and vendor management
- Bulk selection and editing capabilities
- Smart search and pagination
- Interactive Budget Setting: Modal-based budget creation with validation
- Visual Progress Tracking: Color-coded progress bars showing budget utilization
- Monthly Focus: Current month spending vs. all-time totals for clarity
- Budget Status Indicators: Real-time status (on track, approaching limit, over budget)
- Smart Data Display: Current month transaction counts and averages
- AI-powered vendor approval system
- Confidence-based prioritization (review high-confidence first)
- Bulk approval with intelligence insights
- Vendor merging and deduplication tools
- Retroactive transaction healing
- Monthly spending comparisons with trend analysis
- Category spending evolution over time
- Weekly spending patterns and insights
- Top vendors analysis with transaction details
- Transaction type evolution tracking
- Drag-and-drop PDF upload with progress indicators
- Intelligent duplicate detection and handling
- AI-powered vendor classification during import
- Real-time processing feedback with confidence scores
- Framework: Python 3.8+ with Flask
- Database: SQLite with optimized schemas and indexes
- PDF Processing: Advanced pdfplumber integration with intelligent text extraction
- AI Engine: Custom vendor intelligence system with pattern learning
- Architecture: Repository pattern with service layer separation
- Charts: Chart.js for interactive, responsive visualizations
- Styling: Modern CSS with CSS Grid, Flexbox, and CSS Variables
- JavaScript: Modular ES6+ with separated concerns (API, UI, Tables managers)
- Responsiveness: Mobile-first design with progressive enhancement
- Themes: Dynamic dark/light theme support with CSS custom properties
- Repositories: Clean data access layer (Transaction, Vendor, Category)
- Services: Business logic separation (Filtering, Navigation, Pagination)
- Intelligence Engine: AI-powered vendor detection and learning
- Import Pipeline: Multi-stage processing with validation and enhancement
- Python 3.8 or higher
- pip (Python package manager)
- Modern web browser (Chrome, Firefox, Safari, Edge)
-
Clone and Setup
git clone https://github.com/paucotan/fern-finance.git cd fern-finance python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate
-
Install Dependencies
pip install -r requirements.txt
-
Run Application
python app.py
-
Access Dashboard
http://localhost:8080
- Upload First Statement: Use the upload page to import your first PDF
- Review AI Suggestions: Check vendor classifications and approve high-confidence matches
- Set Up Budgets: Visit categories page to set monthly budgets for your spending categories
- Fine-tune Vendors: Use the vendor management hub to merge duplicates and clean up names
- Explore Analytics: Check your dashboard for spending insights, budget progress, and trends
- Upload New Statements: Drag-and-drop your latest bank PDFs
- Quick Review: Focus on low-confidence vendors that need attention
- Monitor Budget Alerts: Check dashboard for categories approaching or exceeding limits
- Bulk Approve: Use confidence-based selection for efficient processing
- Track Progress: Monitor spending trends and budget adherence on your dashboard
- Smart Rules: Create conditional rules (if description contains X, then set category Y) for automated processing
- Vendor Intelligence: Teach the system by correcting vendor names - it learns and applies changes retroactively
- Budget Analytics: Track budget performance over time with variance analysis and historical trends
- Category Insights: View top vendors per category with time-period specific analysis
- Bulk Operations: Use checkbox selection for mass vendor approval and editing
- Smart Merging: Consolidate duplicate vendors with automatic transaction migration
- CSV Management: Export/import vendor configurations for backup or sharing
fern-finance/
├── app.py # Main Flask application with all routes
├── repositories/ # Data access layer
│ ├── base_repository.py # Base repository with common operations
│ ├── transaction_repository.py # Transaction-specific database operations
│ ├── vendor_repository.py # Vendor management and intelligence
│ ├── category_repository.py # Category management
│ └── budget_repository.py # Budget tracking and calculations
├── services/ # Business logic layer
│ ├── transaction_filter_service.py # Advanced filtering and search
│ ├── navigation_service.py # Navigation and routing helpers
│ └── pagination_service.py # Pagination and data display
├── static/ # Frontend assets
│ ├── css/ # Modular CSS architecture
│ │ ├── variables.css # CSS custom properties and themes
│ │ ├── base.css # Base styles and layout
│ │ ├── components.css # Component-specific styles
│ │ └── responsive.css # Mobile and responsive styles
│ └── js/ # Modular JavaScript
│ ├── api.js # API communication layer
│ ├── ui.js # UI management and interactions
│ ├── tables.js # Table operations and bulk actions
│ ├── modals.js # Modal dialogs and forms
│ ├── theme.js # Theme switching and detection
│ └── utils.js # Utility functions and helpers
├── templates/ # Jinja2 HTML templates
│ ├── base.html # Base template with navigation
│ ├── index.html # Interactive dashboard with charts
│ ├── transactions.html # Transaction management interface
│ ├── analytics.html # Comprehensive analytics dashboard
│ ├── vendor_management.html # AI-powered vendor hub
│ ├── vendor_detail.html # Detailed vendor analysis
│ ├── smart_rules.html # Smart rules management interface
│ └── upload.html # Smart import interface
├── simple_parser.py # Advanced PDF parsing with AI integration
├── pdf_parser.py # Enhanced PDF processing engine
├── bank_parser.py # Bank-specific parsing logic
├── vendor_intelligence.py # AI engine for vendor detection and learning
├── finance.db # SQLite database (auto-created, ignored)
├── claude.md # Development notes and features
├── uploads/ # Temporary PDF storage (ignored)
└── requirements.txt # Python dependencies
-- Transactions with full metadata
transactions (
id, date, amount, description, raw_description,
vendor_id, category_id, transaction_type, created_at
)
-- Intelligent vendor management
vendors (
id, name, default_category_id, aliases,
is_approved, approved_at, confidence_score
)
-- Flexible categorization
categories (
id, name, color, created_at
)
-- Budget management
budgets (
id, category_id, monthly_limit, created_at, updated_at
)- Vendor Learning: System remembers corrections and applies them automatically
- Confidence Tracking: Each vendor has a confidence score for prioritization
- Alias Support: Multiple names per vendor for flexible matching
- Retroactive Updates: Changes propagate to historical transactions
- Dutch Banks: Full support (ABN AMRO, ING, Rabobank)
- SEPA Format: European bank statement standard
- Date Format: DD-MM-YYYY with automatic conversion
- Currency: Euro (€) with Dutch decimal notation (1.234,56)
- Multi-Bank Parser: Configurable system for different bank formats
- Auto-Detection: Intelligent format recognition from PDF structure
- Global Support: US, UK, German, and other banking systems
- See
FUTURE_FEATURES.mdfor detailed expansion plans
# In app.py init_db() function
INSERT INTO categories (name, color) VALUES ('Investments', '#f39c12');# In vendor_intelligence.py
def add_vendor_pattern(self, pattern, vendor_name):
"""Add new pattern for vendor detection"""
self.patterns[pattern] = vendor_name/* In static/css/variables.css */
:root {
--primary-color: #your-color;
--accent-color: #your-accent;
}export FLASK_ENV=development # Enable debug mode
export DATABASE_URL=custom.db # Custom database location
export UPLOAD_FOLDER=uploads # Upload directory- Large PDFs: Adjust
MAX_CONTENT_LENGTHin app.py - Database: Consider PostgreSQL for production use
- Charts: Optimize data points for better performance
- Monthly spending trends with percentage changes
- Category breakdown with interactive charts
- Weekly spending patterns analysis
- Top vendor identification and analysis
- Budget status with intelligent alerts
- Transaction type evolution over time
- Vendor spending concentration analysis
- Seasonal spending pattern detection
- Income vs expense flow analysis
- Custom date range comparisons
- No transactions found: Verify PDF contains readable text (not scanned images)
- Wrong amounts: Check date format matches expected DD-MM-YYYY pattern
- Missing vendors: Review vendor intelligence confidence scores
- Slow loading: Check database indexes and query optimization
- Memory usage: Monitor large PDF processing and consider chunking
- Browser performance: Ensure Chart.js datasets aren't too large
- Charts not loading: Verify Chart.js CDN availability and theme CSS variables
- Responsive issues: Test CSS Grid fallbacks for older browsers
- Theme problems: Check CSS custom property support
- Mobile app companion
- Advanced budget tracking with alerts ✨ Completed
- Goal setting and progress tracking
- Export to Excel/CSV with formatting
- Claude AI financial commentary (premium feature)
- Predictive spending analysis
- Anomaly detection for unusual transactions
- Smart budget recommendations
- Multi-bank parser system
- API for third-party integrations
- Multi-user support with permissions
- Cloud deployment options
This project is open source and available under the MIT License. Feel free to fork, modify, and contribute!
Contributions are welcome! Whether it's bug fixes, new features, or improvements to the AI engine, feel free to:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
For technical issues, check the modular codebase documentation in each component. The repository pattern and service layer make the codebase highly maintainable and extensible.
If you find this project useful, please consider giving it a star! It helps others discover the project and motivates continued development.