FinTrack — Personal Finance & Analytics Engine

FinTrack is an enterprise-grade, full-stack personal finance and wealth management platform designed to deliver institutional precision, real-time analytics, and intelligent financial advisory. Built with Django REST Framework (Python 3.12), PostgreSQL 16, and React 19 + Vite, FinTrack emphasizes row-level multi-tenant security, IEEE-754 float safety via exact fixed-point arithmetic, dynamic real-time budget utilization, automated recurring subscription tracking, client-side receipt OCR ingestion, and tool-gated local AI advisory.

---

1. Key Features

• Real-Time Financial Analytics & Dashboard:

  • Net worth tracker, monthly cash flow trends, and categorical expenditure distributions powered by Recharts.
  • 50/30/20 budget adherence analyzer and liquidity runway health calculator.
  • High-performance SQL database-level aggregations (Sum, TruncMonth, Case/When) with zero in-memory Python looping.

• Precision Transaction Ledger:

  • Full CRUD operations with dual-entry credit/debit semantics.
  • Multi-column filtering by transaction type, date ranges, and category.
  • Debounced search, pagination, and RFC 4180 compliant CSV export.
  • Guaranteed decimal precision (DecimalField(max_digits=12, decimal_places=2)) eliminating binary floating-point rounding discrepancies.

• Dynamic Budget Utilization Engine:

  • Real-time spend computation computed on read: $$\text{Spent} = \sum \text{Transactions}(u, c, [\text{Month Start}, \text{Month End}])$$ $$\text{Remaining} = \text{Allocated} - \text{Spent}$$ $$\text{Utilization %} = \frac{\text{Spent}}{\text{Allocated}} \times 100$$
  • Eliminates cache invalidation anomalies and race conditions when historical transactions are edited, backdated, or purged.
  • Visual color-coded thresholds (Healthy, Approaching Limit, Over-Budget).

• Automated Recurring Billing & Subscriptions:

  • Automated scheduling engine for periodic commitments (DAILY, WEEKLY, MONTHLY, YEARLY).
  • Next-run date calculation with one-click pause/resume toggles.
  • Idempotent generation service preventing duplicate billing records.

• Client-Side Optical Character Recognition (OCR):

  • Drag-and-drop receipt scanning using offline Tesseract OCR.
  • Regular expression parsing engine to automatically detect merchant names, transaction dates, and total amounts.
  • Pre-fills the transaction ledger modal for one-click confirmation.

• Tool-Gated AI Financial Copilot:

  • Context-aware financial copilot connecting to local LLM engines (Ollama / Mistral / DeepSeek) or deterministic rule fallbacks.
  • Tool-gated metric injection: only verified monthly statistical snapshots are provided to the prompt context, eliminating SQL injection hazards and preventing model hallucination.

• Atomic CSV Statement Ingestion:

  • Drag-and-drop bank statement import with flexible column header mapping.
  • Complete atomic rollbacks (django.db.transaction.atomic()) ensuring dirty files never corrupt the database ledger.

• Stateless Authentication & Security:

  • SimpleJWT token lifecycle with automatic HTTP 401 Axios refresh interceptors.
  • PBKDF2 password hashing with SHA-256 encryption.
  • Strict row-level queryset scoping preventing Insecure Direct Object References (IDOR).

---

2. Skills & Engineering Competencies

This project showcases full-lifecycle software engineering and architectural best practices:

Domain	Skills & Methodologies Demonstrated
Backend Architecture	RESTful API design, Domain-Driven ORM modeling, Django signals, custom management commands (seed_demo_data), custom middleware, pagination, and dynamic query filtering.
Database Engineering	PostgreSQL relational modeling, schema normalization (3NF), composite B-tree indexes, check constraints (CHECK (amount > 0)), foreign key protection policies (on_delete=models.PROTECT), and atomic transactions.
Frontend Engineering	Modern React 19 architecture, Vite build optimizations, custom hooks (useDashboardAnalytics), Context API state management (Auth, Toast), Axios interceptors, responsive glassmorphic UI, and Tailwind CSS.
Financial Computation	Safe currency representation using Python's Decimal and PostgreSQL numeric(12,2), dynamic balance evaluation, and cash-flow runway modeling.
Security & Hardening	JWT token authentication, CORS configuration, CSRF protection, sanitized SQL queries via ORM, input validation, and password hashing.
DevOps & Testing	Multi-stage Docker containerization, Docker Compose orchestration, Nginx reverse proxy routing, comprehensive automated test suites (113+ tests), and CI workflow preparation.

