fina/backup/first -fina app/docs/SMART_FEATURES_README.md

Smart Recurring Expense Detection & Subscription Management

Overview

FINA now includes intelligent recurring expense detection that automatically identifies subscription patterns and suggests them to users. This feature helps users track and manage their recurring expenses more effectively.

Features Implemented

1. Smart Detection Algorithm

• Analyzes expense history to find recurring patterns
• Detects frequencies: Weekly, Bi-weekly, Monthly, Quarterly, Yearly
• Considers:
  • Amount similarity (5% tolerance)
  • Description matching (fuzzy matching)
  • Time intervals (consistent payment dates)
  • Category grouping (same category)
• Generates confidence score (0-100%) for each detection
• Minimum 3 occurrences required for pattern detection

2. Subscription Management

• Track active subscriptions with payment schedules
• Add subscriptions manually or accept AI suggestions
• View total costs (monthly and yearly)
• Pause/Resume subscriptions without deleting
• Upcoming payments widget on dashboard
• Notes field for additional context

3. Smart Suggestions

• AI-detected patterns shown as suggestions
• Confidence score indicates reliability
• Shows occurrence count and time period
• Accept to convert to subscription
• Dismiss to hide unwanted suggestions
• Visual indicators for high-confidence matches

4. Dashboard Integration

• Upcoming subscriptions widget (next 30 days)
• Notification badge for new suggestions
• Quick link to subscription management
• Real-time payment reminders

Usage

Running Detection

1. Navigate to Subscriptions page
2. Click 🔍 Detect Recurring button
3. Algorithm analyzes your expense history
4. Suggestions appear with confidence scores

Managing Suggestions

• ✅ Accept: Converts pattern to tracked subscription
• ❌ Dismiss: Hides the suggestion
• View details: Amount, frequency, occurrences, time range

Adding Subscriptions

• Manual Entry: Click "➕ Add Subscription"
• Fill in: Name, Amount, Frequency, Category, Next Payment Date
• Add optional notes

Tracking Payments

• View all active subscriptions
• See monthly and annual costs
• Check upcoming payment dates
• Edit or pause anytime

API Endpoints

/subscriptions/detect (POST)

Runs detection algorithm for current user

/subscriptions/api/upcoming (GET)

Returns upcoming subscriptions as JSON

• Query param: days (default: 30)

/subscriptions/suggestion/<id>/accept (POST)

Converts detected pattern to subscription

/subscriptions/suggestion/<id>/dismiss (POST)

Dismisses a suggestion

Detection Algorithm Details

Pattern Matching

# Amount tolerance: 5% or $5 (whichever is larger)
tolerance = max(amount * 0.05, 5.0)

# Description normalization
- Removes dates, transaction numbers
- Lowercases and strips whitespace
- Checks word overlap (60% threshold)

# Interval analysis
- Calculates average days between transactions
- Checks variance (lower = higher confidence)
- Maps to standard frequencies

Confidence Scoring

Base confidence starts at 50-70% depending on interval consistency:

• +15% for monthly patterns (most common)
• +10% for weekly patterns
• +10% if amount variance < 5%
• -10% if amount variance > 20%
• -10% for less common intervals

Database Schema

Subscriptions Table

• name: Subscription name (e.g., "Netflix")
• amount: Payment amount
• frequency: weekly | biweekly | monthly | quarterly | yearly
• category_id: Linked category
• next_due_date: Next payment date
• is_active: Active/paused status
• is_confirmed: User confirmed (vs AI suggestion)
• auto_detected: Created from AI detection
• confidence_score: Detection confidence (0-100)
• notes: User notes

Recurring Patterns Table

• Stores detected patterns before user confirmation
• Links to original expense IDs (JSON array)
• Tracks acceptance/dismissal status
• Prevents duplicate suggestions

Multi-Language Support

All subscription features fully translated:

• 🇬🇧 English
• 🇷🇴 Romanian
• 🇪🇸 Spanish

Translation keys added:

• subscription.* - All subscription-related text
• Frequency labels (weekly, monthly, etc.)
• Dashboard widgets
• Action buttons

Best Practices

For Users

1. Add expenses regularly - More data = better detection
2. Use consistent descriptions - Helps pattern matching
3. Run detection monthly - Catch new subscriptions
4. Review suggestions carefully - Check confidence scores
5. Add notes - Remember renewal terms, cancellation dates

For Developers

1. Run detection as background job - Don't block UI
2. Cache detection results - Expensive operation
3. Adjust confidence thresholds - Based on user feedback
4. Monitor false positives - Track dismissal rates
5. Extend pattern types - Add custom frequencies

Future Enhancements

• Email/push notifications for upcoming payments
• Category-based insights (subscription spending)
• Price change detection
• Cancellation reminders
• Bulk operations
• Export subscription list
• Recurring expense auto-entry
• Integration with calendar apps

Testing

# Rebuild with new models
docker compose down
docker compose up --build -d

# Access app
http://localhost:5001/subscriptions

# Test detection
1. Add similar expenses (3+) with regular intervals
2. Click "Detect Recurring"
3. Check suggestions appear with confidence scores
4. Accept or dismiss suggestions
5. View on dashboard

Troubleshooting

No patterns detected:

• Need minimum 3 similar transactions
• Check amount similarity (within 5%)
• Ensure consistent time intervals
• Verify same category used

Low confidence scores:

• Irregular payment dates
• Varying amounts
• Different descriptions
• Try manual entry instead

Missing upcoming payments:

• Check next_due_date is set
• Verify subscription is active
• Ensure date within 30 days

Architecture

User Actions
    ↓
Routes (subscriptions.py)
    ↓
Smart Detection (smart_detection.py)
    ↓
Models (subscription.py)
    ↓
Database (SQLite)

Pattern detection is stateless and can run independently. Results stored in recurring_patterns table until user action.