FundN3xus - AI-Powered Financial Advisory Platform

Empowering smarter financial decisions through AI and Machine Learning

Quick Start

Option 1: Full Stack Development (Recommended)

# Clone the repository
git clone https://github.com/eyesee11/FundN3xus.git
cd FundN3xus

# Install frontend dependencies
npm install

# Set up ML backend environment
cd ml
pip install -r requirements.txt
cd ..

# Start both frontend and ML backend simultaneously  
npm run dev:full

Option 2: Frontend Only

npm install
npm run dev        # Starts on http://localhost:9002

Option 3: Individual Services

# Terminal 1: Start Next.js frontend
npm run dev        # http://localhost:9002

# Terminal 2: Start ML API backend  
npm run dev:ml     # http://localhost:8000

Access Points:

Web Application: http://localhost:9002
ML API Server: http://localhost:8000
API Documentation: http://localhost:8000/docs
Interactive API: http://localhost:8000/redoc

(Note: The deployed backend and Huggingface ML backend APIs are private. Please contact the maintainer to gain access.)

Overview

FundN3xus is a cutting-edge financial advisory platform that combines modern web technologies with advanced machine learning to provide personalized financial insights. Built with a focus on user experience and data-driven recommendations, FundN3xus helps individuals make informed financial decisions through AI-powered analysis.

What Makes FundN3xus Special

AI-First Approach: Four specialized ML models trained on 15,000+ synthetic financial records
Modern UX: Responsive, intuitive interface built with Next.js and Tailwind CSS
Privacy-Focused: Secure data handling with Firebase authentication and encryption
Multilingual: Full English/Hindi support with seamless language switching
Real-Time: Instant financial predictions and recommendations
Production-Ready: Fully functional ML API with comprehensive documentation

Key Features

AI-Powered Financial Intelligence

Investment Risk Assessment: ML-driven risk tolerance analysis with personalized scoring
Affordability Calculator: Intelligent purchase capacity analysis based on income, expenses, and goals
Financial Health Scoring: Real-time health assessment with actionable improvement recommendations
Scenario Planning: AI-powered strategic recommendations for different financial scenarios
Smart Chatbot: Conversational AI financial advisor with context-aware responses

Modern Web Experience

Interactive Dashboard: Comprehensive financial overview with dynamic charts and insights
Multilingual Interface: Seamless English/Hindi switching with cultural financial context
Responsive Design: Mobile-first approach ensuring optimal experience across all devices
Real-Time Updates: Live financial data processing with instant feedback
Modern UI: Clean, intuitive interface built with shadcn/ui components

Security & Authentication

Firebase Auth: Secure authentication with Google Sign-In and email/password
Data Encryption: Bank-level security for sensitive financial information
Environment Security: Secure API key management and configuration
Privacy Controls: User-controlled data sharing and privacy settings

Financial Management Tools

Portfolio Analytics: Comprehensive investment performance tracking and analysis
Transaction Management: Automated categorization and expense tracking
Goal Setting: Financial target planning with milestone tracking
Net Worth Calculator: Complete wealth assessment including assets and liabilities
Portfolio Rebalancing: AI-driven optimization suggestions based on risk tolerance

Tech Stack

Frontend & UI

Technology	Version	Purpose
Next.js	15.3.3	React framework with App Router and server-side rendering
TypeScript	5.0+	Type-safe JavaScript with enhanced developer experience
Tailwind CSS	3.4+	Utility-first CSS framework for rapid UI development
shadcn/ui	Latest	High-quality, accessible React components
Framer Motion	12.23+	Smooth animations and micro-interactions
React Hook Form	7.54+	Performant forms with easy validation
Recharts	2.15+	Responsive charts built on D3.js

Backend & AI

Technology	Version	Purpose
FastAPI	0.104.1	Modern, fast web framework for building ML APIs
Python	3.10+	Core language for ML backend and data processing
XGBoost	2.1.1	Gradient boosting framework for ML models
Scikit-learn	1.5.2	Machine learning library for data analysis
Imbalanced-learn	0.12.4	Tools for handling imbalanced datasets
Google Genkit	1.14+	AI flow orchestration and prompt management
Gemini AI	Latest	Large language model for conversational AI

Database & Authentication

Technology	Version	Purpose
Firebase	11.10.0	Backend-as-a-Service for auth and database
Firestore	Latest	NoSQL document database for user data
Firebase Auth	Latest	Authentication with multiple providers

Development & Build Tools

Technology	Version	Purpose
Node.js	18+	JavaScript runtime for build tools and server
npm/yarn	Latest	Package management and dependency resolution
ESLint	Latest	Code linting and quality enforcement
Prettier	Latest	Code formatting and style consistency
Concurrently	8.2.2	Run multiple commands simultaneously

Architecture

graph TB
    subgraph "Frontend (Next.js)"
      A[React Components] --> B[Tailwind UI]
      A --> C[Context Providers]
      C --> D[Firebase Auth]
      A --> E[API Clients]
    end
    subgraph "Backend Services"
      E --> F[ML API Server]
      E --> G[Next.js API Routes]
      F --> H[ML Models]
      G --> I[Firebase Services]
    end
    subgraph "Data Layer"
      H --> J[Trained Models]
      I --> K[Firestore DB]
      I --> L[Firebase Auth]
    end
    subgraph "External APIs"
      E --> M[Google Gemini]
      G --> N[Email Service]
    end

Data Flow

User Input: Financial data entered through React forms
Validation: Client-side validation with Zod schemas
ML Processing: Data sent to FastAPI backend for predictions
AI Enhancement: Results enriched with Gemini AI insights
Storage: User preferences saved to Firestore
Visualization: Results displayed with interactive charts

