Initial commit

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

@@ -0,0 +1,213 @@
+# 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
+```python
+# 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
+```bash
+# 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.