🚀 Finexa

AI-Powered Personal Finance Intelligence

AI Financial Coach • Financial Health Score • Smart Budgeting • Expense Tracking • Risk Simulation • Goal Planning

---

📋 Table of Contents

• Overview
• Key Features
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Running the Project
• API Documentation
• Database Setup
• Project Architecture
• Features in Detail
• Contributing
• License

---

📚 Overview

Finexa is an AI-powered personal finance management platform designed to help users take control of their financial health. The platform leverages advanced machine learning, real-time data processing, and intuitive user interfaces to provide comprehensive financial insights, automated expense tracking, and intelligent financial recommendations.

Mission

Empower individuals to achieve financial wellness through AI-driven insights, habit building, and personalized financial guidance.

---

🎯 Key Features

Core Financial Management

• 📊 Dashboard Overview - Real-time financial health score, income/expense tracking, savings visualization
• 💰 Wallet Management - Multi-currency support, balance tracking, transaction history
• 📄 Document Upload & Processing - PDF/image-based expense extraction using AI, automatic transaction categorization
• 💳 Transaction Tracking - Detailed transaction logs, category-wise breakdown, spending patterns analysis

AI-Powered Intelligence

• 🤖 AI Coach - Intelligent chatbot providing personalized financial advice using LLM (Google Gemini/OpenAI)
• 💡 Spending Analysis - Automatic identification of spending patterns, anomalies, and optimization opportunities
• 🎯 Financial Recommendations - AI-generated suggestions for budget optimization and expense reduction
• 📈 Spending Insights - Category analysis, trend detection, comparative financial metrics

Goal & Savings Management

• 🎯 Goals Tracker - Create, track, and manage savings goals with progress visualization
• 💾 Savings Automation - Automatic savings tracking and goal-based fund allocation
• 📋 Expense Budget - Set category-wise budgets and monitor spending against limits

Gamification & Engagement

• 🏆 Habit Challenges - Engagement-driven financial habits with streak tracking, points, and rewards
• 🎖️ Achievement Badges - Earn badges for financial milestones and consistent behavior
• 📚 Financial Education - Interactive learning modules covering financial concepts and best practices

Advanced Analytics

• ⚠️ Emergency Risk Assessment - Calculate emergency fund coverage and financial safety ratings
• 💹 Income Simulator - Model different income scenarios and financial projections
• 📊 Financial Health Score - Comprehensive scoring based on income stability, savings rate, expense ratio, and more

---

⚙️ Tech Stack

---

📁 Project Structure

