Personal Finance Tracker

A comprehensive personal finance management application built with Django REST Framework (backend) and Next.js (frontend). Track your expenses, manage budgets with the 50/30/20 rule, set financial goals, and gain insights into your spending patterns.

About This Project

This Finance Tracker was created as my summer 2025 project to gain hands-on experience with full-stack web development while building something genuinely useful for personal finance management. It combines my passion for learning modern web technologies (Django REST Framework, Next.js, Docker) with the practical need for a comprehensive finance tracking solution.

The project has been an exciting journey of exploring full-stack development, from designing RESTful APIs and database models to creating responsive React components and implementing containerized deployment. While built primarily as a learning experience, it's designed to be a fully functional application that anyone can use to take control of their finances.

Key Learning Goals Achieved:

Backend Development: RESTful API design with Django REST Framework
Frontend Development: Modern React with Next.js and component libraries
DevOps: Docker containerization and deployment automation
Data Visualization: Interactive charts and financial analytics
Product Design: User-centered design for financial management

Features

Dashboard: Real-time overview of your financial status with interactive charts
Transaction Management: Track income and expenses with smart categorization
Smart Budgeting: 50/30/20 rule implementation with custom allocation
Analytics & Insights: Comprehensive spending analysis with personalized recommendations
Financial Goals: Set, track, and achieve your savings objectives
Data Management: CSV export/import functionality for easy data migration
Modern UI: Responsive design with dark theme support
Docker Ready: Easy deployment with Docker and Docker Compose

Quick Start (Recommended)

Using Docker (Self-Hosting)

The easiest way to get started is using Docker. This method handles all dependencies and configuration automatically.

Prerequisites

Docker and Docker Compose
Git

1. Clone the Repository

git clone https://github.com/Quinta0/finance_tracker.git
cd finance_tracker

2. Start Development Environment

# Start the development environment
./manage.sh dev

# The application will be available at:
# - Frontend: http://localhost:3310
# - Backend API: http://localhost:8810/api
# - Admin Panel: http://localhost:8810/admin

Port Configuration

Default Docker Ports:

Frontend: 3310
Backend API: 8810

⚠️ Port Conflicts: If you're running other Docker services (like media servers, development environments, etc.), you may encounter port conflicts. The default ports 3000, 8000, 80, and 443 are commonly used by other applications.

Common Conflicting Services:

Port 3000: Homepage, React dev servers, various dashboards
Port 8000: Django dev servers, other Python applications
Port 80/443: Traefik, Nginx, Apache web servers
Port 8080: qBittorrent, Jenkins, various web UIs

To Change Ports:

Edit docker-compose.yml and modify the port mappings:

services:
  frontend:
    ports:
      - "YOUR_PORT:3000"  # Change YOUR_PORT to your preferred port
  backend:
    ports:
      - "YOUR_PORT:8000"  # Change YOUR_PORT to your preferred port

Update the NEXT_PUBLIC_API_URL environment variable in the frontend service to match your backend port.

Alternative: Use Environment Variables Create a .env file to customize ports:

FRONTEND_PORT=3310
BACKEND_PORT=8810

Reverse Proxy Integration

This application works great with existing reverse proxy setups like Traefik, Nginx Proxy Manager, or Caddy. Since many homelab users already have these running, we've removed the built-in Nginx service to avoid conflicts.

Portainer Deployment

When deploying via Portainer (especially on Proxmox or remote hosts), you need to configure the API URL properly:

In Portainer Stack Environment Variables, add:
```
NEXT_PUBLIC_API_URL=http://YOUR_PROXMOX_IP:8810/api
FRONTEND_PORT=3310
BACKEND_PORT=8810
```
Replace YOUR_PROXMOX_IP with your actual Proxmox/host IP address.
Why this is needed: The frontend runs in the browser and needs to connect to the backend API. When using localhost, it tries to connect to the user's local machine, not the Portainer host.

Using with Traefik

If you're already running Traefik (like in the example homelab stack), add these labels to your services:

services:
  frontend:
    # ... existing configuration
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.finance-frontend.rule=Host(`finance.yourdomain.com`)"
      - "traefik.http.routers.finance-frontend.tls=true"
      - "traefik.http.routers.finance-frontend.tls.certresolver=letsencrypt"
      - "traefik.http.services.finance-frontend.loadbalancer.server.port=3000"
    networks:
      - finance_tracker_network
      - homelab  # Your existing Traefik network

  backend:
    # ... existing configuration  
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.finance-api.rule=Host(`finance-api.yourdomain.com`)"
      - "traefik.http.routers.finance-api.tls=true" 
      - "traefik.http.routers.finance-api.tls.certresolver=letsencrypt"
      - "traefik.http.services.finance-api.loadbalancer.server.port=8000"
    networks:
      - finance_tracker_network
      - homelab  # Your existing Traefik network

networks:
  finance_tracker_network:
    driver: bridge
  homelab:
    external: true  # Reference your existing network

Using with Nginx Proxy Manager