Project Structure

FundN3xus/
├── README.md                     # Project documentation
├── package.json                  # Node.js dependencies and scripts
├── next.config.ts                # Next.js configuration
├── tailwind.config.ts            # Tailwind CSS configuration
├── tsconfig.json                 # TypeScript configuration
├── components.json               # shadcn/ui component configuration
├── apphosting.yaml               # Firebase App Hosting config
├── postcss.config.mjs            # PostCSS configuration
│
├── src/                          # Frontend Application Source
│   ├── app/                      # Next.js App Router
│   │   ├── globals.css           # Global styles and CSS variables
│   │   ├── layout.tsx            # Root layout with providers
│   │   ├── page.tsx              # Landing page component
│   │   ├── (main)/               # Protected main application routes
│   │   │   ├── layout.tsx        # Main app layout with sidebar
│   │   │   ├── dashboard/        # Financial overview and insights
│   │   │   ├── investments/      # Portfolio management tools
│   │   │   ├── affordability/    # Purchase analysis calculator
│   │   │   ├── scenarios/        # Financial planning scenarios
│   │   │   ├── ai-chat/          # AI chatbot interface
│   │   │   ├── profile/          # User settings and preferences
│   │   │   └── settings/         # App configuration
│   │   ├── api/                  # Server-side API routes
│   │   │   ├── ai/               # AI and ML integration endpoints
│   │   │   ├── contact/          # Contact form handling
│   │   │   └── send-welcome-email/ # Email service integration
│   │   ├── login/                # Authentication pages
│   │   └── demo/                 # Demo and testing pages
│   ├── components/               # React Components Library
│   │   ├── ui/                   # Base shadcn/ui components
│   │   ├── dashboard/            # Dashboard-specific components
│   │   │   └── command-center-dashboard.tsx
│   │   ├── investments/          # Investment management components
│   │   │   ├── investments-client-page.tsx
│   │   │   ├── portfolio-overview.tsx
│   │   │   └── rebalancing-tool.tsx
│   │   ├── affordability/        # Affordability analysis components
│   │   │   ├── affordability-analyzer.tsx
│   │   │   └── affordability-client-page.tsx
│   │   ├── scenarios/            # Financial scenario components
│   │   ├── profile/              # User profile components
│   │   ├── auth/                 # Authentication components
│   │   ├── landing/              # Landing page components
│   │   ├── layout/               # Layout and navigation components
│   │   └── shared/               # Reusable shared components
│   ├── lib/                      # Utilities and Configuration
│   │   ├── utils.ts              # General utility functions
│   │   ├── firebase.ts           # Firebase SDK configuration
│   │   ├── ml-api.ts             # ML API client and types
│   │   ├── groq.ts               # Groq API integration
│   │   ├── financial-utils.ts    # Financial calculation utilities
│   │   ├── types.ts              # TypeScript type definitions
│   │   └── mock-data.ts          # Development mock data
│   ├── ai/                       # AI Integration Layer
│   │   ├── config.ts             # AI service configuration
│   │   ├── mcp-service.ts        # Model Context Protocol service
│   │   └── flows/                # AI Flow Definitions
│   │       ├── affordability-analysis.ts
│   │       ├── analyze-financial-trends.ts
│   │       ├── financial-advisor-chatbot.ts
│   │       ├── investment-rebalancing-suggestions.ts
│   │       └── simulate-financial-scenarios.ts
│   ├── contexts/                 # React Context Providers
│   │   ├── auth-context.tsx      # Authentication state management
│   │   └── language-context.tsx  # Internationalization context
│   └── hooks/                    # Custom React Hooks
│       ├── use-profile.ts        # User profile data hook
│       ├── use-mobile.tsx        # Mobile device detection
│       ├── use-toast.ts          # Toast notification hook
│       ├── use-text-to-speech.ts # Text-to-speech functionality
│       └── use-voice-assistant.ts # Voice assistant integration
│
├── ml/                           # Machine Learning Backend
│   ├── server.py                 # FastAPI ML server application
│   ├── train_model.py            # ML model training pipeline
│   ├── requirements.txt          # Python dependencies
│   ├── dataset.csv               # Training dataset (15,000+ records)
│   ├── rag_pipeline_pinecone.py  # RAG pipeline
│   ├── rag_server.py             # RAG server
│   ├── train_rag_embeddings.py   # RAG embeddings training
│   ├── models/                   # Trained ML Models
│   │   ├── investment_risk_model.pkl
│   │   ├── affordability_model.pkl
│   │   ├── health_score_model.pkl
│   │   └── scenario_planner_model.pkl
│   └── __pycache__/              # Python bytecode cache
│
└── public/                       # Static Assets
  ├── favicon.ico               # Website favicon
  ├── banner.png                # Main application banner
  ├── banner2.png               # Secondary banner
  └── bannerLogin.svg           # Login page banner
│   ├── � README.md                 # ML backend documentation
│   │
│   ├── �📁 models/                   # 🧠 Trained ML Models
│   │   ├── 📄 investment_risk_model.pkl      # Investment risk predictor
│   │   ├── 📄 affordability_model.pkl        # Affordability analyzer  
│   │   ├── 📄 health_score_model.pkl         # Financial health scorer
│   │   └── 📄 scenario_planner_model.pkl     # Scenario planning model
│   │
│   └── 📁 __pycache__/              # Python bytecode cache
│
└── 📁 public/                       # 🎨 Static Assets
    ├── � favicon.ico               # Website favicon
    ├── 📄 banner.png                # Main application banner
    ├── 📄 banner2.png               # Secondary banner
    └── 📄 bannerLogin.svg           # Login page banner

Directory Breakdown