---

3. System Architecture

[ Web Browser / Client ] (React 19 + Vite SPA)
         │
         │  Port 5173 (Dev Proxy: /api/* -> 127.0.0.1:8000)
         ▼
[ Django REST Framework ] (Gunicorn / Runserver :8000)
   ├── Authentication & User Isolation Middleware (JWT)
   ├── Domain Services (Ledger, Budgets, Recurring Rules)
   ├── Statement Import Engine (Atomic CSV Parser)
   └── Tool-Gated AI Advisory Service
         │
         │  Port 5432 (psycopg2-binary connection pool)
         ▼
[ PostgreSQL 1Relational Database ]
   ├── Custom accounts_user table (Currency preferences)
   ├── Composite B-Tree Indexes: (user_id, date DESC), (user_id, category_id)
   └── Strict Table Constraints: CHECK (amount > 0.00), UNIQUE (user, category, month)

---

4. Technology Stack

• Backend: Python 3.12, Django 5.1, Django REST Framework 3.15, djangorestframework-simplejwt, psycopg2-binary, django-cors-headers
• Frontend: React 19, Vite 5.4, Tailwind CSS 3.4, Lucide React, Recharts 2.15, Axios, Tesseract.js
• Database: PostgreSQL 16
• Typography: Plus Jakarta Sans, JetBrains Mono
• Deployment & Containers: Docker, Docker Compose, Nginx, Gunicorn, WhiteNoise

---

5. Architectural Trade-offs & Decisions

Decision Area	Chosen Approach	Alternative Evaluated	Engineering Rationale
Financial Representation	DecimalField(max_digits=12, decimal_places=2)	IEEE-754 FloatField	Eliminates binary floating-point precision loss (e.g. 0.1 + 0.2 != 0.3).
Budget Balances	Computed dynamically on read via SQL Sum	Stored remaining_balance column	Avoids race conditions and cache invalidation bugs when past transactions are edited or backdated.
Category Protection	on_delete=models.PROTECT	on_delete=models.CASCADE	Enforces audit-trail integrity; prevents accidental deletion of historical ledgers when modifying categories.
Query Optimization	select_related('category') + Composite Indexes	Default unindexed lookups	Eliminates N+1 query bottlenecks and accelerates dashboard lookups across tens of thousands of records.
AI Context Safety	Tool-gated metric injection	Direct database query execution by LLM	Eliminates prompt injection risks and ensures zero model hallucinations on private financial ledgers.

---

6. Local Development Setup

Prerequisites

• Python 3.12+
• Node.js 18+ & npm
• PostgreSQL 16

---

Step 1: Database Setup

Ensure PostgreSQL is running locally on port 5432 with a database and user matching your configuration:

CREATE DATABASE fintrack;
CREATE USER fintrack_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE fintrack TO fintrack_user;

---

Step 2: Backend Configuration

cd Backend_fintrack

# Create and activate a virtual environment
python -m venv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your database credentials and secret key

# Apply database migrations
python manage.py migrate

# (Optional) Seed realistic demo records
python manage.py seed_demo_data --reset

# Start the Django development server
python manage.py runserver 127.0.0.1:8000

Default Seed Credentials:

• Email: demo@fintrack.local
• Password: DemoUser#2026

---

Step 3: Frontend Configuration

In a separate terminal:

cd Frontend_fintrack

# Install frontend dependencies
npm install

# Start Vite development server
npm run dev

The application will be accessible at: http://localhost:5173/

---

7. Automated Testing Suite

FinTrack features an automated test suite verifying edge cases, boundary conditions, arithmetic accuracy, and multi-tenant security isolation:

# Run backend test suite
cd Backend_fintrack
python manage.py test

# Run frontend tests
cd Frontend_fintrack
npm test

---

8. Docker Deployment

To launch the complete containerized stack using Docker Compose:

# Copy docker environment configuration
cp .env.docker.example .env.docker

# Build and start all services
docker compose up --build -d

Services exposed:

• Frontend / Client: http://localhost:80
• Backend API: http://localhost:8000/api/
• PostgreSQL: localhost:5432

---

9. License

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