Add these as proxy hosts in your Nginx Proxy Manager:

Frontend: finance.yourdomain.com → http://finance_tracker_frontend:3000
Backend: finance-api.yourdomain.com → http://finance_tracker_backend:8000

Direct Access (No Reverse Proxy)

If you prefer direct access without a reverse proxy:

Frontend: http://your-server-ip:3310
Backend API: http://your-server-ip:8810/api

Note: The nginx/ directory contains example configurations that you can reference if you want to set up your own Nginx reverse proxy, but it's not used by the default Docker setup.

3. Production Deployment

# Copy environment template and configure
cp .env.example .env
nano .env  # Edit with your production values

# Start production environment
./manage.sh prod

# Application will be available at:
# - Frontend: http://localhost:3310
# - API: http://localhost:8810/api

Management Script Commands

The manage.sh script provides convenient commands for managing your Finance Tracker:

./manage.sh dev         # Start development environment
./manage.sh prod        # Start production environment  
./manage.sh stop        # Stop all services
./manage.sh logs        # View all logs
./manage.sh logs backend # View specific service logs
./manage.sh status      # Show container status
./manage.sh backup      # Backup database
./manage.sh restore     # Restore database from backup
./manage.sh update      # Update and restart services
./manage.sh reset       # Reset everything (destructive)

Manual Installation (Development)

For developers who want to run the application manually or contribute to the project.

Prerequisites

Python 3.9+
Node.js 18+
npm or yarn
Git

Backend Setup (Django)

Navigate to backend directory:
```
cd backend
```

Create and activate virtual environment:

python -m venv venv

# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Set up database:

python manage.py makemigrations
python manage.py migrate

Create superuser (optional):
```
python manage.py createsuperuser
```
Start development server:
```
python manage.py runserver
```
Backend API will be available at: http://localhost:8810/api

Frontend Setup (Next.js)

Navigate to frontend directory:
```
cd frontend
```
Install dependencies:
```
npm install
```
Start development server:
```
npm run dev
```
Frontend will be available at: http://localhost:3310

Running Both Services

You can run both services simultaneously using two terminal windows, or use the provided development scripts.

Project Structure

finance_tracker/
├── Docker & Deployment
│   ├── docker-compose.yml          # Development environment
│   ├── docker-compose.prod.yml     # Production environment
│   ├── manage.sh                   # Management script
│   └── .env.example               # Environment template
│
├── Backend (Django REST API)
│   ├── finance_tracker/           # Django project settings
│   ├── finance/                   # Main app
│   │   ├── models.py              # Database models
│   │   ├── views.py               # API endpoints
│   │   ├── serializers.py         # Data serialization
│   │   └── urls.py                # URL routing
│   ├── requirements.txt           # Python dependencies
│   ├── Dockerfile                 # Backend container
│   └── manage.py                  # Django management
│
├── Frontend (Next.js React)
│   ├── app/                       # Next.js app directory
│   │   ├── page.js                # Main page component
│   │   ├── layout.js              # App layout
│   │   └── globals.css            # Global styles
│   ├── components/                # React components
│   │   ├── Dashboard.jsx          # Main dashboard
│   │   ├── AddTransactionForm.jsx # Transaction forms
│   │   ├── Analytics.jsx          # Charts and insights
│   │   ├── BudgetManagement.jsx   # Budget controls
│   │   ├── FinancialGoals.jsx     # Goals tracker
│   │   └── ui/                    # UI components (shadcn/ui)
│   ├── lib/                       # Utilities
│   │   ├── api.js                 # API client
│   │   └── utils.js               # Helper functions
│   ├── package.json               # Node.js dependencies
│   └── Dockerfile                 # Frontend container
│
└── Documentation
    ├── README.md                  # This file
    ├── DOCKER.md                  # Docker guide
    └── TESTING.md                 # Testing guide

API Reference

Authentication

Currently using session-based authentication. Token-based auth coming soon.

Transactions

Method	Endpoint	Description
`GET`	`/api/transactions/`	List all transactions
`POST`	`/api/transactions/`	Create new transaction
`PUT`	`/api/transactions/{id}/`	Update transaction
`DELETE`	`/api/transactions/{id}/`	Delete transaction
`GET`	`/api/transactions/monthly_summary/`	Current month summary
`GET`	`/api/transactions/six_month_trend/`	6-month trend data

Budget Management

Method	Endpoint	Description
`GET`	`/api/budget/current_budget/`	Get current budget
`POST`	`/api/budget/update_income/`	Update monthly income
`GET`	`/api/budget/budget_analysis/`	Budget vs actual analysis

Financial Goals

Method	Endpoint	Description
`GET`	`/api/goals/`	List all goals
`POST`	`/api/goals/`	Create new goal
`PUT`	`/api/goals/{id}/`	Update goal
`DELETE`	`/api/goals/{id}/`	Delete goal
`GET`	`/api/goals/active_goals/`	Get active goals
`POST`	`/api/goals/{id}/update_progress/`	Update progress