Directory	Purpose	Key Files
`src/app/`	Next.js App Router pages and API routes	layout.tsx, page.tsx, API routes
`src/components/`	Reusable React components organized by feature	UI components, feature modules
`src/lib/`	Utility functions, configurations, and API clients	ml-api.ts, firebase.ts, utils.ts
`src/ai/`	AI integration layer with Genkit flows	AI flows, configurations
`ml/`	Python ML backend with FastAPI server	server.py, trained models
`public/`	Static assets served directly	Images, icons, logos

Installation Guide

Prerequisites

Before getting started, ensure you have the following installed:

Tool	Minimum Version	Purpose
Node.js	18.0+	JavaScript runtime for frontend
npm/yarn	8.0+ / 1.22+	Package management
Python	3.10+	ML backend runtime
pip	21.0+	Python package installer
Git	2.30+	Version control

🚀 Step-by-Step Setup

1. Clone Repository

# HTTPS (recommended)
git clone https://github.com/eyesee11/FundN3xus.git

# Or SSH (if configured)  
git clone git@github.com:eyesee11/FundN3xus.git

cd FundN3xus

2. Frontend Setup

# Install Node.js dependencies
npm install

# Or using Yarn
yarn install

# Verify installation
npm run typecheck

3. ML Backend Setup

# Navigate to ML directory
cd ml

# Create Python virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# Windows
venv\Scripts\activate
# macOS/Linux  
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Return to project root
cd ..

4. Environment Configuration

# Copy environment template
cp .env.example .env.local

# Edit environment variables (see Configuration section)
# Use your preferred text editor
code .env.local

5. Initialize ML Models

# Train ML models (optional - auto-runs on first API start)
npm run train

# Or manually
cd ml && python train_model.py

6. Start Development Servers

# Option A: Start both frontend and ML backend
npm run dev:full

# Option B: Start individually
# Terminal 1
npm run dev        # Frontend: http://localhost:9002

# Terminal 2  
npm run dev:ml     # ML API: http://localhost:8000

✅ Verify Installation

Frontend: Visit http://localhost:9002 - should show FundN3xus landing page
ML API: Visit http://localhost:8000/docs - should show FastAPI documentation
Health Check: Visit http://localhost:8000/health - should return JSON status

🔧 Troubleshooting

Common Issues

Node.js Dependency Issues

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Python Environment Issues

# Upgrade pip and reinstall
python -m pip install --upgrade pip
pip install -r ml/requirements.txt --force-reinstall

Port Conflicts

# Check what's running on ports
netstat -an | findstr :9002
netstat -an | findstr :8000

# Kill processes if needed (Windows)
taskkill /F /PID <process_id>

ML Model Training Issues

# Check Python version and dependencies
python --version
pip list

# Retrain models with verbose output
cd ml && python train_model.py --verbose

⚙️ Configuration

🔐 Environment Variables Setup

Create a .env.local file in the project root with the following configuration:

# ===================================
# 🔥 FIREBASE CONFIGURATION
# ===================================
# Get these from Firebase Console > Project Settings > General
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abcdef123456
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-ABCDEF1234

# ===================================
# 🤖 AI & ML CONFIGURATION  
# ===================================
# Google AI Studio API Key for Gemini
GEMINI_API_KEY=your_gemini_api_key_here
GOOGLE_GENAI_API_KEY=your_gemini_api_key_here
GOOGLE_AI_API_KEY=your_gemini_api_key_here

# ML API Server Configuration
NEXT_PUBLIC_ML_API_URL=http://localhost:8000
ML_API_TIMEOUT=30000

# ===================================
# 📧 EMAIL SERVICE CONFIGURATION
# ===================================
# SMTP Configuration (Gmail example)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_specific_password
SMTP_FROM=FundN3xus <your_email@gmail.com>
SMTP_TO=support@FundN3xus.app

# ===================================
# 🔒 SECURITY & AUTHENTICATION
# ===================================
# Next.js Authentication
NEXTAUTH_URL=http://localhost:9002
NEXTAUTH_SECRET=your_super_secret_key_minimum_32_chars

# JWT Configuration (optional)
JWT_SECRET=another_super_secret_key_for_jwt_tokens

# ===================================
# 🚀 APPLICATION CONFIGURATION
# ===================================
# App Environment
NODE_ENV=development
NEXT_PUBLIC_APP_ENV=development
NEXT_PUBLIC_APP_VERSION=1.0.0

# Feature Flags
NEXT_PUBLIC_ENABLE_ANALYTICS=false
NEXT_PUBLIC_ENABLE_DEBUG_MODE=true
FundN3xus_ENABLE_PRETRAINED_MODEL=true
FundN3xus_ENABLE_MCP_SERVER=false

# ===================================
# 🌐 API ENDPOINTS
# ===================================
NEXT_PUBLIC_API_BASE_URL=http://localhost:9002/api
NEXT_PUBLIC_WEBAPP_URL=http://localhost:9002

🔑 Getting API Keys

Firebase Setup

Go to Firebase Console
Create a new project or select existing
Navigate to Project Settings → General
Copy configuration values to .env.local
Enable Authentication → Sign-in methods → Google & Email/Password
Create Firestore Database in production mode
Set up Security Rules (see Firebase section below)

Google AI (Gemini) Setup

Visit Google AI Studio
Sign in with Google account
Click Get API Key → Create API Key
Copy the key to GEMINI_API_KEY in .env.local
Enable billing for higher quotas (optional)

Email Service Setup (Gmail)

Enable 2-Factor Authentication on your Gmail account
Generate App Password: Google Account → Security → App Passwords
Use your Gmail address for SMTP_USER
Use the generated app password for SMTP_PASS

🔥 Firebase Security Rules

