AI Financial Coaching Agent

A sophisticated financial coaching application powered by AI that continuously learns about individual user behavior, analyzes spending and income patterns, identifies risks, and delivers personalized recommendations.

🤖 NEW: AI Agent Integration

Chat with your finances! The app now includes an intelligent AI agent powered by OpenAI GPT-4 that lets you manage your finances through natural conversation.

AI Agent Capabilities:

• 💬 Natural Language Interface: Talk to manage finances instead of filling forms
• 🔄 All Website Features: Add transactions, track income, set goals - all via chat
• 🧠 Contextual Understanding: Remembers conversation and understands intent
• 📊 Instant Analysis: Get financial insights through simple questions
• 💡 Personalized Advice: Recommendations tailored to your conversation
• 🎯 20 Powerful Tools: Complete CRUD for goals, wealth tracking (assets/liabilities), and financial management

See AI_AGENT_GUIDE.md for detailed documentation.

🌟 Features

Core Functionality

• Intelligent Pattern Recognition: Automatically analyzes spending and income patterns to identify trends
• Risk Detection: Proactively identifies financial risks (overspending, irregular income, low savings, etc.)
• Personalized Recommendations: Generates actionable, context-aware financial advice based on:
  • Employment type (gig workers, informal sector, full-time, etc.)
  • Income variability and reliability
  • Spending habits and trends
  • Financial goals and priorities
  • Risk tolerance

Key Features

1. Transaction Management

   • Add income and expense transactions
   • Categorize transactions automatically
   • Track recurring transactions
   • View transaction history

2. Income Stream Analysis

   • Multiple income source tracking
   • Income reliability assessment
   • Variability analysis for irregular income
   • Ideal for gig workers and freelancers

3. Financial Goal Tracking

   • Set and monitor financial goals
   • Priority-based goal management
   • Progress tracking with deadlines
   • Actionable steps to reach goals

4. Real-time Analysis

   • Financial health score (0-100)
   • Spending pattern visualization
   • Income stream breakdown
   • Savings rate calculation
   • Months of runway estimation

5. Personalized Insights

   • Category-wise spending trends
   • Risk alerts with severity levels
   • Priority-based recommendations
   • Action items for improvement

6. Data Management

   • Local storage (no database required)
   • Export data as JSON
   • Import existing financial data
   • Complete privacy - data never leaves your browser

🏗️ Architecture

Technology Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Charts: Recharts
• Icons: Lucide React
• Storage: Browser LocalStorage
• API: Next.js API Routes

Project Structure

mumbai/
├── app/
│   ├── api/
│   │   ├── analyze/route.ts       # Main analysis endpoint
│   │   ├── insights/route.ts      # Insights endpoint
│   │   └── recommendations/route.ts # Recommendations endpoint
│   ├── globals.css                 # Global styles
│   ├── layout.tsx                  # Root layout
│   └── page.tsx                    # Main dashboard page
├── components/
│   ├── TransactionForm.tsx         # Transaction input form
│   ├── IncomeStreamForm.tsx        # Income stream input form
│   ├── GoalForm.tsx                # Financial goal form
│   ├── SpendingChart.tsx           # Spending visualization
│   ├── RiskAlert.tsx               # Risk display component
│   ├── RecommendationCard.tsx      # Recommendation display
│   └── FinancialHealthScore.tsx    # Health score widget
├── lib/
│   ├── types.ts                    # TypeScript type definitions
│   ├── financialAgent.ts           # AI agent logic
│   ├── storage.ts                  # LocalStorage utilities
│   └── utils.ts                    # Helper functions
├── package.json
├── tsconfig.json
├── tailwind.config.ts
└── next.config.js

🚀 Getting Started

Prerequisites

• Node.js 18.x or higher
• npm or yarn

Installation

1. Clone or navigate to the project directory:

cd /home/ubuntu/mumbai

2. Install dependencies:

npm install

3. Run the development server:

npm run dev

4. Open your browser and navigate to:

http://localhost:3000

Building for Production

npm run build
npm start

📊 How It Works

AI Agent Logic

The financial coaching agent uses a sophisticated algorithm that:

1. Analyzes Spending Patterns

   • Groups transactions by category
   • Calculates trends (increasing/stable/decreasing)
   • Determines percentage of income per category
   • Identifies discretionary vs. essential spending

2. Evaluates Income Patterns

   • Calculates total and average income
   • Measures income variability (coefficient of variation)
   • Assesses reliability of income sources
   • Tracks contribution of each income stream

3. Identifies Risks

   • Overspending detection
   • Irregular income warnings
   • Low savings rate alerts
   • High discretionary spending flags
   • Increasing spending trend notifications

4. Generates Recommendations

   • Context-aware advice for different employment types
   • Prioritized action items
   • Specific dollar amounts and percentages
   • Potential impact estimation
   • Step-by-step guidance

5. Calculates Health Score

   • Savings rate (0-40 points)
   • Income stability (0-20 points)
   • Risk factors (deductions)
   • Final score: 0-100

🎯 Use Cases

For Gig Workers

• Track irregular income from multiple platforms
• Plan for income variability
• Build appropriate emergency fund (6-12 months)
• Identify income patterns and seasonality

For Informal Sector Workers

• Manage cash-based transactions
• Track daily/weekly income
• Plan for uncertain income periods
• Simple budgeting based on minimum income

For Salaried Employees

• Optimize spending categories
• Build savings habits
• Plan for financial goals
• Investment recommendations

For Mixed Income Earners

• Balance multiple income sources
• Diversification strategies
• Risk management
• Comprehensive financial planning

🔒 Privacy & Security

• No Database: All data stored in browser LocalStorage
• No Server Storage: Data never transmitted to external servers
• Client-Side Processing: All analysis happens in your browser
• Data Portability: Export your data anytime
• Full Control: Delete all data with one click

📱 Features in Detail

Dashboard

• Financial health score with visual indicator
• Quick stats (income, expenses, goals)
• Risk alerts with severity levels
• Spending breakdown pie chart
• Income stream analysis
• Personalized recommendations

Add Data

• Quick transaction entry
• Income stream management
• Goal setting and tracking
• Recent transactions list
• Goals overview with progress bars

Profile Settings

• Employment type configuration
• Risk tolerance setting
• Data summary
• Clear all data option

🎨 User Interface

• Modern Design: Clean, professional interface
• Responsive: Works on desktop, tablet, and mobile
• Intuitive Navigation: Tab-based navigation
• Visual Feedback: Color-coded alerts and scores
• Data Visualization: Charts and progress bars
• Accessibility: Semantic HTML and ARIA labels

🔧 Customization

Adding New Categories

Edit the EXPENSE_CATEGORIES or INCOME_CATEGORIES arrays in:

• components/TransactionForm.tsx

Modifying Risk Detection

Customize risk thresholds in:

• lib/financialAgent.ts → identifyRisks() method

Adjusting Recommendations

Modify recommendation logic in:

• lib/financialAgent.ts → generateRecommendations() method

Changing Color Schemes

Update colors in:

• lib/utils.ts → getCategoryColor(), getSeverityColor(), etc.
• tailwind.config.ts for theme colors

🧪 Testing

Manual Testing Checklist

1. Add various transactions (income and expenses)
2. Add multiple income streams with different reliabilities
3. Create financial goals with different priorities
4. Check dashboard updates after each addition
5. Verify risk alerts appear correctly
6. Review personalized recommendations
7. Test export/import functionality
8. Verify data persistence after page refresh

📈 Future Enhancements

Potential features for future versions:

• Machine learning integration for better predictions
• Automated transaction categorization
• Bill payment reminders
• Budget planning tools
• Multi-currency support
• Expense splitting for shared expenses
• Receipt scanning (OCR)
• Bank account integration (optional)
• Financial literacy resources
• Chatbot interface for Q&A

🤝 Contributing

This is a demonstration project for the Agentic AI Challenge. Feel free to:

• Report issues
• Suggest improvements
• Fork and modify for your needs
• Use as a learning resource

📄 License

This project is created for educational and demonstration purposes.

🙏 Acknowledgments

Built as part of the Agentic AI Challenge to demonstrate:

• AI-powered financial coaching
• Personalized recommendation systems
• Pattern recognition algorithms
• User-centric design
• Privacy-first approach

📞 Support

For questions or issues:

• Check the code documentation
• Review the type definitions in lib/types.ts
• Examine the AI agent logic in lib/financialAgent.ts

---

Note: This application is for educational purposes. Always consult with a qualified financial advisor for professional financial advice.