Complete documentation and developer guide
Vance Finance is a comprehensive personal finance management web application designed to help users track their income, bills, credit cards, loans, subscriptions, and budgets with advanced analytics and insights.
Vance Finance is built with a modular component architecture where each financial entity operates independently while contributing to comprehensive financial insights.
Handles user authentication, session management, and data isolation. Ensures each user can only access their own financial data.
User Model:
- id: Primary key
- username: Unique identifier
- email: Contact information
- password_hash: Secure password storage
- Relationships: One-to-many with all financial entitiesTracks multiple income sources with flexible payment frequencies and provides monthly income calculations for financial health analysis.
Monthly Income Calculation:
- Weekly: amount × 52 ÷ 12
- Bi-weekly: amount × 26 ÷ 12
- Monthly: amount × 1
- Bi-monthly: amount × 2
- Quarterly: amount ÷ 3
- Annually: amount ÷ 12
- One-time: Excluded from monthly calculationsManages recurring and one-time bills with due date tracking, categories, and payment status. Provides expense calculations for financial analysis.
Comprehensive credit card tracking with automatic minimum payment calculations, utilization monitoring, and payment strategy optimization.
Calculation Methods:
1. Standard: 2% of current balance
2. Interest + Principal: Monthly interest + 1% principal
3. Minimum Floor: $25 absolute minimum
4. Annual Fee Addition: Monthly fees added if applicable
5. Balance Cap: Never exceeds current balance + fees
Final Amount: MAX(method1, method2, $25) + monthly_feesTracks recurring subscription services with multiple billing cycles, categories, and auto-renewal status. Helps identify subscription spending patterns.
Tracks various loan types with progress monitoring, payment scheduling, and payoff visualization. Supports multiple loan categories and terms.
Progress Calculation:
Progress % = (Principal Amount - Current Balance) / Principal Amount × 100
Visual indicators:
- Progress bars showing completion percentage
- Remaining balance vs original amount
- Monthly payment impact on timelineComplete budgeting system with categories, periods, transactions, and goals. Provides planned vs actual analysis with intelligent insights.
Performance Analysis:
- Planned vs Actual comparison
- Category performance status (Excellent/Good/Warning/Over Budget)
- Percentage completion tracking
- Variance analysis and recommendations
- Savings rate calculation
- Budget insights and strategic recommendationsProcesses data from all components to generate financial insights, health metrics, and projections. The brain of the financial analysis system.
Component → Analytics Engine → Insights
Income Sources → Monthly Income Calculation
Bills + Subscriptions + Loans + Credit Cards → Monthly Expenses
Budget Transactions → Spending Analysis
All Components → Financial Timeline Generation
Combined Data → Health Metrics & RecommendationsResult: A comprehensive financial management system where each component operates independently but contributes to holistic financial insights and recommendations.
/demo to see the app with sample dataYour financial command center provides:
The Financial Overview is now part of the main Dashboard. It provides a summary of your total income, total expenses, net income, and savings rate for any date range you select.
In the "All Upcoming Bills" section of the dashboard, a "View All" button is always visible in the card header. Click this button to see the complete list of your upcoming bills.
| Frequency | Best For | Configuration | Example |
|---|---|---|---|
| Bi-weekly | Most salary jobs | Next payment date | Every other Friday |
| Bi-monthly | Salary paid twice monthly | Two payment days per month | 15th and 30th |
| Monthly | Freelance, contract work | Day of month | Every 25th |
| One-time | Bonuses, tax refunds | Specific date | March 15, 2025 |
The system automatically calculates minimum payments using multiple methods:
The system uses the highest calculated amount but never exceeds your current balance plus fees.
Use the advanced payment calculator for debt payoff strategies:
Calculated as: (Total Monthly Debt Payments / Total Monthly Income) × 100
Per-card and overall utilization: (Current Balance / Credit Limit) × 100
Control which financial items affect your calculations:
git clone <repository-url>
cd vance-financepython -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activatepip install -r requirements.txtpython static_setup.py# Copy example environment file
cp .env.example .env
# Edit .env with your settings
SECRET_KEY=your-secret-key-here
DEVELOPMENT_MODE=truepython Vance_Financial_Assistant.py/demo to explore the application with pre-populated sample data including all new features like budget management and advanced credit card tools.
Deploy to Heroku, DigitalOcean, or AWS with pre-configured deployment files.
Deploy Guide →Set up environment variables, database connections, and application settings.
Configure →| Variable | Description | Default | Required |
|---|---|---|---|
SECRET_KEY |
Flask session encryption key (CSRF protection) | Auto-generated | Production |
DATABASE_URL |
Database connection string | SQLite local file | No |
DEVELOPMENT_MODE |
Enable development features | true | No |
PORT |
Application port | 5000 | No |
DATABASE_URL=sqlite:///finance_tracker.dbAutomatic setup with safe migrations
DATABASE_URL=postgresql://user:password@host:port/databaseRecommended for production deployments
Vance Finance uses a comprehensive database schema with 11 core tables supporting all financial management features. The schema includes automatic migration support and foreign key relationships for data integrity.
CREATE TABLE user (
id INTEGER PRIMARY KEY,
username VARCHAR(80) UNIQUE NOT NULL,
password_hash VARCHAR(256) NOT NULL,
email VARCHAR(120) UNIQUE NOT NULL
);CREATE TABLE bill (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL,
amount FLOAT NOT NULL,
due_date DATE NOT NULL,
category VARCHAR(50),
is_paid BOOLEAN DEFAULT FALSE,
recurring BOOLEAN DEFAULT FALSE,
include_in_calculations BOOLEAN DEFAULT TRUE,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE credit_card (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL,
last_four VARCHAR(4) NOT NULL,
limit FLOAT,
current_balance FLOAT DEFAULT 0,
payment_due_date DATE NOT NULL,
minimum_payment FLOAT,
interest_rate FLOAT,
is_paid BOOLEAN DEFAULT FALSE,
auto_pay_minimum BOOLEAN DEFAULT FALSE,
auto_payment_amount FLOAT,
include_in_calculations BOOLEAN DEFAULT TRUE,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE income_source (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL,
amount FLOAT NOT NULL,
frequency VARCHAR(20) NOT NULL, -- weekly, biweekly, monthly, etc.
payment_day_1 INTEGER,
payment_day_2 INTEGER,
next_payment_date DATE,
day_of_week VARCHAR(10),
one_time_date DATE,
is_active BOOLEAN DEFAULT TRUE,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE subscription (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL,
amount FLOAT NOT NULL,
billing_cycle VARCHAR(20) NOT NULL, -- Monthly, Yearly, Weekly
next_billing_date DATE NOT NULL,
category VARCHAR(50),
is_active BOOLEAN DEFAULT TRUE,
auto_renew BOOLEAN DEFAULT TRUE,
include_in_calculations BOOLEAN DEFAULT TRUE,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE loan (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL,
loan_type VARCHAR(50) NOT NULL, -- Personal, Auto, Mortgage, Student
principal_amount FLOAT NOT NULL,
current_balance FLOAT NOT NULL,
monthly_payment FLOAT NOT NULL,
interest_rate FLOAT,
next_payment_date DATE NOT NULL,
term_months INTEGER,
is_paid_off BOOLEAN DEFAULT FALSE,
include_in_calculations BOOLEAN DEFAULT TRUE,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE budget_category (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL,
description VARCHAR(255),
color VARCHAR(7) DEFAULT '#667eea', -- Hex color code
icon VARCHAR(50) DEFAULT 'bi-wallet2', -- Bootstrap icon class
is_active BOOLEAN DEFAULT TRUE,
is_income BOOLEAN DEFAULT FALSE, -- True for income, False for expense
sort_order INTEGER DEFAULT 0,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE budget_period (
id INTEGER PRIMARY KEY,
name VARCHAR(100) NOT NULL, -- e.g., "January 2025", "Q1 2025"
period_type VARCHAR(20) NOT NULL, -- monthly, quarterly, yearly, custom
start_date DATE NOT NULL,
end_date DATE NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
auto_rollover BOOLEAN DEFAULT FALSE, -- Auto-create next period
notes TEXT,
user_id INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE budget_item (
id INTEGER PRIMARY KEY,
category_id INTEGER NOT NULL,
period_id INTEGER NOT NULL,
planned_amount FLOAT NOT NULL DEFAULT 0.0,
actual_amount FLOAT DEFAULT 0.0, -- Auto-calculated from transactions
notes TEXT,
alert_threshold FLOAT, -- Alert when % of budget is reached
is_rollover BOOLEAN DEFAULT FALSE, -- Unused budget rolls to next period
user_id INTEGER NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (category_id) REFERENCES budget_category(id),
FOREIGN KEY (period_id) REFERENCES budget_period(id),
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE budget_transaction (
id INTEGER PRIMARY KEY,
category_id INTEGER NOT NULL,
period_id INTEGER NOT NULL,
description VARCHAR(255) NOT NULL,
amount FLOAT NOT NULL,
transaction_date DATE NOT NULL,
transaction_type VARCHAR(20) DEFAULT 'manual', -- manual, bill, subscription, loan
reference_id INTEGER, -- ID of linked bill/subscription/loan
receipt_url VARCHAR(255), -- Optional receipt/proof
tags VARCHAR(255), -- Comma-separated tags
notes TEXT,
user_id INTEGER NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (category_id) REFERENCES budget_category(id),
FOREIGN KEY (period_id) REFERENCES budget_period(id),
FOREIGN KEY (user_id) REFERENCES user(id)
);CREATE TABLE budget_goal (
id INTEGER PRIMARY KEY,
title VARCHAR(150) NOT NULL,
description TEXT,
target_amount FLOAT NOT NULL,
current_amount FLOAT DEFAULT 0.0,
target_date DATE,
category VARCHAR(50), -- emergency, vacation, purchase, debt_payoff
priority VARCHAR(20) DEFAULT 'medium', -- low, medium, high
is_active BOOLEAN DEFAULT TRUE,
is_achieved BOOLEAN DEFAULT FALSE,
auto_contribute FLOAT DEFAULT 0.0, -- Automatic monthly contribution
user_id INTEGER NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES user(id)
);| Version | Changes | Migration |
|---|---|---|
| v1.0 | Initial schema: User, Bill, CreditCard | Create initial tables |
| v1.1 | Added: Subscription, Loan, IncomeSource | Add new financial entity tables |
| v1.1.2 | Added: include_in_calculations columns | ALTER TABLE add column operations |
| v1.1.3 | Added: auto_pay_minimum, auto_payment_amount | Credit card feature enhancements |
| v1.1.4 | Added: Complete budget management schema | 5 new budget-related tables |
| v1.1.5 | Added: one_time_date for income sources | Enhanced income frequency support |
Register a new user account with CSRF protection.
Form Data:username: string (required)
email: string (required)
password: string (required)
csrf_token: string (required)Authenticate user login with session management.
Form Data:username: string (required)
password: string (required)
csrf_token: string (required)End user session and redirect to login.
Response: Redirect to login page with flash message.Main financial dashboard with comprehensive overview.
Response Data:Financial timeline with 90-day projections.
Query Parameters:start_date: YYYY-MM-DD (optional)
end_date: YYYY-MM-DD (optional)
include_excluded: boolean (optional)Manage bills and recurring payments.
POST Form Data:name: string (required)
amount: float (required)
due_date: YYYY-MM-DD (required)
category: string (optional)
recurring: boolean (optional)
include_in_calculations: boolean (optional)
csrf_token: string (required)Credit card management with automatic minimum payment calculation.
POST Form Data:name: string (required)
last_four: string (required)
limit: float (optional)
current_balance: float (required)
interest_rate: float (optional)
due_day: integer (required)
auto_pay_minimum: boolean (optional)
auto_payment_amount: float (optional)
csrf_token: string (required)Income source management with flexible frequencies.
POST Form Data:name: string (required)
amount: float (required)
frequency: string (required) // weekly, biweekly, monthly, bimonthly, quarterly, annually, onetime
payment_day_1: integer (conditional)
payment_day_2: integer (conditional)
next_payment_date: YYYY-MM-DD (conditional)
day_of_week: string (conditional)
one_time_date: YYYY-MM-DD (conditional)
csrf_token: string (required)Budget dashboard with analytics and insights.
Response Data:Record and manage budget transactions.
POST Form Data:category_id: integer (required)
description: string (required)
amount: float (required)
transaction_date: YYYY-MM-DD (required)
notes: string (optional)
tags: string (optional)
csrf_token: string (required)Create and manage financial goals.
POST Form Data:title: string (required)
description: string (optional)
target_amount: float (required)
target_date: YYYY-MM-DD (optional)
category: string (optional)
priority: string (optional) // low, medium, high
auto_contribute: float (optional)
csrf_token: string (required)Export all user data to JSON format.
Response: JSON file download with complete user data backup.Import data from JSON backup file.
POST Form Data:backup_file: file (required) // JSON file
clear_existing: boolean (optional)
csrf_token: string (required)Create manual database backup.
Response: Flash message with backup status.Demo landing page with feature showcase.
Automatic login as demo user with sample data.
Response: Automatic session creation and redirect to dashboard.Reset demo data to original state.
Authentication: Demo mode only.# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt# Set environment variables
export DEVELOPMENT_MODE=true
export SECRET_KEY=your-dev-secret-key
# Or create .env file
echo "DEVELOPMENT_MODE=true" > .env
echo "SECRET_KEY=your-dev-secret-key" >> .envvance-finance/
├── Vance_Financial_Assistant.py # Main application file
├── requirements.txt # Python dependencies
├── static_setup.py # Static file setup script
├── wsgi.py # WSGI entry point
├── config.py # Configuration management
├── demo.py # Demo data generator
├── .env.example # Environment template
├── Dockerfile # Container configuration
├── templates/ # Jinja2 templates
│ ├── base.html # Base template
│ ├── dashboard.html # Main dashboard
│ ├── bills.html # Bill management
│ ├── credit_cards.html # Credit card management
│ ├── income.html # Income management
│ ├── budget.html # Budget dashboard
│ ├── budget_transactions.html # Budget transactions
│ ├── budget_goals.html # Budget goals
│ └── errors/ # Error pages
├── static/ # Static assets
│ └── css/ # Stylesheets
│ ├── style.css # Main styles
│ ├── budget.css # Budget-specific styles
│ └── wiki.css # Documentation styles
└── backups/ # Database backups (auto-created)All models are defined in the main application file:
/debug/paths - View file system paths and configuration/debug/users - View user database information/test/backup - Test backup functionality# Production environment variables
export DEVELOPMENT_MODE=false
export SECRET_KEY=your-production-secret-key-here
export DATABASE_URL=your-production-database-url
export PORT=5000# Build the Docker image
docker build -t vance-finance .
# Run with environment variables
docker run -d \
--name vance-finance \
-p 5000:5000 \
-e SECRET_KEY=your-secret-key \
-e DATABASE_URL=your-database-url \
-e DEVELOPMENT_MODE=false \
vance-finance# docker-compose.yml
version: '3.8'
services:
app:
build: .
ports:
- "5000:5000"
environment:
- SECRET_KEY=your-secret-key
- DATABASE_URL=sqlite:///finance_tracker.db
- DEVELOPMENT_MODE=false
volumes:
- ./backups:/app/backups
- ./data:/app/data# Install Heroku CLI and login
heroku login
# Create Heroku app
heroku create your-app-name
# Add PostgreSQL database
heroku addons:create heroku-postgresql:hobby-dev# Set environment variables
heroku config:set SECRET_KEY=your-secret-key
heroku config:set DEVELOPMENT_MODE=false
# Database URL is automatically set by Heroku PostgreSQL addon# Deploy to Heroku
git push heroku main
# Migrate database (if needed)
heroku run python -c "from Vance_Financial_Assistant import app, db; app.app_context().push(); db.create_all()"# Install Gunicorn
pip install gunicorn
# Run with Gunicorn
gunicorn --bind 0.0.0.0:5000 --workers 4 wsgi:app
# Or with configuration file
gunicorn --config gunicorn.conf.py wsgi:app# /etc/nginx/sites-available/vance-finance
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /static {
alias /path/to/your/app/static;
expires 1d;
}
}# /etc/systemd/system/vance-finance.service
[Unit]
Description=Vance Finance Application
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/your/app
Environment=PATH=/path/to/your/app/venv/bin
ExecStart=/path/to/your/app/venv/bin/gunicorn --workers 3 --bind unix:vance-finance.sock -m 007 wsgi:app
Restart=always
[Install]
WantedBy=multi-user.target# .do/app.yaml
name: vance-finance
services:
- name: web
source_dir: /
github:
repo: your-username/vance-finance
branch: main
run_command: gunicorn --worker-tmp-dir /dev/shm --config gunicorn.conf.py wsgi:app
environment_slug: python
instance_count: 1
instance_size_slug: basic-xxs
envs:
- key: SECRET_KEY
value: your-secret-key
- key: DEVELOPMENT_MODE
value: "false"
databases:
- name: db
engine: PG
version: "13"pip install awsebclieb initeb create productioneb setenv SECRET_KEY=your-key DEVELOPMENT_MODE=falseeb deploy/health returns application status<form method="POST">
<input type="hidden" name="csrf_token" value="ImI3MTJlNjg3MDBhZTNjYzE5ZWUyMGE3NDY5OGMwYjdmZDg5MzIxYjgi.aTOnVQ.8u9GSySjIhJW0k5R-i9Y72sTwfI"/>
<!-- form fields -->
</form>@app.route('/protected')
def protected_route():
if 'user_id' not in session:
return redirect(url_for('login'))
# Verify data ownership
item = Model.query.get_or_404(item_id)
if item.user_id != session['user_id']:
flash('Unauthorized access', 'danger')
return redirect(url_for('dashboard'))# Add to your Flask app or web server configuration
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'
Referrer-Policy: strict-origin-when-cross-originVance Finance includes a multi-layered backup system designed to protect your financial data with multiple recovery options.
/backup/manualbackups/finance_tracker_backup_YYYYMMDD_HHMMSS.db/backup/exportDatabase Backups:
finance_tracker_backup_20250711_143022.db
JSON Exports:
vance_financial_backup_username_20250711_143022.json# Cron job for daily backups (Linux/Mac)
0 2 * * * /path/to/your/app/venv/bin/python -c "
from Vance_Financial_Assistant import backup_database, app
with app.app_context():
backup_database()
"python --version (requires 3.7+)pip install -r requirements.txtnetstat -an | grep 5000export PORT=5001/demo/login to test functionality/debug/users (development only)df -h (Linux/Mac) or check disk properties| Route | Purpose | Information Provided |
|---|---|---|
/debug/paths |
File system debugging | Application paths, working directory, database location |
/debug/users |
User database inspection | User count, usernames, email addresses |
/test/backup |
Backup system testing | Backup functionality, file permissions, directory access |
/health |
Application health check | Application status, timestamp, basic functionality |
# Database connection error
sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) database is locked
# CSRF token error
The CSRF token is missing. or Bad Request: The CSRF token is missing.
# Permission error
PermissionError: [Errno 13] Permission denied: '/path/to/database'
# Import error (missing dependency)
ModuleNotFoundError: No module named 'flask'If all else fails, you can reset to demo state for testing:
/demo/login to access demo mode/demo/reset to restore original demo data