Add these security rules to your Firestore database:

// Firestore Security Rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users can only access their own data
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
    
    // Public data (if any)
    match /public/{document} {
      allow read: if true;
      allow write: if request.auth != null;
    }
    
    // Financial profiles - user specific
    match /profiles/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

🔧 Development vs Production

Development Environment

NODE_ENV=development
NEXT_PUBLIC_APP_ENV=development
NEXT_PUBLIC_ML_API_URL=http://localhost:8000
NEXT_PUBLIC_WEBAPP_URL=http://localhost:9002
NEXT_PUBLIC_ENABLE_DEBUG_MODE=true

Production Environment

NODE_ENV=production
NEXT_PUBLIC_APP_ENV=production  
NEXT_PUBLIC_ML_API_URL=https://your-ml-api.railway.app
NEXT_PUBLIC_WEBAPP_URL=https://FundN3xus.vercel.app
NEXT_PUBLIC_ENABLE_DEBUG_MODE=false

🔒 Security Best Practices

Never commit .env.local to version control
Use different Firebase projects for development/production
Rotate API keys regularly (quarterly recommended)
Enable Firebase Security Rules before going live
Use HTTPS in production for all API endpoints
Set up monitoring for API usage and errors

⚡ Performance Configuration

# Next.js Performance
NEXT_PUBLIC_ENABLE_SW=true  # Service Worker
NEXT_PUBLIC_ENABLE_PWA=true # Progressive Web App

# ML API Performance  
ML_API_CACHE_TTL=300        # Cache responses for 5 minutes
ML_API_MAX_RETRIES=3        # Maximum retry attempts
ML_API_TIMEOUT=30000        # 30 second timeout

👩‍💻 Development

🛠️ Available Scripts

Command	Purpose	Environment
`npm run dev`	Start Next.js frontend only	http://localhost:9002
`npm run dev:ml`	Start ML API server only	http://localhost:8000
`npm run dev:full`	Start both frontend & ML backend	Both ports
`npm run build`	Build production frontend	-
`npm run start`	Start production frontend	http://localhost:9002
`npm run lint`	Run ESLint code analysis	-
`npm run typecheck`	TypeScript type checking	-
`npm run train`	Train/retrain ML models	-
`npm run setup:ml`	Install ML dependencies	-

🔄 Development Workflow

1. Feature Development Process

# 1. Create feature branch
git checkout -b feature/new-financial-tool

# 2. Start development environment
npm run dev:full

# 3. Make changes with hot reloading
# - Frontend: src/ directory changes auto-reload
# - ML Backend: Restart required for server.py changes

# 4. Test changes
npm run typecheck
npm run lint

# 5. Commit and push
git add .
git commit -m "feat: add new financial analysis tool"
git push origin feature/new-financial-tool

2. Component Development

# Create new component using shadcn/ui
npx shadcn-ui@latest add component-name

# Component structure
src/components/
  ├── ui/                  # Base components (buttons, cards, etc.)
  ├── feature-name/        # Feature-specific components
  └── shared/              # Reusable components

3. ML Model Development

# Modify training pipeline
cd ml
python train_model.py --help  # See available options

# Test new model predictions
python -c "
import joblib
model = joblib.load('models/new_model.pkl')
# Test prediction logic
"

# Update API endpoints in server.py
# Restart ML server: npm run dev:ml

🏗️ Project Architecture Patterns

Frontend Architecture

App Router: File-based routing with layout compositions
Component Composition: Reusable components with clear interfaces
Context Providers: Global state management for auth and settings
Custom Hooks: Reusable logic for API calls and state management
Type Safety: Full TypeScript coverage with strict mode

Backend Architecture

FastAPI: Async API framework with automatic OpenAPI docs
Model Abstraction: Centralized model loading and prediction logic
Error Handling: Comprehensive error responses with logging
CORS Configuration: Secure cross-origin resource sharing setup

📝 Code Standards & Best Practices

TypeScript Guidelines

// ✅ Good: Explicit types and interfaces
interface UserProfile {
  id: string;
  name: string;
  financialGoals: FinancialGoal[];
}

// ✅ Good: Type-safe API calls
async function fetchUserData(userId: string): Promise<UserProfile> {
  // Implementation
}

// ❌ Avoid: Any types
const userData: any = await fetchData();

React Component Guidelines

// ✅ Good: Props interface with JSDoc
interface FinancialCardProps {
  /** User's financial data */
  data: FinancialData;
  /** Called when user updates data */
  onUpdate: (data: FinancialData) => void;
  /** Additional CSS classes */
  className?: string;
}

export function FinancialCard({ data, onUpdate, className }: FinancialCardProps) {
  // Component implementation
}

Python ML Guidelines

# ✅ Good: Type hints and docstrings
from typing import Dict, List, Optional
import pandas as pd

def predict_investment_risk(
    profile_data: Dict[str, float],
    model_path: str = "models/investment_risk_model.pkl"
) -> Dict[str, float]:
    """
    Predict investment risk score for user profile.
    
    Args:
        profile_data: User financial profile data
        model_path: Path to trained model file
        
    Returns:
        Dictionary with risk score and confidence
    """
    # Implementation

🧪 Development Tools

VS Code Extensions (Recommended)

{
  "recommendations": [
    "bradlc.vscode-tailwindcss",
    "ms-python.python",
    "ms-python.black-formatter",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "ms-playwright.playwright"
  ]
}

Git Hooks (Optional)

# Install pre-commit hooks
npm install --save-dev husky lint-staged

# Add to package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{py}": ["black", "isort"]
  }
}

🔍 Debugging

Frontend Debugging

# Enable React Developer Tools
# Install browser extension: React Developer Tools

# Debug API calls
console.log('API Response:', response.data);

# Use Next.js debug mode
DEBUG=* npm run dev

ML Backend Debugging

# Add logging to server.py
import logging
logging.basicConfig(level=logging.DEBUG)

# Debug model predictions
print(f"Model input: {input_data}")
print(f"Model output: {prediction}")

# Test individual endpoints
curl -X POST "http://localhost:8000/predict/investment-risk" \
  -H "Content-Type: application/json" \
  -d '{"age": 30, "income": 75000}'

📊 Performance Optimization

Frontend Performance

// Lazy load heavy components
const MLAnalyzer = lazy(() => import('./ml-investment-risk-analyzer'));

// Optimize images
import Image from 'next/image';
<Image
  src="/banner.png"
  alt="FundN3xus Banner"
  width={800}
  height={400}
  priority
/>

// Memoize expensive calculations
const expensiveValue = useMemo(() => {
  return calculateComplexFinancialData(userData);
}, [userData]);

ML Backend Performance

# Model caching
@lru_cache(maxsize=1)
def load_model(model_path: str):
    return joblib.load(model_path)

# Async endpoints
@app.post("/predict/async")
async def async_prediction(data: PredictionRequest):
    # Non-blocking prediction logic
    return await process_prediction(data)

🧭 Development Tips

Hot Reloading: Frontend changes auto-reload, but ML server requires restart
Type Checking: Run npm run typecheck frequently during development
API Testing: Use http://localhost:8000/docs for interactive API testing
Component Testing: Test components in isolation using Storybook (optional)
Mobile Testing: Use browser dev tools for responsive design testing
Error Boundaries: Wrap components in error boundaries for better UX

🤖 ML Models & API

FundN3xus's machine learning backend provides four specialized models trained on financial data, accessible via a production-ready FastAPI server.

🧠 Machine Learning Models

Model	Type	Performance	Features	Use Case
Investment Risk	XGBoost Regression	R² > 0.35	Age, Income, Goals, Timeline	Risk tolerance assessment
Affordability Analysis	XGBoost Regression	R² > 0.99	Income, Expenses, Debt, Savings	Purchase capacity evaluation
Financial Health	XGBoost Regression	R² > 0.99	Multiple financial factors	Overall health scoring
Scenario Planning	XGBoost Classification	99.9% Accuracy	SMOTE balanced dataset	Strategy recommendations

📊 Model Training Details

Dataset Information

Size: 15,000+ synthetic financial records
Features: 10-15 features per model (age, income, expenses, savings, etc.)
Generation: Realistic financial scenarios with proper correlations
Balancing: SMOTE technique applied for classification models
Validation: Train/test split with cross-validation

Model Pipeline

# Training Pipeline Overview
1. Data Loading & Preprocessing
   ├── Load dataset.csv (15,000+ records)
   ├── Handle missing values
   ├── Feature scaling/normalization
   └── Train/test split (80/20)

2. Model Training
   ├── XGBoost hyperparameter tuning
   ├── Cross-validation (5-fold)
   ├── Feature importance analysis
   └── Model serialization (.pkl files)

3. Model Evaluation
   ├── Regression: R², MAE, RMSE
   ├── Classification: Accuracy, F1, Precision, Recall
   ├── Feature importance plots
   └── Prediction confidence intervals

🌐 API Endpoints

Base URL: `http://localhost:8000`

Endpoint	Method	Purpose	Input	Output
`/health`	GET	Health check & model status	-	Server status
`/predict/investment-risk`	POST	Investment risk scoring	Profile data	Risk score (0-10)
`/predict/affordability`	POST	Purchase affordability	Financial data	Affordability score
`/predict/financial-health`	POST	Overall financial health	Complete profile	Health score & tips
`/predict/scenario`	POST	Financial planning	Goals & constraints	Strategy recommendations

📝 API Usage Examples

Investment Risk Prediction

curl -X POST "http://localhost:8000/predict/investment-risk" \
  -H "Content-Type: application/json" \
  -d '{
    "age": 35,
    "income": 85000,
    "savings": 50000,
    "debt": 25000,
    "investment_amount": 10000,
    "risk_tolerance": "moderate",
    "investment_timeline": 10
  }'

Response:

{
  "risk_score": 6.8,
  "risk_category": "Moderate-High",
  "confidence": 0.92,
  "recommendations": [
    "Consider diversified portfolio",
    "Allocate 30% to bonds for stability"
  ],
  "model_version": "1.0.0"
}

Affordability Analysis

curl -X POST "http://localhost:8000/predict/affordability" \
  -H "Content-Type: application/json" \
  -d '{
    "income": 75000,
    "expenses": 4500,
    "savings": 30000,
    "debt": 15000,
    "purchase_price": 250000,
    "down_payment": 50000
  }'

Response:

{
  "affordability_score": 7.2,
  "can_afford": true,
  "monthly_payment_capacity": 2100,
  "recommendations": [
    "Comfortable purchase within budget",
    "Consider 20% down payment"
  ],
  "stress_test": {
    "interest_rate_increase": "Still affordable at +2%",
    "income_reduction": "Risk at -15% income"
  }
}

🔧 Model Performance & Monitoring

Performance Metrics

# Model Evaluation Results
Investment Risk Model:
├── R² Score: 0.354
├── Mean Absolute Error: 0.89
├── Root Mean Square Error: 1.12
└── Cross-validation Score: 0.341 ± 0.023

Affordability Model:
├── R² Score: 0.998
├── Mean Absolute Error: 0.034
├── Root Mean Square Error: 0.067
└── Cross-validation Score: 0.997 ± 0.001

Financial Health Model:
├── R² Score: 0.992
├── Mean Absolute Error: 0.078
├── Root Mean Square Error: 0.156
└── Cross-validation Score: 0.991 ± 0.002

Scenario Planning Model:
├── Accuracy: 99.9%
├── Precision: 99.8%
├── Recall: 99.9%
├── F1-Score: 99.8%
└── Cross-validation Accuracy: 99.7% ± 0.1%

🚀 Model Training & Retraining

Training New Models

# Full model retraining
cd ml
python train_model.py

# Training with custom parameters
python train_model.py --n_estimators 200 --max_depth 8 --learning_rate 0.1

# Training specific model
python train_model.py --model investment_risk

# Verbose training output
python train_model.py --verbose

Adding New Models

# 1. Add training logic in train_model.py
def train_new_model(df):
    # Feature engineering
    features = ['feature1', 'feature2', 'feature3']
    X = df[features]
    y = df['target']
    
    # Model training
    model = XGBRegressor(
        n_estimators=100,
        max_depth=6,
        learning_rate=0.1,
        random_state=42
    )
    
    model.fit(X, y)
    return model

# 2. Add API endpoint in server.py
@app.post("/predict/new-model")
async def predict_new_model(request: NewModelRequest):
    try:
        model = load_model("models/new_model.pkl")
        prediction = model.predict([request.features])
        return {"prediction": prediction[0]}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

📊 Feature Importance

Investment Risk Model Features

Investment Timeline (0.25) - Most important factor
Age (0.18) - Life stage considerations
Income Stability (0.16) - Financial security
Current Savings (0.15) - Financial cushion
Debt-to-Income Ratio (0.12) - Financial obligations
Previous Investment Experience (0.14) - Knowledge factor

Model Interpretability

# Feature importance visualization
import matplotlib.pyplot as plt
from xgboost import plot_importance

# Load trained model
model = joblib.load('models/investment_risk_model.pkl')

# Plot feature importance
plot_importance(model, max_num_features=10)
plt.title('Investment Risk Model - Feature Importance')
plt.show()

🔄 API Integration in Frontend

TypeScript API Client (`src/lib/ml-api.ts`)

interface MLApiResponse<T> {
  success: boolean;
  data: T;
  error?: string;
  model_version: string;
}

export async function predictInvestmentRisk(
  profileData: InvestmentRiskRequest
): Promise<InvestmentRiskResponse> {
  const response = await fetch(`${ML_API_BASE_URL}/predict/investment-risk`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(profileData)
  });
  
  if (!response.ok) {
    throw new Error(`ML API Error: ${response.statusText}`);
  }
  
  return response.json();
}

🐛 Troubleshooting ML Issues

Common Issues & Solutions

Model Not Found Error

# Check if models directory exists and contains .pkl files
ls -la ml/models/

# Retrain models if missing
cd ml && python train_model.py

Prediction Errors

# Check input data format
print("Input data:", json.dumps(request_data, indent=2))

# Validate feature names and types
expected_features = ['age', 'income', 'savings']  # etc.

Performance Issues

# Model loading optimization
from functools import lru_cache

@lru_cache(maxsize=4)  # Cache all 4 models
def load_model(model_path: str):
    return joblib.load(model_path)

🧪 Testing

🧪 Testing Strategy

FundN3xus employs a comprehensive testing approach covering frontend components, API endpoints, and ML model validation.

Test Types Coverage

Unit Tests: Individual functions and components
Integration Tests: API endpoints and data flows
E2E Tests: Complete user workflows
ML Model Tests: Prediction accuracy and performance
Visual Regression: UI consistency across updates

🔧 Frontend Testing

Testing Framework Setup

# Install testing dependencies
npm install --save-dev @testing-library/react @testing-library/jest-dom jest jest-environment-jsdom

# Install Playwright for E2E tests
npm install --save-dev @playwright/test
npx playwright install

Jest Configuration (`jest.config.js`)

const nextJest = require('next/jest')

const createJestConfig = nextJest({
  dir: './',
})

const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  moduleNameMapping: {
    '^@/(.*)$': '<rootDir>/src/$1',
  },
  testEnvironment: 'jest-environment-jsdom',
}

module.exports = createJestConfig(customJestConfig)

Component Testing Examples

// src/components/__tests__/FinancialHealthSummary.test.tsx
import { render, screen } from '@testing-library/react'
import { FinancialHealthSummary } from '../dashboard/financial-health-summary'

const mockHealthData = {
  score: 8.5,
  category: 'Excellent',
  recommendations: ['Maintain current savings rate']
}

describe('FinancialHealthSummary', () => {
  it('renders health score correctly', () => {
    render(<FinancialHealthSummary data={mockHealthData} />)
    
    expect(screen.getByText('8.5')).toBeInTheDocument()
    expect(screen.getByText('Excellent')).toBeInTheDocument()
  })

  it('displays recommendations', () => {
    render(<FinancialHealthSummary data={mockHealthData} />)
    
    expect(screen.getByText('Maintain current savings rate')).toBeInTheDocument()
  })
})

🤖 ML Backend Testing

Model Testing (`ml/test_models.py`)

import unittest
import numpy as np
import pandas as pd
from server import load_model, predict_investment_risk

class TestMLModels(unittest.TestCase):
    
    def setUp(self):
        """Set up test data"""
        self.test_profile = {
            "age": 35,
            "income": 80000,
            "savings": 40000,
            "debt": 20000,
            "investment_amount": 15000
        }
    
    def test_investment_risk_model_loads(self):
        """Test that investment risk model loads correctly"""
        model = load_model("models/investment_risk_model.pkl")
        self.assertIsNotNone(model)
    
    def test_investment_risk_prediction_range(self):
        """Test that predictions are within expected range"""
        prediction = predict_investment_risk(self.test_profile)
        
        self.assertIsInstance(prediction, dict)
        self.assertIn("risk_score", prediction)
        self.assertTrue(0 <= prediction["risk_score"] <= 10)

if __name__ == '__main__':
    unittest.main()

Running Tests

# Frontend Tests
npm test                    # Run all tests
npm run test:coverage       # Run with coverage
npx playwright test         # Run E2E tests

# ML Backend Tests
cd ml
python -m pytest test_models.py -v
python -m pytest test_api.py -v

🚀 Deployment

🌐 Frontend Deployment Options

Vercel (Recommended)

Vercel provides seamless Next.js deployment with automatic CI/CD.

# Install Vercel CLI
npm install -g vercel

# Login to Vercel
vercel login

# Deploy to Vercel
vercel

# Set environment variables in Vercel dashboard
# Import from .env.local: Project Settings > Environment Variables

Vercel Configuration (vercel.json):

{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",
  "env": {
    "NEXT_PUBLIC_ML_API_URL": "https://your-ml-api.railway.app"
  }
}

Netlify Alternative

# Build command: npm run build
# Publish directory: .next
# Environment variables: Set in Netlify dashboard

# netlify.toml
[build]
  command = "npm run build"
  publish = ".next"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

🤖 ML Backend Deployment

Railway (Recommended for ML)

Railway provides Python environment with good ML library support.

# Install Railway CLI
npm install -g @railway/cli

# Login and initialize
railway login
railway init

# Deploy ML backend
cd ml
railway up

Railway Configuration (railway.toml):

[build]
nixPacks = true

[deploy]
startCommand = "python server.py"
healthcheckPath = "/health"
healthcheckTimeout = 300

[env]
PYTHON_VERSION = "3.11"
PORT = "8000"

Heroku Alternative

# Create Procfile in ml/ directory
echo "web: python server.py" > ml/Procfile

# Create runtime.txt
echo "python-3.11" > ml/runtime.txt

# Deploy to Heroku
cd ml
heroku create FundN3xus-ml-api
git subtree push --prefix ml heroku main

Docker Deployment

# Dockerfile for ML backend
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY ml/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY ml/ .

# Expose port
EXPOSE 8000

# Run server
CMD ["python", "server.py"]

🏗️ Full Stack Deployment

Multi-Service Architecture

# docker-compose.yml
version: '3.8'

services:
  frontend:
    build: 
      context: .
      dockerfile: Dockerfile.frontend
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_ML_API_URL=http://ml-backend:8000
    depends_on:
      - ml-backend

  ml-backend:
    build:
      context: ./ml
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - ./ml/models:/app/models

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - frontend
      - ml-backend

☁️ Cloud Platform Deployments

Google Cloud Platform

# App Engine deployment
# app.yaml for frontend
runtime: nodejs18
service: frontend
env_variables:
  NEXT_PUBLIC_ML_API_URL: https://ml-api-service.appspot.com

# app.yaml for ML backend  
runtime: python311
service: ml-api
env_variables:
  PORT: 8080

AWS Deployment

# Frontend: AWS Amplify
amplify init
amplify add hosting
amplify publish

# ML Backend: AWS Lambda + API Gateway
# Use serverless framework
npm install -g serverless
serverless create --template aws-python3 --path FundN3xus-ml

Azure Deployment

# Frontend: Azure Static Web Apps
az staticwebapp create \
  --name FundN3xus-frontend \
  --resource-group FundN3xus-rg \
  --source https://github.com/your-username/FundN3xus \
  --location "East US 2"

# ML Backend: Azure Container Instances
az container create \
  --resource-group FundN3xus-rg \
  --name FundN3xus-ml \
  --image your-registry/FundN3xus-ml:latest \
  --ports 8000

🔧 Environment Configuration

Production Environment Variables

# Production .env.production
NODE_ENV=production
NEXT_PUBLIC_APP_ENV=production

# Updated URLs for production
NEXT_PUBLIC_ML_API_URL=https://FundN3xus-ml.railway.app
NEXT_PUBLIC_WEBAPP_URL=https://FundN3xus.vercel.app

# Production Firebase project
NEXT_PUBLIC_FIREBASE_PROJECT_ID=FundN3xus-prod
NEXT_PUBLIC_FIREBASE_API_KEY=your_prod_api_key

# Production security
NEXTAUTH_SECRET=your_super_secure_production_secret
JWT_SECRET=another_secure_production_secret

# Disable debug features
NEXT_PUBLIC_ENABLE_DEBUG_MODE=false
NEXT_PUBLIC_ENABLE_ANALYTICS=true

📊 Monitoring & Analytics

Application Monitoring

# Add Vercel Analytics
npm install @vercel/analytics

# Add to _app.tsx
import { Analytics } from '@vercel/analytics/react'

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Analytics />
    </>
  )
}

ML API Monitoring

# Add to server.py
import logging
from prometheus_client import Counter, Histogram
import time

# Metrics
PREDICTION_COUNT = Counter('ml_predictions_total', 'Total predictions', ['model'])
PREDICTION_DURATION = Histogram('ml_prediction_duration_seconds', 'Prediction duration')

@app.post("/predict/investment-risk")
async def predict_investment_risk(request: InvestmentRiskRequest):
    start_time = time.time()
    try:
        # Prediction logic
        result = make_prediction(request)
        PREDICTION_COUNT.labels(model='investment_risk').inc()
        return result
    finally:
        PREDICTION_DURATION.observe(time.time() - start_time)

🔒 Production Security

Security Headers (`next.config.ts`)

