A comprehensive family expense management web application that enables users to track personal and shared expenses, manage family member contributions, set intelligent budgets, and generate detailed financial reports. The goal was to build something intuitive, simple, and scalable while applying Flask best practices and modern web development principles.
Live Demo | Documentation | Report Bug | Request Feature
- Project Goals
- User Stories
- Features
- Database Design
- User Interface
- Technology Stack
- Project Management
- Installation
- Testing
- Deployment
- Future Enhancements
- Credits
- Intuitive Financial Management - User-friendly expense tracking for individuals and families
- Intelligent Cost Splitting - Flexible splitting: personal, shared, or members-only expenses
- Real-Time Budget Monitoring - Proactive alerts and spending analysis with custom thresholds
- Actionable Financial Insights - Interactive dashboards, trends, and detailed reports
- Data Privacy & Security - Secure authentication and authorization
- Scalability - Maintainable Flask Blueprint architecture for future expansion
As a budget-conscious user, I want to quickly log daily expenses, categorize them, set monthly budgets, and receive alerts when approaching limits, so that I can maintain control over my finances.
As a family account manager, I want to add family members, assign them to shared expenses, and view detailed breakdowns, so that I can fairly distribute household costs and maintain transparency.
As a detail-oriented user, I want to view monthly summaries, analyze spending patterns, and export data to CSV/PDF, so that I can identify trends and maintain accurate records.
As a privacy-conscious user, I want to create a secure account, update my profile, and delete my data when needed, so that I can maintain control over my personal information.
As a system administrator, I want to access an admin interface to manage users, transactions, and categories, so that I can maintain the application and ensure system integrity.
Click to watch the full application walkthrough showing expense tracking, family management, budgets, and analytics features.
Core features for personal and family expense management with intelligent cost splitting.
Secure email-based registration and login with bcrypt password hashing, session management, and role-based admin access control.
Real-time financial overview with monthly summaries, category pie charts, budget progress bars with color-coded alerts, spending trends, and recent transaction activity.
Complete CRUD operations for income/expenses with category assignment, date selection, member cost-splitting, and user participation toggle. Advanced filtering by type, category, and date range with sorting and pagination.
Add, edit, and delete family members with automatic join date tracking. View comprehensive member statistics including total contributions, transaction count, and spending averages.
Flexible expense splitting with three modes: personal (100% user), shared (even split with members), and members-only (user pays, members owe). Real-time calculations with clear cost breakdowns.
See PROJECT_DOCUMENTATION.md for detailed calculations and examples.
Create budgets for users or members by category or total spending. Real-time monitoring with color-coded alerts (🟢 green, 🟡 yellow, 🟠 orange, 🔴 red) based on customizable thresholds (default 80%). Pause/unpause budgets as needed.
Export transactions to CSV (Excel/Google Sheets compatible) or PDF (professional formatted reports) for tax preparation and record-keeping.
View and edit account details (username, email). Clear all transaction data or permanently delete account with double confirmation for data safety.
Visualize income vs expenses with line charts, category breakdowns, net balance tracking, and spending trend predictions.
Flask-Admin dashboard for superusers with full database management: user/transaction/category/budget oversight, bulk operations, and advanced search/filtering.
- Search & Filtering - Transaction search by amount, date, category; member filtering; date range pickers
- Responsive Design - Mobile-first approach with CSS Grid/Flexbox, optimized for all screen sizes
- Real-Time Updates - Instant budget recalculation, live spending percentages, dynamic statistics
Entity Relationship Diagram showing all 6 tables with fields, data types, nullable constraints, and relationship cardinalities
The application uses 6 core tables managed by SQLAlchemy ORM with Flask-Migrate for migrations:
- Users - Account authentication and profiles
- Categories - 7 system categories (Transport, Utilities, Entertainment, Food, Healthcare, Shopping, Other) + custom
- Members - Family member data entities (not user accounts)
- Transactions - Income/expense financial records
- MembersTransaction - Junction table for cost splitting (many-to-many)
- Budgets - Budget tracking for users/members by category
Database: SQLite (development) / PostgreSQL (production-ready)
For implementation details and key relationship notes, see Project Documentation.
- User-Centered: Clean interfaces, intuitive navigation, consistent design patterns
- Responsive: Mobile-first with breakpoints (Desktop: 1200px+, Tablet: 768-1199px, Mobile: <768px)
- Accessible: Semantic HTML5, ARIA labels, keyboard navigation, WCAG AA compliant
Wireframing: Initial paper sketches to establish layout and user flow
Prototyping: High-fidelity mockups created in Figma for visual design
Paper Wireframes |
Click to view interactive Figma prototype |
- 🟦 Primary Blue
#3498db- Main actions, links, primary buttons - 🟩 Success Green
#28a745- Confirmations, positive feedback, income - 🟨 Warning Yellow
#ffc107- Alerts, budget warnings - 🟥 Danger Red
#dc3545- Errors, deletions, over-budget status - ⬛ Dark Gray
#2c3e50- Text, headers - ⬜ Light Gray
#f8f9fa- Backgrounds, borders
- Font Family: System font stack (Arial, Helvetica, sans-serif)
- Headings: Bold weight for hierarchy
- Body Text: Regular weight for readability
- Font Sizes: Responsive scaling for accessibility
Public Routes: Landing (/), Login, Register, About, FAQ
Protected Routes: Dashboard, Transactions, Family Management, Budgets, Cash Flow, Profile
Admin Only: Admin Dashboard (/admin)
Full route details and access control logic available in Project Documentation.
Flask Blueprint Structure:
auth_bp- Login, signup, logoutmain_bp- Dashboard, family, profile, cashflow, static pagestransactions_bp- Transactions CRUD, budgets, exports
Defensive Design: Form validation (client + server), CSRF protection, SQL injection prevention, XSS protection, bcrypt password hashing, confirmation dialogs for destructive actions
Backend: Flask 3.1.2, Python 3.13, SQLAlchemy 2.0.36, Flask-Login, Flask-WTF, ReportLab (PDF), bcrypt (password hashing)
Database: SQLite (development) / PostgreSQL (production) with Flask-Migrate
Frontend: HTML5, CSS3 (Grid/Flexbox), Vanilla JavaScript
Testing: pytest 8.4.2, pytest-flask, 49 tests (100% passing)
Tools: Git/GitHub, VS Code, pip, venv
See requirements.txt for complete dependency list.
Smart_Expenses_Tracker/
├── run.py # Application entry point
├── requirements.txt # Python dependencies
├── app/
│ ├── __init__.py # App factory, extensions initialization
│ ├── models.py # SQLAlchemy models (User, Transaction, Member, Budget, Category)
│ ├── services.py # Business logic (cost splitting, budget calculations)
│ ├── utils.py # Helper functions
│ ├── admin.py # Admin user management
│ ├── auth/ # Authentication blueprint
│ │ ├── __init__.py
│ │ ├── routes.py # Login, register, logout routes
│ │ └── forms.py # WTForms for authentication
│ ├── main/ # Main application blueprint
│ │ ├── __init__.py
│ │ └── routes.py # Dashboard, profile routes
│ ├── transactions/ # Transaction management blueprint
│ │ ├── __init__.py
│ │ ├── routes.py # CRUD operations for transactions
│ │ └── forms.py # Transaction forms
│ ├── static/
│ │ ├── css/ # Stylesheets (style.css, budget.css, etc.)
│ │ ├── js/ # JavaScript files (script.js, members.js)
│ │ └── images/ # Static images
│ ├── templates/ # Jinja2 templates
│ │ ├── base.html # Base template with navigation
│ │ ├── index.html # Landing page
│ │ ├── dashboard.html # Main dashboard
│ │ ├── transactions.html # Transaction list
│ │ ├── edit_transaction.html # Edit transaction form
│ │ ├── budget.html # Budget management
│ │ ├── family_management.html # Family members
│ │ ├── cashflow.html # Cash flow analysis
│ │ ├── about.html # About page
│ │ └── faq.html # FAQ page
│ └── utilities/
│ └── seed_categories.py # Database seeding script
├── migrations/ # Flask-Migrate database migrations
├── instance/
│ └── expenses.db # SQLite database (dev)
└── tests/ # pytest test suite
├── conftest.py # Test fixtures
├── test_auth.py # Authentication tests
├── test_family_management.py # Family management tests
├── test_transactions.py # Transaction tests
├── test_budgets.py # Budget tests
└── test_cost_splitting.py # Cost splitting logic tests
Development Approach: Hybrid methodology combining Waterfall and Agile practices
- Ideation: Requirements gathering and feature planning
- Design: Wireframing (paper sketches) and prototyping (Figma)
- Database Design: ERD modeling and schema planning
- Methodology: Iterative development with sprint cycles
- Task Management: GitHub Projects with Kanban board
- Version Control: Git feature branches and pull requests
- Testing: Continuous testing and integration
Tools: GitHub Projects for task tracking, Git/GitHub for version control and collaboration
# 1. Clone repository
git clone https://github.com/FlaviaMorgulis/Smart_Expenses_Tracker.git
cd Smart_Expenses_Tracker
# 2. Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS/Linux
# 3. Install dependencies
pip install -r requirements.txt
# 4. Initialize database
flask db upgrade
# 5. Seed categories (run in Python shell)
python -c "from app import create_app, db; from app.utilities.seed_categories import seed_system_categories; app = create_app(); app.app_context().push(); seed_system_categories()"
# 6. Create admin user (optional)
python create_admin.py
# 7. Run application
python run.py
# Access at http://127.0.0.1:5000Requirements: Python 3.10+, pip, git (optional)
Test Suite: 49 tests (100% passing) - Authentication (15), Transactions (6), Family Management (8), Cost Splitting (10), Budget Management (10)
Test Strategy: Test-Driven Development (TDD) approach with isolated unit and integration tests. Each test uses in-memory SQLite database to ensure no state pollution. Comprehensive coverage of authentication, CRUD operations, cost-splitting logic, and budget calculations.
pytest # Run all tests
pytest --cov=app # With coverage
pytest tests/test_auth.py # Specific fileFull test documentation in Project Documentation.
Status: Development Complete - Ready for Deployment
Next Phase: Production deployment and user testing planned for PythonAnywhere platform.
- Cashflow for Family Management - Per-member cash flow analysis and tracking
- Enhanced Analytics - Year-over-year comparison, trend predictions, spending heatmaps, forecasting
- Notifications - Email/SMS budget alerts, in-app notification center, summary emails
- Advanced Budgets - Weekly/monthly/yearly periods, recurring budgets, rollover, templates
- Receipt Scanning - Mobile camera OCR, auto-populate transactions, cloud storage
- Data Visualization - Interactive charts (Chart.js/D3.js), customizable widgets, drag-and-drop
- Multi-Currency - Currency conversion API, exchange rate tracking, multiple currencies
- Recurring Transactions - Subscription tracking, auto-create expenses, bill reminders
- Mobile App - React Native (iOS/Android), offline sync, push notifications, biometrics
- Shared Accounts - Multi-user access, role-based permissions, real-time collaboration
- Advanced Reporting - Tax reports, custom builder, scheduled delivery, accounting exports
- Banking Integration - Plaid/Open Banking API, auto-import, credit card sync, net worth
- Machine Learning - Pattern recognition, anomaly detection, smart suggestions, predictive alerts
- Goal Setting - Savings tracker, debt payoff calculator, milestone tracking, visual progress
Developers: Flavia Morgulis | Behram Aras
Acknowledgments:Komal Karrir (Instructor), Flask documentation, SQLAlchemy ORM, pytest team, Stack Overflow community, RealPython
Resources: Project Documentation | Flask Docs | SQLAlchemy Docs | pytest Docs | RealPython | CS50 | GitHub Docs | GitHub Projects
Support: Report Bug | Request Feature