Logic_Legion_Finexa/
├── backend/
│   ├── ai_assistant/                    # AI & document processing module
│   │   ├── migrations/                  # Database migrations
│   │   ├── services/
│   │   │   ├── agent.py                 # LLM agent for conversation
│   │   │   ├── expense_extraction.py    # Document-to-expense extraction
│   │   │   ├── financial_health.py      # Health score calculation
│   │   │   ├── spending_analysis.py     # Pattern analysis
│   │   │   └── goal_planning.py         # Goal optimization
│   │   ├── views.py                     # API endpoints
│   │   ├── serializers.py               # Data serialization
│   │   ├── models.py                    # Database models
│   │   └── urls.py                      # Routing
│   ├── core/
│   │   ├── settings.py                  # Django configuration
│   │   ├── urls.py                      # Main URL routing
│   │   ├── asgi.py                      # ASGI config
│   │   └── wsgi.py                      # WSGI config
│   ├── users/                           # User authentication & management
│   │   ├── models.py                    # User model
│   │   ├── views.py                     # Auth endpoints
│   │   └── serializers.py               # User serializers
│   ├── transactions/                    # Transaction management
│   ├── sockets/                         # WebSocket support
│   ├── gamification/                    # Badges & challenges
│   ├── savings_goals/                   # Goals tracking
│   ├── manage.py                        # Django CLI
│   ├── requirements.txt                 # Python dependencies
│   ├── Dockerfile                       # Docker image config
│   ├── .env.example                     # Environment template
│   └── README.md                        # Backend documentation
│
├── frontend/
│   ├── src/
│   │   ├── components/                  # Reusable React components
│   │   │   ├── ProtectedRoute.tsx       # Route protection
│   │   │   └── CursorFX.tsx             # UI effects
│   │   ├── contexts/
│   │   │   ├── AuthContext.tsx          # Authentication state
│   │   │   └── ThemeContext.tsx         # Theme configuration
│   │   ├── pages/
│   │   │   ├── auth/
│   │   │   │   ├── SignIn.tsx           # Login page
│   │   │   │   └── SignUp.tsx           # Registration page
│   │   │   ├── dashboard/
│   │   │   │   ├── Overview.tsx         # Main dashboard
│   │   │   │   ├── Wallet.tsx           # Wallet management
│   │   │   │   ├── Transactions.tsx     # Transaction list
│   │   │   │   ├── Documents.tsx        # File upload
│   │   │   │   ├── SpendingInsights.tsx # Analytics
│   │   │   │   ├── GoalsTracker.tsx     # Goals management
│   │   │   │   ├── AICoach.tsx          # AI chatbot
│   │   │   │   ├── HabitChallenges.tsx  # Gamification
│   │   │   │   ├── FinancialEducation.tsx # Learning
│   │   │   │   ├── BudgetOptimizer.tsx  # Budget planning
│   │   │   │   ├── IncomeSimulator.tsx  # Scenario modeling
│   │   │   │   ├── EmergencyRisk.tsx    # Risk assessment
│   │   │   │   ├── Cards.tsx            # Card management
│   │   │   │   ├── Subscription.tsx     # Subscription management
│   │   │   │   └── Settings.tsx         # User settings
│   │   │   ├── Landing/
│   │   │   │   └── index.tsx            # Landing page
│   │   │   └── Onboarding.tsx           # Onboarding flow
│   │   ├── layouts/
│   │   │   └── DashboardLayout.tsx      # Main layout
│   │   ├── lib/
│   │   │   ├── api.ts                   # API client
│   │   │   ├── calculations.ts          # Financial calculations
│   │   │   └── mockData.ts              # Mock data for testing
│   │   ├── App.tsx                      # Main app component
│   │   ├── main.tsx                     # Entry point
│   │   └── index.css                    # Global styles
│   ├── public/                          # Static assets
│   ├── package.json                     # Node dependencies
│   ├── tsconfig.json                    # TypeScript config
│   ├── vite.config.ts                   # Vite configuration
│   ├── tailwind.config.js               # Tailwind CSS config
│   └── postcss.config.js                # PostCSS config
│
├── docker-compose.yml                   # Multi-container orchestration
├── .gitignore                           # Git ignore rules
└── README.md                            # This file

---

📋 Prerequisites

• Node.js 18.0 or higher
• Python 3.10 or higher
• npm 9.0 or higher (comes with Node.js)
• pip 21.0 or higher (comes with Python)
• Docker & Docker Compose (optional, for containerized setup)
• PostgreSQL or SQLite (database)
• MongoDB 5.0+ (for document storage)
• Redis (optional, for caching and task queuing)
• API Keys:
  • Google Gemini API key OR OpenAI API key
  • MongoDB Atlas connection string

---

🚀 Installation

1. Clone the Repository

git clone https://github.com/yourusername/Logic_Legion_Finexa.git
cd Logic_Legion_Finexa

2. Backend Setup

Create Virtual Environment

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

Install Dependencies

pip install -r requirements.txt

Create Environment File

# Copy the example file
cp .env.example .env

# Edit .env with your configuration
nano .env

Run Migrations

python manage.py migrate

Create Superuser (Admin)

python manage.py createsuperuser

3. Frontend Setup

cd frontend
npm install

---

⚙️ Configuration

Backend Configuration (.env)

# Django Settings
DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1

# Database Configuration
DATABASE_ENGINE=django.db.backends.postgresql
DATABASE_NAME=finexa_db
DATABASE_USER=postgres
DATABASE_PASSWORD=your-password
DATABASE_HOST=localhost
DATABASE_PORT=5432