Configuration

Environment Variables

Create a .env file from the template for production:

# Copy template
cp .env.example .env

Key variables:

DOMAIN: Your domain name (for production)
SECRET_KEY: Django secret key (generate new for production)
DEBUG: Set to 0 for production
Email settings (optional, for notifications)

Database Configuration

Development: Uses SQLite by default (simple, no setup required)

Production: Can use PostgreSQL by setting environment variables:

DB_ENGINE=django.db.backends.postgresql
DB_NAME=finance_tracker
DB_USER=finance_user
DB_PASSWORD=your_secure_password
DB_HOST=db
DB_PORT=5432

Usage Guide

Getting Started

Set Monthly Income: Go to Budget Management and set your monthly income
Add Transactions: Start adding your income and expenses
Review Dashboard: Check your financial overview and insights
Set Goals: Create savings goals and track progress
Analyze Spending: Use analytics to understand your spending patterns

Best Practices

Categorize Transactions: Use consistent categories for better insights
Regular Updates: Add transactions regularly for accurate tracking
Review Goals: Check and update your financial goals monthly
Export Data: Regularly backup your data using CSV export

Deployment

Docker Production Setup

Server Requirements:
- Linux server with Docker installed
- Domain name (optional, can use IP)
- 1GB+ RAM, 10GB+ storage

Deploy:

git clone https://github.com/Quinta0/finance_tracker.git
cd finance_tracker
cp .env.example .env
# Edit .env with your values
./manage.sh prod

SSL Setup (optional):
- Add SSL certificates to nginx/ssl/
- Update nginx configuration

Cloud Deployment

The application can be deployed on:

DigitalOcean: Using Docker Droplet
AWS: ECS or EC2 with Docker
Heroku: Using container registry
VPS: Any provider supporting Docker

Development

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test thoroughly
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Development Workflow

# Start development environment
./manage.sh dev

# View logs
./manage.sh logs

# Reset database (development only)
cd backend
rm db.sqlite3
python manage.py migrate

# Run tests
python manage.py test  # Backend tests
npm test              # Frontend tests (if available)

Adding Features

Backend: Add models in models.py, views in views.py
Frontend: Create components in components/
API: Update serializers.py and urls.py
Testing: Add tests for new functionality

Troubleshooting

Common Issues

Docker permission denied:

sudo usermod -aG docker $USER
# Log out and log back in

Port already in use:

./manage.sh stop
# Or kill specific processes
sudo lsof -i :3000
sudo lsof -i :8000

Database issues:

# Reset database (development)
./manage.sh stop
rm backend/db.sqlite3
./manage.sh dev

Build failures:

# Clean rebuild
./manage.sh stop
docker system prune -f
./manage.sh dev

Getting Help

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Check DOCKER.md and TESTING.md

Roadmap

Current Features

Transaction management with categories
50/30/20 budget rule implementation
Financial goals tracking
Spending analytics and insights
Data export/import (CSV)
Modern responsive UI
Docker deployment

Upcoming Features

Recurring Transactions: Automatic monthly bills and income
Advanced Reports: PDF reports and detailed analytics
Categories Management: Custom expense/income categories
Budget Templates: Pre-defined budget templates

Long-term Vision

Investment tracking
Multi-currency support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Django REST Framework: Powerful API development
Next.js: Modern React framework
shadcn/ui: Beautiful UI components
Recharts: Excellent charting library
Tailwind CSS: Utility-first CSS framework

If you find this project helpful, please consider giving it a star!

Report Bug · Request Feature · Contribute

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.next		.next
backend		backend
frontend		frontend
nginx		nginx
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DOCKER.md		DOCKER.md
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
README_NEW.md		README_NEW.md
TESTING.md		TESTING.md
cleanup.sh		cleanup.sh
deploy.sh		deploy.sh
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.simple.yml		docker-compose.simple.yml
docker-compose.yml		docker-compose.yml
manage.sh		manage.sh

License

Quinta0/finance_tracker

Folders and files

Latest commit

History

Repository files navigation

Personal Finance Tracker

About This Project

Features

Quick Start (Recommended)

Using Docker (Self-Hosting)

Prerequisites

1. Clone the Repository

2. Start Development Environment

Port Configuration

Reverse Proxy Integration

Portainer Deployment

Using with Traefik

Using with Nginx Proxy Manager

Direct Access (No Reverse Proxy)

3. Production Deployment

Management Script Commands

Manual Installation (Development)

Prerequisites

Backend Setup (Django)

Frontend Setup (Next.js)

Running Both Services

Project Structure

API Reference

Authentication

Transactions

Budget Management

Financial Goals

Configuration

Environment Variables

Database Configuration

Usage Guide

Getting Started

Best Practices

Deployment

Docker Production Setup

Cloud Deployment

Development

Contributing

Development Workflow

Adding Features

Troubleshooting

Common Issues

Getting Help

Roadmap

Current Features

Upcoming Features

Long-term Vision

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages