Demo & Presentation

Video Demonstration

YouTube Demo Link: [https://www.youtube.com/@skyhorizon5801]

Smart Financial Coach - Technical Design Document

1. Project Overview

Problem Statement

Personal finance management suffers from poor visibility and lack of personalized guidance. Users struggle with manual expense tracking and generic advice, leading to unaware spending patterns and financial anxiety.

Solution

An AI-powered financial coaching platform that transforms transaction data into actionable insights, enabling users to understand spending patterns, detect subscriptions, and achieve financial goals through personalized recommendations.

Target Users

• Young adults building financial habits
• Freelancers with variable income
• Anyone seeking spending visibility and savings optimization

2. System Architecture

High-Level Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend        │    │   Data Layer    │
│   (React+Vite)  │◄──►│   (Flask API)    │◄──►│   (In-Memory)   │
│                 │    │                  │    │                 │
│ - UI Components │    │ - Data Processing│    │ - Transactions  │
│ - State Mgmt    │    │ - AI Insights    │    │ - Goals         │
│ - Charts        │    │ - File Upload    │    │ - Insights      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Technology Stack

Frontend:

• React 19.1.1 with TypeScript
• Vite for build tooling
• Tailwind CSS 4.x for styling
• Recharts for data visualization
• Lucide React for icons

Backend:

• Flask (Python) REST API
• Pandas for data processing
• NumPy for statistical analysis
• Flask-CORS for cross-origin requests

Data Processing:

• CSV/Excel file parsing
• Transaction categorization
• Subscription detection algorithms
• Spending trend analysis

3. Core Features & Implementation

3.1 File Upload & Data Processing

Frontend Component:

const handleFileUpload = async (file: File) => {
  const formData = new FormData();
  formData.append('file', file);
  
  const response = await fetch(`${API_BASE_URL}/upload-transactions`, {
    method: 'POST',
    body: formData,
  });
  
  return response.json();
};

Backend Processing:

• Standardizes column names (amount, description, date, category, merchant)
• Validates data integrity
• Categorizes transactions
• Generates initial insights

3.2 AI-Powered Spending Insights

Algorithm Features:

• Category spending analysis with percentages
• Trend detection (increasing/decreasing patterns)
• Anomaly detection for unusual expenses
• Coffee spending alerts (specific use case)

Implementation:

def generate_spending_insights():
    category_totals = {}
    for transaction in expenses:
        category = transaction['category']
        amount = transaction['amount']
        category_totals[category] = category_totals.get(category, 0) + amount
    
    # Calculate percentages and trends
    insights = []
    for category, total in category_totals.items():
        percentage = (total / total_expenses * 100)
        trend = 'increasing' if percentage > 20 else 'decreasing'
        insights.append({
            'category': category,
            'total_spent': total,
            'percentage_of_total': percentage,
            'trend': trend
        })

3.3 Subscription Detection System

Detection Logic:

• Identifies recurring merchants
• Analyzes payment consistency
• Uses keyword matching for subscription services
• Calculates confidence scores based on patterns

Key Features:

• Automatic detection of Netflix, Spotify, Adobe, etc.
• Confidence scoring (0.5-0.95 range)
• Last transaction tracking
• Monthly cost calculation

3.4 Goal Forecasting & Progress Tracking

Goal Management:

• Target amount and date setting
• Progress calculation and visualization
• Monthly savings requirements
• Achievement likelihood assessment

AI Recommendations:

• Personalized saving strategies
• Spending reduction suggestions
• Timeline adjustments
• Progress optimization tips

4. Data Flow Architecture

4.1 Data Upload Flow

1. User uploads CSV/Excel file
2. Frontend sends file to Flask API
3. Backend processes and validates data
4. Transactions stored in memory
5. AI insights generated automatically
6. Frontend receives processed data

4.2 Insight Generation Flow

1. Raw transactions analyzed
2. Spending categories calculated
3. Subscription patterns detected
4. Goal progress evaluated
5. Recommendations generated
6. Real-time updates to dashboard

5. API Design

Core Endpoints

GET /api/transactions          - Fetch all transactions
GET /api/insights/spending     - Get spending analysis
GET /api/subscriptions         - Get detected subscriptions
GET /api/goals                 - Fetch financial goals
GET /api/analytics/summary     - Get overview statistics
POST /api/upload-transactions  - Upload and process files
POST /api/goals                - Create new financial goal

Response Formats

Transaction Object:

{
  "id": "string",
  "amount": number,
  "description": "string",
  "category": "string",
  "type": "income|expense",
  "date": "YYYY-MM-DD",
  "merchant": "string"
}

Spending Insight Object:

{
  "category": "string",
  "total_spent": number,
  "percentage_of_total": number,
  "trend": "increasing|decreasing"
}

6. Security & Privacy Considerations

Data Protection

• File uploads processed immediately and deleted
• No persistent storage of sensitive data
• In-memory data clearing on session end
• CORS configuration for secure origins

Privacy Features

• No external API connections for bank data
• User-controlled file uploads only
• Local processing of all financial data
• No data transmission to third parties

7. User Experience Design

Dashboard Layout

• Three main views: Dashboard, Insights, Goals
• Responsive design for mobile/desktop
• Real-time data visualization
• Progressive disclosure of information

Visual Design Principles

• Clean, modern interface with glassmorphism effects
• Gradient-based color scheme for visual hierarchy
• Interactive charts and progress bars
• Accessible design with proper contrast

8. Performance Considerations

Frontend Optimization

• Component-level state management
• Lazy loading for chart libraries
• Responsive image handling
• Efficient re-rendering patterns

Backend Optimization

• Pandas vectorized operations
• Efficient data structures
• Memory management for large datasets
• Request rate limiting

9. Future Enhancements

Phase 2 Features

• Bank API integration for automatic data sync
• Machine learning models for better predictions
• Advanced budgeting tools
• Multi-currency support

Technical Improvements

• Database integration (PostgreSQL/MongoDB)
• User authentication system
• Real-time notifications
• Mobile app development

AI Enhancements

• Natural language processing for transaction descriptions
• Predictive spending models
• Personalized saving recommendations
• Market trend integration

10. Development & Deployment

Local Development Setup

# Frontend
npm install
npm run dev

# Backend
pip install -r requirements.txt
python app.py

Environment Configuration

• Vite environment variables (VITE_API_URL)
• Flask configuration for development/production
• CORS settings for deployment

Testing Strategy

• Component unit tests for React
• API endpoint testing for Flask
• Integration testing for file uploads
• User acceptance testing for workflows

11. Success Metrics & KPIs

User Engagement

• File upload success rate
• Dashboard interaction time
• Goal creation and tracking usage
• Feature adoption rates

Financial Impact

• Identified subscription savings
• Goal achievement rates
• Spending behavior changes
• User retention metrics

Technical Performance

• API response times
• File processing speed
• Chart rendering performance
• Error rates and reliability

12. Implementation Timeline

Phase 1 (Current - MVP)

• Basic file upload functionality
• Transaction data processing
• Spending insights dashboard
• Subscription detection
• Goal tracking system
• Responsive UI with charts

Phase 2 (Next 2-4 weeks)

• Enhanced AI algorithms
• Better categorization logic
• Advanced goal forecasting
• Export functionality
• Performance optimizations
• Goal Setting

Phase 3 (Future)

• Database integration
• User authentication
• Bank API connections
• Mobile application
• Advanced analytics

13. Risk Assessment

Technical Risks

• Data Processing Limitations: Current in-memory storage limits scalability
• File Format Variations: Different CSV structures may cause parsing issues
• Browser Compatibility: Modern features may not work on older browsers

Mitigation Strategies

• Implement progressive enhancement for older browsers
• Add robust error handling for various file formats
• Plan database migration for production scaling

Business Risks

• User Trust: Handling financial data requires high trust levels
• Data Accuracy: Incorrect insights could mislead users
• Competition: Established players like Mint, YNAB have market presence

14. Conclusion

The Smart Financial Coach demonstrates a viable approach to AI-powered personal finance management. The current implementation provides core functionality for transaction analysis, spending insights, and goal tracking while maintaining user privacy through local data processing.

The technical architecture supports rapid iteration and feature development, with clear paths for scaling and enhancement. The focus on user experience and actionable insights addresses real pain points in personal finance management.

Key differentiators include the AI-powered subscription detection, personalized goal forecasting, and privacy-first approach to data handling. These features position the platform well for addressing the target audience's needs while building trust through transparent data processing.

Appendices

A. Sample Data Formats

CSV Upload Format:

date,amount,description,category,merchant
2024-01-15,-45.67,Coffee purchase,food,Starbucks
2024-01-16,-12.99,Netflix subscription,subscription,Netflix
2024-01-17,2500.00,Salary deposit,income,Company Inc

B. Environment Variables

# Frontend (.env)
VITE_API_URL=http://localhost:5000/api

# Backend (environment)
FLASK_ENV=development
FLASK_DEBUG=True
UPLOAD_FOLDER=uploads
MAX_FILE_SIZE=16777216

C. Dependencies

Frontend (package.json):

• React 19.1.1
• TypeScript 5.8.3
• Vite 7.1.2
• Tailwind CSS 4.1.13
• Recharts 3.1.2
• Lucide React 0.542.0

Backend (requirements.txt):

• Flask==2.3.3
• Flask-CORS==4.0.0
• pandas==2.1.0
• numpy==1.24.3
• openpyxl==3.1.2
• Werkzeug==2.3.7
• xlrd==2.0.1