# MongoDB Configuration
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/finexa

# AI/LLM Configuration
OPENAI_API_KEY=sk-proj-your-key-here
GOOGLE_GEMINI_API_KEY=your-gemini-key-here

# Redis Configuration
REDIS_URL=redis://localhost:6379/0

# JWT Settings
JWT_SECRET_KEY=your-jwt-secret-key
JWT_ALGORITHM=HS256

# Email Configuration (Optional)
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

# Allowed Origins (CORS)
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# AWS S3 (Optional, for file storage)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_STORAGE_BUCKET_NAME=your-bucket-name

Frontend Configuration

Environment variables are handled in the API client (src/lib/api.ts):

const API_BASE_URL = process.env.REACT_APP_API_URL || 'http://localhost:8000/api';

---

▶️ Running the Project

Option 1: Manual Setup (Development)

Terminal 1 - Backend

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
python manage.py runserver 8000

Terminal 2 - Frontend

cd frontend
npm run dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000/api
• Admin Panel: http://localhost:8000/admin

Option 2: Docker Compose (Production-Ready)

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

# To stop services
docker-compose down

# View logs
docker-compose logs -f

Services will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/api
• PostgreSQL: localhost:5432
• MongoDB: localhost:27017
• Redis: localhost:6379

---

📚 API Documentation

Base URL

https://api.finexa.com/api/v1

Authentication

All API endpoints require JWT token in headers:

Authorization: Bearer <your-jwt-token>

Key Endpoints

Authentication

• POST /auth/register/ - Register new user
• POST /auth/login/ - Login and get JWT token
• POST /auth/refresh/ - Refresh JWT token
• POST /auth/logout/ - Logout user

Financial Data

• GET /finance/overview/ - Get dashboard overview with health score
• GET /finance/transactions/ - List all transactions
• POST /finance/transactions/ - Create new transaction
• GET /finance/health-score/ - Get detailed health score

Documents

• POST /documents/upload/ - Upload and process financial document
• GET /documents/ - List uploaded documents
• GET /documents/{id}/summary/ - Get document summary

AI Services

• POST /ai/chat/ - Chat with AI coach
• POST /ai/analyze/spending/ - Get spending analysis
• GET /ai/recommendations/ - Get recommendations
• POST /ai/extract-expenses/ - Extract expenses from document

Goals & Savings

• GET /goals/ - List all goals
• POST /goals/ - Create new goal
• PUT /goals/{id}/progress/ - Update goal progress
• DELETE /goals/{id}/ - Delete goal

Wallet

• GET /wallet/ - Get wallet balance
• GET /wallet/transactions/ - Get wallet transactions
• POST /wallet/transfer/ - Transfer funds

User Profile

• GET /user/profile/ - Get user profile
• PUT /user/profile/ - Update profile
• POST /user/settings/ - Update settings

For complete API documentation, see API_DOCS.txt

---

🗄️ Database Setup

PostgreSQL

# Create database
createdb finexa_db

# Create user
createuser finexa_user -P

# Grant privileges
psql -c "GRANT ALL PRIVILEGES ON DATABASE finexa_db TO finexa_user;"

MongoDB

The MongoDB collections are created automatically. Key collections:

• users - User profiles
• transactions - Transaction records
• documents - Uploaded documents and summaries
• expense_patterns - Spending analysis data
• financial_health - Health score history
• ai_conversations - Chat history with AI

Running Migrations

# Show pending migrations
python manage.py showmigrations

# Run all migrations
python manage.py migrate

# Create migration for changes
python manage.py makemigrations

# Reverse migration
python manage.py migrate <app-name> <migration-name>

---

🏗️ Project Architecture

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                       FRONTEND (React + TypeScript)             │
│                    Vite | Tailwind | Framer Motion             │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTP/WebSocket (Axios)
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    API GATEWAY & MIDDLEWARE                      │
│              JWT Auth | CORS | Request Validation               │
└────────────────────────────┬────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│   REST API       │ │  WebSocket       │ │  Admin Panel     │
│   (Django REST)  │ │  (Channels)      │ │  (Django Admin)  │
└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌────────────────┐   ┌────────────────┐   ┌────────────────┐
│  PostgreSQL    │   │   MongoDB      │   │   Redis        │
│  (Relational)  │   │  (NoSQL/Docs)  │   │  (Cache/Queue) │
└────────────────┘   └────────────────┘   └────────────────┘

External Services:
├── Google Gemini API (AI/LLM)
├── OpenAI GPT-4 (Expense Extraction)
├── Celery (Async Tasks)
└── Email Service (Notifications)

Data Flow

User Upload Document
        │
        ▼
Document Processing Service
        │
        ├─ Validate file format & size
        └─ Extract text using OCR
                  │
                  ▼
         Entity Recognition & Extraction
                  │
                  ├─ Date extraction
                  ├─ Amount extraction
                  ├─ Category classification
                  └─ Merchant identification
                  │
                  ▼
         Validation & Enrichment
                  │
                  ├─ Format validation
                  └─ Duplicate detection
                  │
                  ▼
         Store in Database
                  │
                  ├─ Save to MongoDB (documents)
                  ├─ Save to PostgreSQL (transactions)
                  └─ Update financial metrics
                  │
                  ▼
         Return Structured Response
                  │
                  └─ JSON with extracted expenses

---

💡 Features in Detail

1. Financial Health Score

Calculation Formula:

Health Score = (Income Stability × 20%) + (Expense Ratio × 25%) + 
               (Savings Rate × 25%) + (Debt-to-Income × 20%) + 
               (Emergency Buffer × 10%)

Score Ranges:

• 80-100: Excellent
• 60-79: Good
• 40-59: Fair
• 20-39: Poor
• 0-19: Critical

2. Expense Extraction

Powered by LLM (Google Gemini or OpenAI GPT-4), the system can:

• Extract expenses from bank statements (PDF/Image)
• Automatically categorize transactions
• Identify merchants and amounts
• Handle multiple date formats
• Detect and prevent duplicate entries

3. AI Coach

Conversational AI assistant that:

• Answers financial questions
• Provides personalized advice
• Suggests budget optimizations
• Explains financial concepts
• Tracks conversation history

4. Spending Analysis

Analyzes financial data to provide:

• Category-wise spending breakdown
• Trend detection (increases/decreases)
• Anomaly identification
• Benchmarking against user's own history
• Pattern-based recommendations

5. Goal Tracking

Users can:

• Create savings goals with targets
• Set monthly contribution amounts
• Track progress with visualizations
• Get achievement notifications
• Adjust goals dynamically

6. Gamification

• Habit Challenges: Daily/weekly financial tasks
• Achievement Badges: Earned for milestones
• Streak Tracking: Maintain positive financial behaviors
• Points System: Reward financial actions

---

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Write tests for new functionality
5. Submit a pull request

Code Standards

• Follow PEP 8 for Python
• Use TypeScript for frontend code
• Write meaningful commit messages
• Add documentation for new features

Testing

# Backend tests
python manage.py test

# Frontend tests
npm run test

# End-to-end tests (if applicable)
npm run test:e2e

---

📄 License

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

---

📞 Support & Contact

• Documentation: Backend README
• Issue Tracker: GitHub Issues
• Email: sakshi.s.nikam05@gmail.com

---

🙏 Acknowledgments

• Built with Django, React, and modern web technologies
• Powered by Google Gemini and OpenAI APIs
• Community contributions and feedback

---

📊 Project Status

• ✅ Core financial tracking functionality
• ✅ AI-powered expense extraction
• ✅ Health score calculation
• ✅ Goal tracking system
• ✅ Gamification features
• 🔄 Mobile app (In Progress)
• 🔄 Advanced analytics dashboard (In Progress)
• 🔄 Integration with banking APIs (Planned)
• 🔄 Multi-currency support enhancement (Planned)

---

🤝 Contributors

Sakshi

Sukhada

Atharva

Yash

---

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💜 Built with passion by the Logic Legion Team

Finexa © 2026 • All rights reserved

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━