const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Frame-Options',
            value: 'DENY'
          },
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff'
          },
          {
            key: 'Referrer-Policy',
            value: 'origin-when-cross-origin'
          },
          {
            key: 'Permissions-Policy',
            value: 'camera=(), microphone=(), geolocation=()'
          }
        ]
      }
    ]
  }
}

API Rate Limiting

# Add to ML server.py
from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.post("/predict/investment-risk")
@limiter.limit("30/minute")  # 30 requests per minute
async def predict_investment_risk(request: Request, data: InvestmentRiskRequest):
    # Implementation

📈 Performance Optimization

Frontend Optimization

// Image optimization
import Image from 'next/image'

// Code splitting
const MLAnalyzer = dynamic(() => import('./MLAnalyzer'), { 
  ssr: false,
  loading: () => <Skeleton />
})

// Service Worker for caching
// next.config.ts
const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true
})

module.exports = withPWA(nextConfig)

ML Backend Optimization

# Model caching and optimization
import asyncio
from functools import lru_cache

@lru_cache(maxsize=4)
def load_model(model_path: str):
    return joblib.load(model_path)

# Async processing for multiple predictions
@app.post("/predict/batch")
async def batch_predictions(requests: List[PredictionRequest]):
    tasks = [process_single_prediction(req) for req in requests]
    results = await asyncio.gather(*tasks)
    return {"predictions": results}

🔄 CI/CD Pipeline

GitHub Actions (`.github/workflows/deploy.yml`)

name: Deploy FundN3xus

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint

  deploy-frontend:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}

  deploy-ml:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install -r ml/requirements.txt
      - run: cd ml && python train_model.py --validate
      - name: Deploy to Railway
        run: railway deploy --service ml-backend
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/your-username/FundN3xus.git
Create a feature branch: git checkout -b feature/amazing-feature
Install dependencies: npm install && cd ml && pip install -r requirements.txt
Start development: npm run dev:full

Contribution Guidelines

Code Style: Follow TypeScript and Python best practices
Commits: Use conventional commit messages
Testing: Ensure all features work before submitting
Documentation: Update README if adding major features
Pull Requests: Provide clear description of changes

Areas for Contribution

🎨 UI/UX Improvements: Enhanced components and user experience
🧠 ML Models: Additional financial prediction models
🌐 Integrations: Bank APIs, financial data sources
🔧 Infrastructure: Performance optimizations, testing
📚 Documentation: Tutorials, guides, API documentation

📄 License

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

🙏 Acknowledgments

Next.js Team - For the amazing React framework
Firebase Team - For backend infrastructure
Google AI - For Gemini AI capabilities
Tailwind CSS - For utility-first CSS framework
shadcn/ui - For beautiful UI components
XGBoost - For high-performance ML models

📞 Support & Contact

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: weaboo1164@gmail.com
🔗 LinkedIn: Ayush Chauhan

🤝 Contributing

We welcome contributions from developers, designers, financial experts, and data scientists! Here's how you can help make FundN3xus better.

🚀 Getting Started

1. Development Setup

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/your-username/FundN3xus.git
cd FundN3xus

# Create a feature branch
git checkout -b feature/amazing-new-feature

# Install dependencies
npm install
cd ml && pip install -r requirements.txt && cd ..

# Start development environment
npm run dev:full

2. Making Changes

Frontend: Work in src/ directory with TypeScript and React
ML Backend: Work in ml/ directory with Python and FastAPI
Documentation: Update README and add inline comments
Tests: Add tests for new features and bug fixes

3. Submitting Changes

# Run quality checks
npm run typecheck
npm run lint
npm test

# Commit your changes
git add .
git commit -m "feat: add amazing new feature"
git push origin feature/amazing-new-feature

# Create a Pull Request on GitHub

📋 Contribution Guidelines

Code Quality Standards

TypeScript: Use strict typing, avoid any
Python: Follow PEP 8, use type hints
Testing: Add unit tests for new features
Documentation: Update README for major features
Commits: Use conventional commit messages (feat:, fix:, docs:)

Areas for Contribution

Area	Skills Needed	Impact	Examples
🎨 UI/UX	React, Tailwind CSS, Design	High	Improve dashboard, mobile responsiveness
🧠 ML Models	Python, XGBoost, Statistics	High	New prediction models, accuracy improvements
🔌 Integrations	APIs, Authentication	Medium	Bank APIs, payment processors
📱 Mobile	React Native, Expo	High	Native mobile application
🔧 DevOps	Docker, CI/CD, Cloud	Medium	Deployment automation, monitoring
🧪 Testing	Jest, Playwright, pytest	Medium	Test coverage, E2E scenarios
📚 Documentation	Technical Writing	Low	Tutorials, API docs, guides

🐛 Bug Reports

Found a bug? Please create a detailed issue:

**Bug Description**
A clear description of what the bug is.

**Steps to Reproduce**
1. Go to '...'
2. Click on '...'
3. See error

**Expected Behavior**
What you expected to happen.

**Screenshots**
Add screenshots if applicable.

**Environment**
- OS: [e.g., Windows 11]
- Browser: [e.g., Chrome 98]
- Node.js Version: [e.g., 18.0.0]

💡 Feature Requests

Have an idea for a new feature? We'd love to hear it!

**Feature Description**
A clear description of the feature you'd like to see.

**Problem It Solves**
What problem would this feature address?

**Proposed Solution**
How do you envision this feature working?

**Additional Context**
Any other context, mockups, or examples.

👥 Community Guidelines

Be Respectful: Treat everyone with kindness and respect
Be Inclusive: Welcome contributors from all backgrounds
Be Constructive: Provide helpful feedback and suggestions
Be Patient: Remember that everyone is learning
Follow Code of Conduct: Maintain professional behavior