Deploy to Hugging Face

Dockerfile

@@ -0,0 +1,54 @@
+# Use an official Python runtime as a parent image
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE 1
+ENV PYTHONUNBUFFERED 1
+ENV PORT 7860
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    cmake \
+    pkg-config \
+    libgomp1 \
+    libopenblas-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set environment variables for better stability with Stan (Prophet) and Llama-cpp
+ENV OMP_NUM_THREADS 1
+ENV MKL_NUM_THREADS 1
+ENV OPENBLAS_NUM_THREADS 1
+ENV KMP_DUPLICATE_LIB_OK TRUE
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install llama-cpp-python (Latest).
+# We compile from source because pre-built glibc wheels aren't always available.
+# CRITICAL FIX for OOM (137): llama-cpp-python uses Ninja, which ignores MAKEFLAGS.
+# We MUST set CMAKE_BUILD_PARALLEL_LEVEL=1 to limit it to a single thread.
+ENV CMAKE_ARGS="-DGGML_CPU=ON"
+ENV CMAKE_BUILD_PARALLEL_LEVEL="1"
+RUN pip install --no-cache-dir --upgrade llama-cpp-python
+
+# Pre-download the model into the image for instant startup on HF Spaces.
+# Using Gemma 4 E4B (Instruct-GGUF) - ~2.5GB model file.
+RUN mkdir -p models && \
+    python -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='bartowski/google_gemma-4-E4B-it-GGUF', filename='google_gemma-4-E4B-it-Q4_K_M.gguf', local_dir='models')"
+
+# Copy the rest of the application code
+COPY . .
+
+# Expose the port the app runs on
+EXPOSE 7860
+
+# Command to run the application using uvicorn with a single worker
+# Reverting to 1 worker for debugging startup hangs on HF Spaces.
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -0,0 +1,1132 @@
+---
+title: Grip Backend
+emoji: 💰
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+---
+
+# GRIP
+
+> **Autonomous Financial Intelligence.**
+
+An AI-powered personal platform that transforms your inbox into a complete financial intelligence system. Track spending, forecast expenses, grow investments—all while keeping your data private and secure.
+
+**🎯 The Only Platform in India That Shows If Your SIP Date is Costing You Money.**
+
+Import your Consolidated Account Statement (CAMS, KFin, MFCentral) in 60 seconds. Discover if switching your SIP date could earn you thousands more. No other platform does this.
+
+[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com)
+[![React](https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)](https://reactjs.org)
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?style=for-the-badge&logo=postgresql&logoColor=white)](https://www.postgresql.org)
+
+---
+
+## 🌟 What Makes Grip Different
+
+### 💰 Know Your True Spending Power
+- **Safe-to-Spend Engine**: See what you can *actually* spend after bills, credit cards, and commitments—not just your bank balance.
+- **Real-Time Intelligence**: Automatically accounts for unpaid bills, upcoming rent, and unbilled credit card purchases.
+- **Predictive Budgeting**: Includes projected recurring expenses ("Surety") before they even arrive.
+
+### 🎯 Timing Alpha: The Only Platform for Precision Wealth Analytics
+Most investment apps are "lazy"—they show you generic fund returns or XIRR calculated with approximate dates. Grip is built for the precision-obsessed investor.
+
+**The "Average" Problem with Other Platforms:**
+- ❌ **Lazy Pricing**: Use month-end NAVs or weekly averages to calculate your returns.
+- ❌ **Generic XIRR**: Show you a number that assumes your transactions happened at a "standard" time.
+- ❌ **The Blind Spot**: No insight into whether your SIP date is actually helping or hurting you.
+
+**The Grip Precision Advantage:**
+- ✅ **Day-Specific NAV**: We fetch the *exact* NAV of the day your transaction hit the bank. If you invest on the 7th, we calculate parity with the 7th, not a "monthly average".
+- ✅ **Timing Leakage Analysis (WORLD FIRST)**: We analyze every SIP you've ever made and cross-reference them with the volatility schedules of that specific fund. 
+- ✅ **What-If Date Simulation**: Grip simulates your entire investment history against every other day of the month (1st to 28th) to determine if a simple change in your salary-cycle could yield an extra 1-2% in "Timing Alpha".
+
+**Why this is a Big Deal:**
+Mutual Fund NAVs fluctuates daily. An investor who does a SIP on the 10th vs. the 15th might see a **1.5% difference in lifetime XIRR** for the exact same fund. Most platforms hide this "Timing Leakage." Grip exposes it and shows you how to fix it.
+
+> **Our Finding says:** No other retail investment platform in India—not Zerodha Coin, INDMoney, or Groww—performs historical date-permutation analysis on your *actual* transactions to optimize your future returns.
+
+### 🛡️ Frictionless, Private Onboarding
+While others make you wait for "syncs" or manual entries, Grip is built to get you from zero to "Deep Insights" in under a minute.
+
+- **Universal Statement Import**: Upload your Consolidated Account Statement (CAS) from CAMS, KFin, or MFCentral. We reconstruct your entire investment life—identifying SIPs, step-ups, and even "missed" months—instantly.
+- **Step-Up & Skip Detection**: We don't just show total units; we map the *evolution* of your discipline. See exactly when you increased your SIPs and where you missed a beat.
+- **Privacy-First Intelligence**: All your data is processed with local sanitization. Your bank details and PAN are masked *before* our analysis engines ever touch the data.
+
+### 📊 Professional-Grade Portfolio Simulation
+- **AI-Powered Forecasting**: We use Facebook Prophet (the same engine used by data scientists for revenue forecasting) to project your portfolio 10-20 years into the future with realistic confidence intervals.
+- **Simulation Mode**: Instantly see how a ₹2,000 "Step-Up" in your monthly SIP today changes your net worth 15 years from now.
+- **Email-to-Wealth Pipeline**: Once imported, Grip auto-extracts your future buys from your bank alert emails. No more manual tracking.
+- **Precision XIRR**: Calculated using the Newton-Raphson method for accurate annualized returns based on daily cashflows.
+- **Timing Leakage Reports**: Detailed breakdown of how much "extra" money you could have made by simply shifting your SIP date.
+
+### 🤖 Hybrid Intelligence — Fast, Private, Reliable
+- **Local LLM Engine (Primary)**: A high-privacy, zero-cost LLM (SmolLM2-1.7B) runs natively on your server for extraction. With 2048-token(configurable) context window handles even the longest transaction alerts.
+- **Semantic Email Compression**: Inspired by LLMLingua-2, Grip semantically strips 60-70% of email boilerplate (disclaimers, etc.) while preserving high-signal transaction data, ensuring 2x-3x faster and more reliable extraction.
+- **KV Cache Optimization**: Prompts are reordered to put static context at the top, allowing the local LLM to cache instruction states and significantly speed up batch processing of multiple emails.
+- **Rule Engine (Secondary)**: A deterministic, zero-latency pattern-matching engine handles common Indian bank email formats.
+- **Automatic Transaction Extraction**: Connect Gmail once; transactions are extracted from bank alerts automatically.
+- **Webhook Sync Optimization**: Intelligent 5-second debouncing and concurrency guards prevent redundant syncs from batch emails.
+- **Autonomous Notification Engine**: Scheduled email alerts for Gmail disconnection, surety bill reminders, and spending insights.
+- **Hybrid Forecasting**: Combines Meta Prophet (statistical) + Local LLM (contextual) to predict month-end expenses.
+- **Smart Learning**: Remembers your merchant preferences, auto-categorizes future transactions.
+- **Multi-Layer Spam Filter**: Sender whitelist + subject gates + body signals distinguish real transactions from marketing emails.
+### 🔒 Privacy Built-In, Not Bolted-On
+- **100% On-Server Extraction**: Local LLM (SmolLM2-1.7B) runs natively on our server. Your financial data **never leaves your infrastructure** for extraction.
+- **Real-Time Privacy**: Gmail webhooks (via Google Pub/Sub) trigger immediate, secure parsing.
+- **Sanitization Before Processing**: PAN, Aadhaar, and Credit Card numbers are masked *before* the LLM even sees them, providing double-layered privacy.
+- **No Data Selling**: Your financial data stays yours. Period.
+- **Self-Hostable**: Open architecture—you control the deployment and data.
+- **Read-Only Gmail**: OAuth 2.0 with minimal scopes; we can't send or modify your emails.
+
+---
+
+## ⚡ Zero-Effort Automation
+- **One-Click Sync**: Connect Gmail → Transactions flow in automatically
+- **Smart Deduplication**: SHA-256 hashing ensures no duplicate transactions
+- **Background Processing**: Email parsing happens async—never blocks your UI
+- **Merchant Intelligence**: Auto-learns from your verifications, gets smarter over time
+- **Daily Price Sync**: Scheduled job updates investment NAVs every evening at 9 PM IST
+
+---
+
+## 🚀 How It Works
+
+Grip processes your financial data through a sophisticated, privacy-preserving pipeline:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. EMAIL INGESTION (3 Methods)                                 │
+│    • OAuth Sync: Gmail API fetch (manual/scheduled)            │
+│    • Webhook Push: Real-time via Google Apps Script            │
+│    • Manual Entry: Cash/other transactions (auto-verified)     │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. PRIVACY SANITIZATION (LOCAL)                                 │
+│    Regex Engine → Masks PII → Safe for AI processing            │
+│    • Credit Card: 💳 ****-****-XXXX-1234                        │
+│    • Aadhaar: 🆔 XXXX-XXXX-5678                                 │
+│    • UPI ID: 👤 <email>@***                                     │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. AI EXTRACTION (Local SmolLM2-1.7B)                           │
+│    Natural Language → Structured JSON                           │
+│    "Rs 1,250 debited from Card ending 4521 at Swiggy"          │
+│    ↓                                                             │
+│    { amount: 1250, merchant: "Swiggy",                          │
+│      category: "Food & Dining", account: "CREDIT_CARD" }        │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 4. SMART DEDUPLICATION                                          │
+│    SHA-256 Hash → Check Database → Skip if exists               │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 5. INVESTMENT DETECTION & MAPPING                               │
+│    "ICICI Pru SIP ₹5000" → Match Rule → Fetch NAV → Add Units  │
+│    Auto-creates snapshots for portfolio tracking                │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 6. MERCHANT INTELLIGENCE                                        │
+│    User Verification → Create Mapping → Future Auto-categorize  │
+│    "SWIGGY*BANGALORE" → Clean: "Swiggy" → Category: Food        │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 7. PREDICTIVE FORECASTING                                       │
+│    Historical Data → Prophet/Local LLM → Month-end burden prediction│
+│    "Expected ₹12,500 in remaining expenses (18 days left)"     │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+│ 8. AUTONOMOUS NOTIFICATIONS                                     │
+│    • Gmail Connection Alerts: Instant email if OAuth expires       │
+│    • Surety Reminders: Morning-of alerts for big recurring bills  │
+│    • Weekly Insights: Smart alerts for Category spending spikes   │
+└────────────────────────┬────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 9. ACTIONABLE INSIGHTS & DASHBOARD                              │
+│    • Safe-to-Spend = Balance - (Bills + CC + Buffer)           │
+│    • Wealth Trajectory: Historical + 10Y AI forecast           │
+│    • Investment XIRR: Annualized returns per asset              │
+│    Visual dashboard with spending trends and recommendations    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✨ Key Features
+
+### 💰 Safe-to-Spend Intelligence (Core USP)
+
+**The Number That Matters Most**
+
+Forget checking your bank balance—Grip shows you what you can *actually* spend without stress.
+
+**Intelligent Calculation:**
+```
+Safe-to-Spend = Current Balance 
+                - Unpaid Bills
+                - Projected Recurring Bills (Surety)
+                - Current Unbilled Credit Card Expenses
+                - Configurable Safety Buffer (default 10%)
+```
+
+**Real-World Example:**
+```
+Bank Balance:              ₹45,000
+- Rent (due in 5 days):    -₹15,000
+- Utilities (projected):    -₹2,500
+- Unbilled CC purchases:    -₹8,200
+- Safety Buffer (10%):      -₹1,930
+─────────────────────────────────────
+Safe-to-Spend:             ₹17,370 ✅
+```
+
+**Visual Health System:**
+- 🔴 **Negative**: Overdrawn (immediate action required)
+- 🟠 **Critical**: < ₹1,000 (extremely tight budget)
+- 🟡 **Warning**: ₹1,000 - ₹3,000 (limited spending room)
+- 🟢 **Healthy**: > ₹3,000 (comfortable spending capacity)
+
+**Why This Matters:**
+- **Prevents Overspending**: Accounts for committed expenses before they hit
+- **Reduces Anxiety**: One number tells you your true spending power
+- **Builds Buffer**: Automatic safety margin prevents living paycheck-to-paycheck
+- **Predictive**: Includes projected bills, not just current ones
+
+### 📈 Investment Intelligence Platform (NEW!)
+
+**Automated Wealth Tracking**
+
+Transform your investment expenses into a live-tracked portfolio with zero manual work.
+
+**Email-to-Wealth Pipeline:**
+```
+① Bank Email: "SIP ₹5,000 debited for ICICI Pru Bluechip"
+② Auto-Detection: Investment category + merchant pattern match
+③ Smart Linking: Checks if asset exists in portfolio
+   - If New: Creates new holding
+   - If Existing: Appends transaction to history
+④ NAV Fetch: Historical price on transaction date (mfapi.in)
+⑤ Unit Calculation: ₹5,000 / ₹45.23 = 110.52 units
+⑤ Snapshot Created: Portfolio updated with new units
+⑥ XIRR Recalculated: Annualized returns refreshed
+⑥ Portfolio Update: Total units increased, XIRR recalibrated
+```
+
+**🆕 Universal Statement Import (Instant Onboarding):**
+- **Broad Support**: Import statements from CAMS, KFin, or MFCentral
+- **Format Agnostic**: Supports both CSV and Excel formats
+- **Bulk Processing**: Import years of transactions in seconds
+- **Auto-Detection**: Automatically identifies SIP patterns vs lump sum
+- **Step-Up Tracking**: Detects when SIP amount increases (e.g., ₹5k → ₹7k)
+- **Skip Detection**: Identifies missed SIP months with gap analysis
+- **Smart Metadata**: Stores change percentages, skip reasons, historical patterns
+- **Zero Manual Work**: Auto-creates holdings, fetches historical NAVs, calculates units
+- **Preview Before Import**: Review all transactions before committing
+
+**🎯 SIP Date-Specific Performance Analysis (UNIQUE USP!):**
+
+*No other platform in India offers this!*
+
+**What Others Show:**
+- ❌ Generic monthly average returns
+- ❌ Hypothetical "if you invested on 1st Jan every year"
+- ❌ Fund-level performance only
+
+**What Grip Shows:**
+- ✅ **YOUR Actual SIP Dates**: Analyzes your real purchase dates (e.g., 15th of every month)
+- ✅ **Alternative Date Comparison**: Simulates 6 alternative dates (1st, 5th, 10th, 15th, 20th, 25th)
+- ✅ **Exact NAV on Your Dates**: Fetches historical NAV for your specific purchase days
+- ✅ **Potential Improvement**: Shows how much more you could have earned with different dates
+- ✅ **Historical Win Rate**: "10th-date SIPs outperformed 15th in 16/24 months (67%)"
+- ✅ **AI Insights**: "Switching to 10th could earn you ₹1,100 more (4.4% better)"
+- ✅ **Optimization Recommendations**: Actionable suggestions for future SIPs
+
+**Example Analysis:**
+```
+Your SIP Date: 15th of every month
+Your Performance:
+  • Total Invested: ₹1,20,000
+  • Current Value: ₹1,45,000
+  • Returns: +₹25,000 (20.8%)
+  • XIRR: 12.5%
+
+Best Alternative: 10th of every month
+  • Returns: +₹26,100 (21.8%)
+  • XIRR: 13.2%
+  • Improvement: ₹1,100 (0.9% better)
+
+💡 Insight: "Your 15th date SIP performed well, but switching 
+to 10th could have earned you ₹1,100 more. Consider adjusting 
+your SIP date for future investments."
+```
+
+**Live Market Sync:**
+- **Daily Price Updates**: Scheduled job at 9:00 PM IST
+- **Mutual Funds**: NAV from mfapi.in (India's official MF API)
+- **Stocks**: Real-time prices via yfinance
+- **Auto-Snapshots**: Daily value tracking for Prophet forecasting
+
+**Professional-Grade Analytics:**
+- **XIRR Calculation**: scipy.optimize.newton for accurate annualized returns
+- **Historical Performance**: Complete transaction history with date-wise snapshots
+- **Asset-Level Drill-Down**: Click any holding to see detailed growth chart + SIP analysis
+- **Portfolio Aggregation**: Net worth, total invested, absolute returns
+- **Step-Up/Skip Visualization**: Timeline showing SIP changes and missed months
+
+**AI-Powered Forecasting:**
+- **Facebook Prophet**: Statistical time-series analysis on daily snapshots
+- **10-20 Year Projections**: Confidence intervals with upper/lower bounds
+- **Simulation Mode**: Adjust monthly SIP, see instant forecast updates
+- **Category Breakdown**: Equity, Debt, Liquid, Fixed Income allocation
+
+**Supported Asset Types:**
+- ✅ **SIP** (Systematic Investment Plans) - *with date optimization*
+- ✅ **Mutual Funds** (Lump sum)
+- ✅ **Stocks** (Equity holdings)
+- ✅ **FD/RD** (Fixed/Recurring Deposits - manual input)
+- ✅ **PF/Gratuity** (Retirement accruals - formulaic)
+- ✅ **Gold, Real Estate** (Manual tracking)
+
+**Human-in-the-Loop:**
+- **Statement Import**: Upload consolidated statement (CAMS/KFin/MFCentral) for instant portfolio creation
+- **Transaction Linker**: Manually map undetected investment transactions
+- **Mapping Rules**: Create patterns for future auto-detection
+- **Adjustments**: Override AI suggestions, edit units/prices
+- **Add Holdings**: Manually add assets not tracked via email
+
+**Future-Proof:**
+- **Tax Engine Placeholder**: Ready for LTCG/STCG calculations
+- **Multi-Asset Support**: Extensible for crypto, bonds, commodities
+- **Consolidated View**: Liquid cash + Fixed income + Market-linked in one dashboard
+- **Multi-Fund Optimization**: Find best SIP dates across entire portfolio (coming soon)
+
+### 🧠 AI-Powered Intelligence
+
+**Automatic Transaction Extraction**
+- Connects to Gmail via OAuth 2.0 (read-only)
+- AI parses bank alerts, credit card statements, UPI confirmations
+- Extracts: Amount, Merchant, Category, Account Type, Date
+- Natural language processing handles different email formats
+- Works with major Indian banks (ICICI, HDFC, SBI, Axis, Kotak, and others)
+
+**Hybrid Forecasting Engine**
+- **Meta Prophet**: Statistical time-series analysis of daily spending patterns
+- **Groq LLM**: Category-level breakdowns with contextual reasoning
+  - "Food & Dining trending 20% higher: 4 weekend restaurant visits vs 2 last month"
+  - "Expected ₹12,500 in remaining expenses (18 days left in month)"
+- Predicts month-end spending based on historical patterns
+- Adapts to seasonal patterns, holidays, and lifestyle changes
+
+**Merchant Intelligence & Memory**
+- First time: "SWIGGY*BANGALORE127" → AI suggests "Food & Dining"
+- You verify: "Food & Dining > Online Food"
+- Forever after: "SWIGGY*" auto-categorized as "Food & Dining > Online Food"
+- Learns from every verification, gets smarter over time
+- Clean merchant names (no more cryptic transaction descriptions)
+
+### 💳 Credit Card Lifecycle Management
+
+**Comprehensive Card Tracking**
+- Register unlimited credit cards with billing details
+- Tracks: Card name, last 4 digits, statement date, payment due date, credit limit
+- Automatic billing cycle calculation (current cycle, days remaining)
+- Real-time unbilled amount in current cycle
+- Credit utilization monitoring (% of limit used)
+
+**Billing Cycle Intelligence**
+```
+HDFC Regalia Gold (••1234)
+───────────────────────────────────
+Statement Date:    15th (every month)
+Payment Due:       25th (every month)
+Current Cycle:     Jan 16 - Feb 15
+Days to Statement: 12 days
+───────────────────────────────────
+Unbilled Amount:   ₹8,247
+Credit Limit:      ₹3,00,000
+Utilization:       2.7% ✅
+```
+
+**Smart Alerts & Predictions**
+- "Cycle closes in 5 days: ₹8,247 unbilled"
+- "Estimated bill: ₹8,500 (based on current trend)"
+- "Payment due in 10 days: ₹12,340"
+- Prevents surprise bills by tracking unbilled amounts in real-time
+
+**Transaction Linking**
+- Link each transaction to specific credit card
+- Accurate per-card spending tracking
+- Prevents overspending within billing cycle
+- Helps optimize card usage across multiple cards
+
+### 📋 Bill Management & "Surety" Intelligence
+
+**Bill Tracking**
+- Create one-time or recurring bills
+- Set due dates and payment amounts
+- Mark bills as paid/unpaid
+- View upcoming bills (next 7/30/60 days)
+- Payment reminders
+
+**Surety Bills (Predictable Expenses)**
+
+The secret sauce for accurate Safe-to-Spend calculation.
+
+**What is "Surety"?**
+Predictable, recurring expenses that you *know* are coming:
+- Rent (every 1st of month)
+- Electricity/Water (monthly)
+- Internet/Phone bills
+- Insurance premiums
+- Subscriptions (Netflix, Spotify, etc.)
+- Society maintenance
+
+**How It Works:**
+```
+① Mark bill as "Surety" (predictable recurring)
+② Grip automatically projects next occurrence
+③ Amount included in Safe-to-Spend calculation
+④ Even if not yet billed, it's accounted for
+```
+
+**Example:**
+```
+Rent: ₹15,000 (Surety, due 1st of every month)
+Today: Jan 20
+Next Due: Feb 1 (12 days away)
+
+Safe-to-Spend: Already reduced by ₹15,000
+Result: Prevents overspending before rent is due ✅
+```
+
+**Frozen Funds Breakdown:**
+```
+┌────────────────────────────────────────┐
+│ Frozen Funds: ₹25,700                  │
+├────────────────────────────────────────┤
+│ • Unpaid Bills:           ₹10,500      │
+│ • Projected Surety:       ₹12,000      │
+│ • Unbilled CC:             ₹3,200      │
+└────────────────────────────────────────┘
+```
+
+### 🎯 Financial Goals
+
+**Goal Setting & Tracking**
+- Set savings goals with target amounts and deadlines
+- Track progress towards each goal
+- Visual progress indicators
+- Automatic calculation of monthly savings needed
+- Integration with Safe-to-Spend (optional goal reserves)
+
+**Goal Types:**
+- Emergency Fund
+- Vacation
+- Gadget Purchase
+- Down Payment
+- Custom Goals
+
+**Smart Recommendations:**
+- "Save ₹8,500/month to reach ₹1,00,000 goal by December"
+- "You're 45% towards your iPhone fund!"
+- "Adjust Safe-to-Spend buffer to include goal savings"
+
+### 📊 Advanced Analytics
+
+**Variance Analysis**
+- Month-to-date vs last month comparison
+- Category-level spend changes with % metrics
+- "You spent 23% more on Food & Dining this month (₹8,500 vs ₹6,900)"
+- Trend detection: "Entertainment spending doubled"
+- Visual charts showing spend distribution
+
+**Spend Categorization**
+- 20+ default categories (Food & Dining, Shopping, Transport, etc.)
+- Hierarchical subcategories (e.g., Food > Restaurants, Groceries, Online Food)
+- Custom tag system for personal organization (#business, #vacation, #medical)
+- Pie charts, bar graphs, trend lines
+- Export category reports
+
+**Monthly Summary Dashboard**
+- Total income vs expenses
+- Category-wise breakdown
+- Top merchants
+- Largest transactions
+- Spending trends over time
+
+### 🔄 Automated Email Sync
+
+**Gmail Integration (Zero Manual Work)**
+- One-click OAuth 2.0 connection (read-only access)
+- Searches inbox for transaction keywords automatically:
+  - "spent", "debited", "transaction", "alert", "paid", "credited"
+- Processes bank alerts, credit card statements, UPI confirmations
+- Background sync (doesn't block UI)
+- Deduplication (SHA-256 hash prevents duplicate transactions)
+
+**Sync Features:**
+- **Manual Trigger**: Click "Sync Now" anytime for instant update
+- **Connection Status**: See last sync time, total transactions imported
+- **Sync History**: Complete log with status, errors, records processed
+- **Easy Disconnect**: One-click disconnect, reconnect anytime
+- **Format-Agnostic**: Works with different email formats via natural language AI
+
+**Supported Email Types:**
+```
+✅ Bank transaction alerts      (ICICI, HDFC, SBI, etc.)
+✅ Credit card alerts           (Statement generated, payment due)
+✅ UPI payment confirmations    (GPay, PhonePe, Paytm)
+✅ Debit card purchases         (POS transactions)
+✅ NEFT/RTGS/IMPS alerts       (Fund transfers)
+✅ Wallet transactions          (Paytm, Mobikwik)
+✅ Investment confirmations     (SIP, MF purchases)
+```
+
+### 🔐 Privacy & Security (Core Differentiator)
+
+**Local-First Sanitization**
+```
+Before AI processing (happens on your server):
+────────────────────────────────────────────────
+Original: "Paid ₹500 using Card 4521-6789-1234-5678"
+Masked:   "Paid ₹500 using Card ****-****-****-5678"
+
+Original: "PAN: ABCDE1234F, Aadhaar: 9876-5432-1098"
+Masked:   "PAN: XXXXX1234X, Aadhaar: XXXX-XXXX-1098"
+
+Original: "UPI: user@paytm paid merchant@phonepe"
+Masked:   "UPI: ****@paytm paid ****@phonepe"
+```
+
+**What Gets Sanitized:**
+- ✅ Credit Card numbers (💳 12-digit masking, last 4 visible)
+- ✅ PAN cards (🆔 Professional alpha-numeric masking)
+- ✅ Aadhaar numbers (🆔 8-digit masking, last 4 visible)
+- ✅ UPI IDs (👤 <email> or <username> prefix masked)
+- ✅ Phone numbers (📱 middle 6 digits masked)
+**Security Architecture:**
+- JWT authentication with bcrypt password hashing
+- Email verification with OTP (SMTP)
+- Read-only Gmail OAuth (can't send/modify emails)
+- Encrypted OAuth tokens in database (PostgreSQL JSONB encrypted)
+- No third-party analytics or tracking
+- Self-hostable (you control the data)
+
+### 🏷️ Advanced Organization
+
+**Tags System**
+- Create custom tags (#vacation, #business, #medical, #family)
+- Tag individual transactions
+- Filter and analyze by tags
+- Multi-tag support (one transaction, multiple tags)
+
+**Categories & Subcategories**
+- 20+ predefined categories
+- Hierarchical structure (Category > Subcategory)
+- Fully customizable (add/edit/delete)
+- Visual spending distribution
+
+**Search & Filters**
+- Search by merchant, amount, category, tag
+- Date range filters
+- Account type filters (Credit Card, Savings, Cash, UPI)
+- Status filters (Pending, Verified)
+- Export filtered results
+
+---
+
+## 🛠️ Technology Stack
+
+### Backend
+- **Framework**: FastAPI (Python 3.12+) - High-performance async API
+- **Database**: PostgreSQL with SQLAlchemy (async) + asyncpg
+- **AI/ML**:
+  - **Groq** (Llama 3.3 70B) - Transaction extraction & forecasting
+  - **Meta Prophet** - Statistical time-series forecasting
+  - **scipy** - XIRR calculation (Newton-Raphson optimization)
+- **Data APIs**:
+  - **mfapi.in** - Mutual fund NAV data (India)
+  - **yfinance** - Stock prices (global)
+- **Scheduler**: APScheduler (async) - Daily price sync jobs
+- **Authentication**: JWT + bcrypt
+- **Email**: SMTP for OTP delivery
+- **OAuth**: Google OAuth 2.0 for Gmail
+- **Deployment**: Render/Vercel-ready
+
+### Frontend
+- **Framework**: React 19 with TypeScript
+- **Build**: Vite (lightning-fast HMR)
+- **Styling**: Vanilla CSS (no framework bloat)
+- **State**: Zustand (lightweight)
+- **Data Fetching**: Axios with interceptors
+- **Charts**: Recharts (responsive, composable)
+- **Icons**: Lucide React
+- **Animations**: Framer Motion
+- **Routing**: React Router DOM
+
+### Infrastructure
+- **Package Manager**: uv (Rust-based, 10-100x faster than pip)
+- **Database**: Supabase / NeonDB (serverless Postgres)
+- **Hosting**: Render (backend) + Vercel (frontend)
+- **Version Control**: Git / GitHub
+
+---
+
+## ⚡ Quick Start
+
+### Prerequisites
+- Python 3.12+
+- Node.js 18+
+- PostgreSQL database
+- Gmail account (for email sync)
+- Groq API key ([Get one free](https://console.groq.com))
+
+### 1. Clone & Install
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/grip.git
+cd grip
+
+# Backend setup
+cd Backend
+uv sync  # Install dependencies
+
+# Frontend setup
+cd ../Frontend
+npm install
+```
+
+### 2. Configure Environment
+
+**Backend (`Backend/.env`):**
+```bash
+# Database
+DATABASE_URL=postgresql://user:pass@host:port/dbname
+
+# Security
+SECRET_KEY=your-secret-key-here
+GRIP_SECRET=webhook-secret
+
+# AI Features (Local SmolLM2-1.7B)
+USE_AI_FORECASTING=true
+ENABLE_SCHEDULER=true
+GROQ_API_KEY=your-groq-api-key # Optional fallback
+GROQ_MODEL=llama-3.3-70b-versatile
+
+# Gmail OAuth & Webhooks (Real-time Sync)
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+GMAIL_PUBSUB_TOPIC=projects/your-project/topics/gmail-updates
+FRONTEND_ORIGIN=http://localhost:5173
+
+# Email (for OTP)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASSWORD=your-gmail-app-password
+FROM_EMAIL=noreply@grip.com
+FROM_NAME=Grip
+
+# Branding
+APP_NAME=Grip
+APP_TAGLINE=Money that minds itself.
+```
+
+**Frontend (`Frontend/.env`):**
+```bash
+VITE_API_BASE_URL=http://localhost:8000/api/v1
+VITE_APP_NAME=Grip
+VITE_APP_TAGLINE=Money that minds itself.
+```
+
+### 3. Initialize Database
+
+```bash
+cd Backend
+
+# Run migrations
+uv run alembic upgrade head
+
+# Seed default data (optional)
+uv run python scripts/seed_db.py
+# Creates user: amit@grip.com / password: admin
+```
+
+### 4. Run Development Servers
+
+```bash
+# Terminal 1 - Backend
+cd Backend
+uv run uvicorn app.main:app --reload
+# → http://localhost:8000
+
+# Terminal 2 - Frontend
+cd Frontend
+npm run dev
+# → http://localhost:5173
+```
+
+### 5. Set Up Gmail Sync (Optional)
+
+See **[Gmail Sync Setup Guide](GMAIL_SYNC_QUICKSTART.md)** for detailed instructions.
+
+**Quick version:**
+1. Create Google Cloud project
+2. Enable Gmail API
+3. Create OAuth credentials
+4. Add credentials to `.env`
+5. Connect in app: More → Gmail Sync
+
+---
+
+## 📖 Usage
+
+### First-Time Setup
+
+1. **Register Account**
+   - Open http://localhost:5173
+   - Click "Sign Up"
+   - Enter email and password
+   - Check email for 6-digit OTP
+   - Verify and auto-login ✅
+
+2. **Connect Gmail** (Recommended)
+   - Go to More → Gmail Sync
+   - Click "Connect Gmail"
+   - Approve Google OAuth
+   - Click "Sync Now"
+   - Watch transactions flow in automatically! 🎉
+
+3. **Add Credit Cards** (Optional)
+   - Go to My Cards
+   - Add each card with billing details
+   - Link transactions to cards for cycle tracking
+
+4. **Set Up Bills** (Optional)
+   - Go to Bills & Surety
+   - Add recurring bills (rent, utilities, subscriptions)
+   - Mark predictable expenses as "Surety"
+
+5. **Track Investments** (NEW!)
+   
+   **Option A: Statement Import (Fastest)**
+   - Go to Wealth tab → Click purple Upload icon
+   - Select Source (CAMS / KFin / MFCentral)
+   - Upload statement file (CSV/Excel)
+   - Preview transactions → Click Import
+   - System auto-detects SIPs, step-ups, and skips
+   
+   **Option B: Manual Entry**
+   - Click "Link Transaction" to map investment expenses
+   - Or manually add holdings (MF, Stocks, FDs)
+   
+   **Analyze Your SIPs**
+   - Click any SIP holding → Switch to "SIP Date Analysis" tab
+   - See your actual performance vs alternative dates
+   - Get optimization recommendations
+   
+   Watch portfolio grow with daily NAV updates!
+
+### Daily Workflow
+
+**Automated (Recommended):**
+1. Gmail Sync runs automatically (or click "Sync Now")
+2. AI extracts transaction details
+3. Investment transactions auto-mapped to portfolio
+4. Review pending transactions in Transactions tab
+5. Verify or edit as needed
+6. Check Dashboard for safe-to-spend amount
+7. Monitor Wealth tab for portfolio performance
+
+**Manual Entry:**
+1. Click "+" button
+2. Enter transaction details
+3. Select category
+4. Save (auto-marked as verified)
+
+---
+
+## 🔌 API Documentation
+
+### Interactive Docs
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+### Key Endpoints
+
+#### Authentication
+```bash
+POST /api/v1/auth/register        # Register with OTP
+POST /api/v1/auth/verify-otp      # Verify OTP
+POST /api/v1/auth/token           # Login (JWT)
+```
+
+#### Gmail Sync
+```bash
+GET  /api/v1/sync/google/auth     # Get OAuth URL
+POST /api/v1/sync/google/callback # Complete OAuth
+GET  /api/v1/sync/status          # Check connection
+POST /api/v1/sync/manual          # Trigger sync
+GET  /api/v1/sync/history         # View sync logs
+DELETE /api/v1/sync/disconnect    # Disconnect Gmail
+```
+
+#### Transactions
+```bash
+GET  /api/v1/transactions                   # List all
+POST /api/v1/transactions/manual            # Manual entry
+GET  /api/v1/transactions/pending           # Pending review
+PUT  /api/v1/transactions/{id}              # Update
+DELETE /api/v1/transactions/{id}            # Delete
+POST /api/v1/transactions/{id}/verify       # Verify
+```
+
+#### Wealth & Investments (NEW!)
+```bash
+GET  /api/v1/wealth/holdings                     # List portfolio
+GET  /api/v1/wealth/holdings/{id}                # Holding details with snapshots
+POST /api/v1/wealth/holdings                     # Add new asset
+POST /api/v1/wealth/forecast                     # AI forecast (Prophet)
+POST /api/v1/wealth/map-transaction              # Link transaction to holding
+GET  /api/v1/wealth/sync-prices                  # Trigger manual price sync
+POST /api/v1/wealth/import-cams                  # Import CAMS statement (NEW!)
+GET  /api/v1/wealth/holdings/{id}/sip-analysis   # SIP date performance analysis (NEW!)
+```
+
+#### Analytics
+```bash
+GET /api/v1/analytics/safe-to-spend  # Real-time calculation
+GET /api/v1/analytics/variance       # Month-over-month
+GET /api/v1/analytics/monthly-summary # Monthly stats
+```
+
+#### Forecasting
+```bash
+GET /api/v1/dashboard/forecast  # 30-day AI prediction
+```
+
+---
+
+## 🚀 Deployment
+
+### Production Setup (Recommended)
+
+**Architecture:**
+- **Frontend**: Vercel (Free, unlimited bandwidth)
+- **Backend**: Railway (Serverless, $5/month credit)
+- **Database**: Supabase (Free tier, 500MB)
+- **Scheduled Tasks**: GitHub Actions (Free unlimited for public repos)
+
+**Total Cost: $0/month** (everything within free tiers!)
+
+---
+
+### Backend Deployment (Railway)
+
+#### 1. Initial Setup
+
+1. **Sign up at [railway.app](https://railway.app)** with GitHub
+2. **Create New Project** → Deploy from GitHub repo
+3. **Select your repository**
+4. **Configure Service:**
+   - Root Directory: `Backend`
+   - Start Command: `uvicorn app.main:app --host 0.0.0.0 --port $PORT`
+   - Watch Paths: `Backend/**`
+
+#### 2. Environment Variables
+
+Add these in Railway Dashboard → Variables:
+
+```bash
+# Database
+DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-1-ap-south-1.pooler.supabase.com:6543/postgres
+
+# Security
+SECRET_KEY=your-secret-key-here
+GRIP_SECRET=webhook-secret
+ENVIRONMENT=production
+
+# AI
+GROQ_API_KEY=your-groq-api-key
+GROQ_MODEL=llama-3.3-70b-versatile
+USE_AI_FORECASTING=true
+ENABLE_SCHEDULER=false  # Using GitHub Actions for scheduled tasks
+
+# Gmail OAuth
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+FRONTEND_ORIGIN=https://your-app.vercel.app
+
+# Email (OTP)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASSWORD=your-gmail-app-password
+FROM_EMAIL=noreply@grip.com
+FROM_NAME=Grip
+
+# Branding
+APP_NAME=Grip
+APP_TAGLINE=Money that minds itself.
+```
+
+#### 3. Generate Domain
+
+- Go to Settings → Generate Domain
+- Copy the URL (e.g., `https://grip-backend.up.railway.app`)
+- Update `VITE_API_BASE_URL` in frontend
+
+---
+
+### Scheduled Tasks (GitHub Actions)
+
+**Why GitHub Actions?**
+- ✅ **Free unlimited** for public repos (2,000 min/month for private)
+- ✅ Saves $1-2/month on Railway (serverless vs always-on)
+- ✅ Reliable cron scheduling
+- ✅ Easy monitoring via1. **Add Secrets** (One-time):
+   - Go to GitHub repo → Settings → Secrets → Actions
+   - Click "New repository secret" and add:
+     - `DATABASE_URL`: Your Supabase connection string.
+     - `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`: For email alerts.
+     - `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`: For Gmail OAuth.
+     - `GROQ_API_KEY`: For AI transaction extraction.
+     - `FRONTEND_ORIGIN`: Your deployment URL (e.g. `https://grip.vercel.app`).
+
+2. **Workflows are already configured**:
+   - `daily-price-sync.yml`: Runs at 3:30 PM IST (Price updates).
+   - `gmail_sync.yml`: Runs every hour (Transactions).
+   - `daily-intelligence.yml`: Runs at 9:00 AM IST (Reminders & Insights).
+
+3. **Test the Workflow**:
+   - Go to Actions tab
+   - Click "Daily Price Sync"
+   - Click "Run workflow" → "Run workflow"
+   - Check logs to verify success
+
+4. **Set Railway to Serverless**:
+   - In Railway Environment Variables:
+   - `ENABLE_SCHEDULER=false` (disables internal scheduler)
+   - This saves ~$1-2/month in Railway credits
+
+**Monitoring:**
+- View logs in GitHub Actions tab
+- Check Railway logs for API requests
+- Verify data updates in Supabase dashboard
+
+---
+
+### Frontend Deployment (Vercel)
+
+#### 1. Deploy to Vercel
+
+```bash
+cd Frontend
+npm run build
+vercel --prod
+```
+
+Or connect via Vercel Dashboard:
+1. Go to [vercel.com](https://vercel.com)
+2. Import Git Repository
+3. Select your repo
+4. Framework Preset: Vite
+5. Root Directory: `Frontend`
+6. Deploy!
+
+#### 2. Environment Variables
+
+Add in Vercel Dashboard → Settings → Environment Variables:
+
+```bash
+VITE_API_BASE_URL=https://grip-backend.up.railway.app/api/v1
+VITE_APP_NAME=Grip
+VITE_APP_TAGLINE=Money that minds itself.
+```
+
+#### 3. Update Google OAuth
+
+- Go to [Google Cloud Console](https://console.cloud.google.com)
+- APIs & Services → Credentials
+- Edit OAuth 2.0 Client
+- Add Authorized JavaScript Origins:
+  - `https://your-app.vercel.app`
+- Add Authorized Redirect URIs:
+  - `https://your-app.vercel.app`
+- Save
+
+---
+
+### Database Setup (Supabase)
+
+1. **Create Project** at [supabase.com](https://supabase.com)
+2. **Get Connection String**:
+   - Project Settings → Database
+   - Copy "Transaction" pooler string (port 6543)
+3. **Add to Railway** as `DATABASE_URL`
+4. **Add to GitHub Secrets** for Actions workflow
+
+**Important:** Use port **6543** (Transaction pooler), not 5432, for Railway compatibility.
+
+---
+
+### Cost Breakdown
+
+| Service | Free Tier | Your Usage | Cost |
+|---------|-----------|------------|------|
+| **Railway** (Serverless) | $5/month credit | ~$1-2/month | $0 |
+| **Vercel** (Frontend) | Unlimited | Unlimited | $0 |
+| **Supabase** (Database) | 500MB | ~50MB | $0 |
+| **GitHub Actions** (Cron) | Unlimited (public) | 30 min/month | $0 |
+| **Groq** (AI) | Free tier | ~1000 requests/month | $0 |
+
+**Total: $0/month** 🎉
+
+---
+
+### Deployment Checklist
+
+- [ ] Railway backend deployed with all env vars
+- [ ] Vercel frontend deployed with API URL
+- [ ] Supabase database created and connected
+- [ ] GitHub Actions secret added (`DATABASE_URL`)
+- [ ] Google OAuth redirect URIs updated
+- [ ] Test login flow
+- [ ] Test Gmail sync
+- [ ] Test scheduled task (manual trigger)
+- [ ] Verify investment price sync working
+
+---
+
+### Monitoring & Maintenance
+
+**Daily Checks:**
+- GitHub Actions logs (scheduled task status)
+- Railway logs (API errors)
+- Supabase dashboard (data integrity)
+
+**Weekly:**
+- Check Railway usage (should be <$2)
+- Review Groq API usage
+- Test critical flows (login, sync, forecast)
+
+**Monthly:**
+- Review GitHub Actions minutes (should be ~30)
+- Check Railway credit balance
+- Update dependencies if needed
+
+---
+
+## 🔒 Privacy & Data Handling
+
+### What We Store
+- Transaction metadata (amount, merchant, category, dates)
+- Investment snapshots (units, prices, dates)
+- Encrypted OAuth tokens (Gmail access)
+- User preferences and mappings
+- Sync logs (for debugging)
+
+### What We DON'T Store
+- Full email content
+- Credit card CVVs or PINs
+- Unmasked PAN/Aadhaar numbers
+- Gmail passwords
+- Any sensitive PII
+
+### Data Flow
+1. Email received in your Gmail
+2. OAuth token grants read access
+3. Email content fetched via API
+4. **Sanitization happens locally** (regex masking)
+5. Sanitized text sent to Groq for extraction
+6. Extracted JSON stored in database
+7. Investment transactions auto-mapped to holdings
+8. Daily price sync updates portfolio values
+9. Original email remains in your Gmail (unchanged)
+
+---
+
+## 🤝 Contributing
+
+This project is currently private. For feature requests or bug reports, please open an issue.
+
+---
+
+## 📝 License
+
+Private and proprietary. All rights reserved.
+
+---
+
+## 🛠️ Environment & Security Configuration
+
+Grip is designed with a "Privacy-First" and "Cloud-Resilient" architecture. Depending on where you deploy (Local vs. Cloud), you may need to adjust certain security measures:
+
+### 📧 Email Connection Modes
+Most cloud providers (Hugging Face, Railway) block **Ports 25, 587, and 465** to prevent spam. 
+- **Grip Email Relay (Microservice)**: By default, we use a dedicated relay service (located in `/EmailService`) intended for deployment on Vercel (Port 443) to bypass SMTP blocks. Configure `EMAIL_RELAY_URL` in your `.env`.
+- **Standard SMTP**: If running locally or on a VPS where ports are open, uncomment the `LEGACY DIRECT SMTP` block in `app/core/email.py` and set your Gmail App Password.
+
+### 🤖 LLM Intelligence & Fallbacks
+We utilize a dual-track AI system for maximum reliability:
+- **Grip Intelligence (Primary)**: A high-performance, private engine hosted on Hugging Face Spaces.
+- **Groq Llama-3 (Roboust Fallback)**: If the primary engine is sleeping or unreachable, Grip automatically falls back to Groq.
+- **Note**: Ensure `GROQ_API_KEY` is set in your environment variables. If you wish to use only Groq, uncomment the relevant lines in `app/core/llm.py`.
+
+### 🔐 Security Measures
+- **Sanitization First**: All PII (PAN, Account numbers) is masked via local regex logic *before* being processed by any AI engine.
+- **Scoped Ingress**: Gmail OAuth is restricted to `gmail.readonly` and specifically queries for transaction-only keywords.
+
+---
+
+## 🙏 Acknowledgments
+
+Built with incredible open-source tools:
+- **Groq** - Lightning-fast LLM inference
+- **Meta Prophet** - Time-series forecasting
+- **FastAPI** - Modern Python web framework
+- **React** - UI library
+- **PostgreSQL** - Robust database
+- **scipy** - Scientific computing for XIRR
+- **yfinance** - Stock market data
+- **mfapi.in** - Indian mutual fund NAV data
+- **Render** - Backend deployment
+- **Vercel** - Frontend deployment
+
+---
+
+## 📚 Documentation
+
+- **[Quick Start Guide](GMAIL_SYNC_QUICKSTART.md)** - 15-minute setup
+- **[CAMS Import Guide](CAMS_IMPORT_GUIDE.md)** - Import years of history in 60s
+- **[Implementation Details](GMAIL_SYNC_IMPLEMENTATION.md)** - Technical deep-dive
+- **[Session Summary](SESSION_SUMMARY.md)** - Recent updates
+
+---
+
+## 💬 Support
+
+For setup help or questions, refer to:
+1. **API Docs**: http://localhost:8000/docs
+2. **Troubleshooting**: Check `GMAIL_SYNC_IMPLEMENTATION.md`
+3. **Common Issues**: See "Troubleshooting" section in setup guides
+
+---
+
+<div align="center">
+
+**Grip** - Autonomous Financial Intelligence.
+
+*Made with ❤️ , effort and AI*
+
+</div>

app/core/config.py

@@ -0,0 +1,89 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+from typing import Optional
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "Grip"
+    API_V1_STR: str = "/api/v1"
+    ENVIRONMENT: str = "local"
+    APP_TIMEZONE: str = "Asia/Kolkata"  # Default to IST
+    
+    DATABASE_URL: str = ""
+    
+    SECRET_KEY: str = "SECRET_KEY"
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 3  # 3 days
+    GRIP_SECRET: str = ""
+    
+    EXCEPTION_ROUTES: list[str] = [
+        "/",
+        "/privacy",
+        "/terms",
+        "/docs", 
+        "/redoc", 
+        "/openapi.json", 
+        "/api/v1/openapi.json",
+        "/api/v1/auth/register", 
+        "/api/v1/auth/verify-otp",
+        "/api/v1/auth/token",
+        "/api/v1/auth/google-login",
+        "/api/v1/auth/google/one-tap",
+        "/api/v1/sync/webhook",
+        "/api/v1/internal/generate"  # Protected by X-Grip-Secret, not JWT
+    ]
+    
+    USE_AI_FORECASTING: bool = True
+    ENABLE_SCHEDULER: bool = True  # Set to False when using external cron (e.g., GitHub Actions)
+    
+    GROQ_API_KEY: str = ""
+    GROQ_MODEL: str = "llama-3.1-8b-instant"
+    
+    # Local LLM Settings
+    LOCAL_LLM_CONTEXT: int = 4096
+    LOCAL_MODEL_REPO: str = "bartowski/google_gemma-4-E4B-it-GGUF"
+    LOCAL_MODEL_FILE: str = "google_gemma-4-E4B-it-Q4_K_M.gguf"
+    LOCAL_MODEL_DIR: str = "models"
+    
+    GOOGLE_CLIENT_ID: str = ""
+    GOOGLE_CLIENT_SECRET: str = ""
+    FRONTEND_ORIGIN: str = "https://grip-akdey.vercel.app"  # Frontend URL for OAuth origin parameter
+    GOOGLE_REDIRECT_URI: str = "postmessage"
+    GMAIL_PUBSUB_TOPIC: Optional[str] = None
+
+    
+    # Firebase Settings
+    FIREBASE_CREDENTIALS_PATH: str = "firebase_credentials.json"
+    
+    
+    # Email Settings
+    SMTP_HOST: str = "smtp.gmail.com"
+    SMTP_PORT: int = 587
+    SMTP_USER: str = ""
+    SMTP_PASSWORD: str = ""
+    FROM_EMAIL: str = "noreply@grip.com"
+    FROM_NAME: str = "Grip"
+
+    # External Email Relay (for bypassing cloud SMTP blocks)
+    EMAIL_RELAY_URL: Optional[str] = "https://akdey-grip-email-relay.vercel.app/send"
+    EMAIL_RELAY_SECRET: Optional[str] = None
+    
+    # Branding
+    APP_NAME: str = "GRIP"
+    APP_TAGLINE: str = "Autonomous Financial Intelligence"
+    
+    @property
+    def ASYNC_DATABASE_URL(self) -> str:
+        url = self.DATABASE_URL
+        if url.startswith("postgresql://"):
+            url = url.replace("postgresql://", "postgresql+asyncpg://", 1)
+        
+        if "pgbouncer=true" in url:
+            url = url.replace("?pgbouncer=true", "").replace("&pgbouncer=true", "")
+            
+        return url
+
+    model_config = SettingsConfigDict(env_file=".env", case_sensitive=True, extra="ignore")
+
+@lru_cache()
+def get_settings():
+    return Settings()

app/core/database.py

@@ -0,0 +1,77 @@
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.pool import NullPool
+from app.core.config import get_settings
+import ssl
+
+settings = get_settings()
+
+# Handle missing DATABASE_URL
+db_url = settings.ASYNC_DATABASE_URL
+if not db_url:
+    print("WARNING: DATABASE_URL not set. Using in-memory SQLite.")
+    db_url = "sqlite+aiosqlite:///:memory:"
+
+# Initialize engine
+engine = None
+
+try:
+    connect_args = {}
+    poolclass = None
+    
+    if "sqlite" in db_url:
+        connect_args = {"check_same_thread": False}
+    else:
+        # PostgreSQL configuration
+        connect_args = {
+            "statement_cache_size": 0,  # Required for Supabase pooler
+            "server_settings": {
+                "application_name": "grip_backend",
+                "search_path": "public"
+            },
+            "timeout": 20,
+            "command_timeout": 20
+        }
+        
+        # Supabase-specific configuration
+        if "supabase" in db_url.lower():
+            # Permissive SSL context for Supabase
+            ssl_context = ssl.create_default_context()
+            ssl_context.check_hostname = False
+            ssl_context.verify_mode = ssl.CERT_NONE
+            connect_args["ssl"] = ssl_context
+
+    # Create engine with robust pooling
+    engine = create_async_engine(
+        db_url,
+        echo=False,
+        connect_args=connect_args,
+        pool_size=10,
+        max_overflow=20,
+        pool_recycle=300,
+        pool_pre_ping=True
+    )
+    
+except Exception as e:
+    print(f"CRITICAL: Failed to create database engine: {e}")
+    import traceback
+    traceback.print_exc()
+    # Fallback to SQLite
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:", poolclass=NullPool)
+
+# Session factory
+AsyncSessionLocal = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+    autoflush=False
+)
+
+# Base model
+class Base(DeclarativeBase):
+    pass
+
+# Dependency
+async def get_db():
+    async with AsyncSessionLocal() as session:
+        yield session

app/core/email.py

@@ -0,0 +1,108 @@
+import smtplib
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+import logging
+from app.core.config import get_settings
+
+settings = get_settings()
+logger = logging.getLogger(__name__)
+
+import httpx
+
+def send_email(to_email: str, subject: str, html_content: str):
+    """
+    Sends an email using either a Vercel Microservice relay (Approach C)
+    or standard SMTP if configured.
+    """
+    # External Relay (Recommended for cloud hosting like HF Spaces as required ports are blocked)
+    if settings.EMAIL_RELAY_URL and settings.EMAIL_RELAY_SECRET:
+        try:
+            payload = {
+                "to_email": to_email,
+                "subject": subject,
+                "html_content": html_content,
+                "from_name": settings.FROM_NAME
+            }
+            headers = {"X-Grip-Secret": settings.EMAIL_RELAY_SECRET}
+            
+            # Using synchronous request for simplicity in background tasks, 
+            # though async is generally better.
+            with httpx.Client() as client:
+                resp = client.post(settings.EMAIL_RELAY_URL, json=payload, headers=headers, timeout=15.0)
+                if resp.status_code == 200:
+                    return True
+                else:
+                    logger.error(f"Relay failed ({resp.status_code}): {resp.text}")
+                    return False
+        except Exception as e:
+            logger.error(f"Relay connection error: {e}")
+            return False
+
+    # --- LEGACY DIRECT SMTP (Approach A/B) ---
+    # NOTE: DO NOT REMOVE THIS BLOCK. 
+    # Standard SMTP (Port 587/465) is frequently blocked on cloud providers like HF Spaces.
+    # If using approach above, this code remains here as an alternative for local development.
+    if not settings.SMTP_USER or not settings.SMTP_PASSWORD:
+        logger.warning("SMTP credentials not set. Email not sent.")
+        return False
+
+    try:
+        message = MIMEMultipart("alternative")
+        message["Subject"] = subject
+        message["From"] = f"{settings.FROM_NAME} <{settings.FROM_EMAIL}>"
+        message["To"] = to_email
+
+        part = MIMEText(html_content, "html")
+        message.attach(part)
+
+        # Use SMTP_SSL for port 465, otherwise standard SMTP + starttls
+        if settings.SMTP_PORT == 465:
+            with smtplib.SMTP_SSL(settings.SMTP_HOST, settings.SMTP_PORT) as server:
+                server.login(settings.SMTP_USER, settings.SMTP_PASSWORD)
+                server.sendmail(settings.FROM_EMAIL, to_email, message.as_string())
+        else:
+            with smtplib.SMTP(settings.SMTP_HOST, settings.SMTP_PORT) as server:
+                server.starttls()
+                server.login(settings.SMTP_USER, settings.SMTP_PASSWORD)
+                server.sendmail(settings.FROM_EMAIL, to_email, message.as_string())
+        
+        return True
+    except Exception as e:
+        logger.error(f"Failed to send email to {to_email}: {e}")
+        return False
+
+    logger.warning("No email relay or SMTP configured accurately.")
+    return False
+
+def send_otp_email(to_email: str, otp: str):
+    subject = f"Your {settings.APP_NAME} Verification Code: {otp}"
+    html_content = f"""
+    <html>
+        <body style="font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color: #1e293b; line-height: 1.6; margin: 0; padding: 20px; background-color: #f8fafc;">
+            <div style="max-width: 500px; margin: 0 auto; background: white; padding: 40px; border-radius: 20px; border: 1px solid #e2e8f0; box-shadow: 0 10px 25px -5px rgba(0,0,0,0.05);">
+                <div style="margin-bottom: 30px; text-align: left;">
+                    <span style="font-size: 24px; font-weight: 900; letter-spacing: -0.02em; color: #111;">GRIP</span>
+                    <div style="height: 4px; width: 40px; background: #4F46E5; margin-top: 4px; border-radius: 2px;"></div>
+                </div>
+                
+                <h2 style="color: #111; margin-top: 0; font-size: 22px; font-weight: 800;">Verify your email</h2>
+                <p style="color: #475569; font-size: 16px;">Welcome! Please use the verification code below to complete your sign-in to {settings.APP_NAME}.</p>
+                
+                <div style="background: #f1f5f9; padding: 30px; border-radius: 12px; margin: 25px 0; text-align: center; border: 1px solid #e2e8f0;">
+                    <span style="font-size: 36px; font-weight: 900; letter-spacing: 12px; color: #111; font-family: monospace; display: block; margin-left: 12px;">{otp}</span>
+                </div>
+                
+                <p style="font-size: 14px; color: #94a3b8; text-align: center;">This code will expire in 10 minutes.</p>
+                
+                <div style="margin-top: 40px; border-top: 1px solid #f1f5f9; padding-top: 20px;">
+                    <p style="font-size: 14px; color: #64748b; margin: 0;">Stay focused,</p>
+                    <p style="font-size: 14px; font-weight: bold; color: #111; margin: 4px 0;">The {settings.APP_NAME} Team</p>
+                </div>
+            </div>
+            <div style="max-width: 500px; margin: 10px auto; text-align: center;">
+                <p style="font-size: 11px; color: #94a3b8;">If you didn't request this code, you can safely ignore this email.</p>
+            </div>
+        </body>
+    </html>
+    """
+    return send_email(to_email, subject, html_content)

app/core/llm.py

@@ -0,0 +1,300 @@
+import logging
+import re
+import httpx
+import json
+import asyncio
+import os
+import threading
+from typing import Optional, Dict, Any, List
+from app.core.config import get_settings
+
+print(">>> LLM MODULE IMPORTED", flush=True)
+
+# Global flag to track if llama-cpp is available and usable on this system.
+HAS_LLAMA_CPP = False 
+try:
+    import llama_cpp
+    HAS_LLAMA_CPP = True
+    print(">>> LLM_ENGINE: llama-cpp-python imported successfully.", flush=True)
+except Exception as e:
+    # Capturing the error to help debug HF Space deployment issues
+    print(f">>> LLM_ENGINE: Failed to import llama-cpp-python: {e}", flush=True)
+    pass
+
+settings = get_settings()
+logger = logging.getLogger(__name__)
+
+class LocalLLMEngine:
+    """Handles local execution of GGUF models using llama-cpp-python."""
+    
+    def __init__(self):
+        self._model = None
+        self._lock = threading.Lock()
+        self.repo_id = settings.LOCAL_MODEL_REPO
+        self.filename = settings.LOCAL_MODEL_FILE
+        self.models_dir = settings.LOCAL_MODEL_DIR
+        
+    def _ensure_model(self):
+        """Lazy load and potentially download the model. Thread-safe."""
+        with self._lock:
+            if self._model:
+                return self._model
+                
+            try:
+                from llama_cpp import Llama
+                from huggingface_hub import hf_hub_download
+            except Exception as e:
+                logger.error(f"Cannot load local LLM engine (likely missing system dependencies for llama_cpp): {e}")
+                return None
+                
+            try:
+                # Create models directory if it doesn't exist
+                os.makedirs(self.models_dir, exist_ok=True)
+                
+                # Check for model existence. Use absolute path for reliability in Docker containers.
+                model_path = os.path.abspath(os.path.join(self.models_dir, self.filename))
+                logger.info(f"LocalLLMEngine: Checking for model at {model_path}")
+                
+                if os.path.exists(model_path):
+                    file_size = os.path.getsize(model_path)
+                    logger.info(f"LocalLLMEngine: Model file found. Size: {file_size / (1024*1024):.2f} MB")
+                    if file_size < 100 * 1024 * 1024: # Less than 100MB is likely a pointer/corrupted for a 1.7B model
+                        logger.warning(f"LocalLLMEngine: Model file seems too small ({file_size} bytes). It might be an LFS pointer. Re-downloading...")
+                        os.remove(model_path)
+                
+                if not os.path.exists(model_path):
+                    logger.warning(f"LocalLLMEngine: Model not found at expected path or removed. Attempting download from {self.repo_id}...")
+                    downloaded_path = hf_hub_download(
+                        repo_id=self.repo_id,
+                        filename=self.filename,
+                        local_dir=self.models_dir
+                    )
+                    model_path = os.path.abspath(downloaded_path)
+                    logger.info(f"LocalLLMEngine: Download complete. Size: {os.path.getsize(model_path) / (1024*1024):.2f} MB")
+                
+                # Initialize Llama-cpp with optimized context and caching
+                # n_ctx: 2048 (default) - Sufficient for long emails + context
+                # n_threads: Use all available cores to speed up inference
+                import multiprocessing
+                threads = max(2, multiprocessing.cpu_count())
+                
+                self._model = Llama(
+                    model_path=model_path,
+                    n_ctx=settings.LOCAL_LLM_CONTEXT,
+                    n_threads=threads,
+                    n_gpu_layers=0, # Force CPU
+                    logits_all=False,
+                    flash_attn=True, # Speeds up KV cache for Gemma architectures
+                    verbose=False
+                )
+                logger.info(f"Local LLM engine initialized (ctx: {settings.LOCAL_LLM_CONTEXT}, threads: {threads}).")
+                return self._model
+            except Exception as e:
+                logger.error(f"Failed to initialize local LLM engine: {e}")
+                return None
+
+    def _strip_thoughts(self, text: str) -> str:
+        """Removes internal thinking blocks from Gemma 4 output."""
+        if not text:
+            return text
+        # Gemma 4 thought pattern: <|channel>thought ... <channel|>
+        text = re.sub(r'<\|channel>thought.*?<channel\|>', '', text, flags=re.DOTALL)
+        return text.strip()
+
+    def generate(self, prompt: str, system_prompt: str, temperature: float) -> Optional[str]:
+        """Generate response using the local model."""
+        model = self._ensure_model()
+        if not model:
+            return None
+            
+        try:
+            # Format prompt for Gemma 4
+            formatted_prompt = f"<|turn>system\n{system_prompt} <turn|>\n<|turn>user\n{prompt} <turn|>\n<|turn>model\n"
+            
+            logger.debug(f"LocalLLMEngine: Starting inference with Gemma 4...")
+            import time
+            start_t = time.perf_counter()
+            output = model(
+                formatted_prompt,
+                max_tokens=512, # Optimized for JSON response with more prompt headroom
+                temperature=temperature,
+                stop=["<turn|>", "<|turn>", "<|im_end|>", "<|endoftext|>"],
+                echo=False
+            )
+            inf_time = (time.perf_counter() - start_t) * 1000
+            raw_text = output['choices'][0]['text'].strip()
+            text = self._strip_thoughts(raw_text)
+            logger.info(f"LocalLLMEngine: Inference complete. Took {inf_time:.2f}ms. Generated {len(text)} characters.")
+            return text
+        except Exception as e:
+            logger.error(f"Error during local LLM inference: {e}")
+            return None
+
+class LLMService:
+    """Centralized service for Large Language Model interactions."""
+    
+    def __init__(self):
+        self.groq_api_key = settings.GROQ_API_KEY
+        self.groq_model = settings.GROQ_MODEL
+        self.groq_url = "https://api.groq.com/openai/v1/chat/completions"
+        self.local_engine = LocalLLMEngine()
+        
+        # PII patterns for sanitizing content before sending to external APIs
+        self._pii_patterns = [
+            # (re.compile(r'[a-zA-Z0-9.\-_]{2,}@[a-zA-Z]{2,}'), '<UPI>'),  # Allow LLM to read UPI based merchants
+            (re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'), '<EMAIL>'),
+            (re.compile(r'(?:\+?91|0)?[6-9]\d{9}'), '<PHONE>'),
+            (re.compile(r'(?:\d[ -]*?){12,19}'), '<CARD>'),
+            (re.compile(r'[Xx]+\d{3,6}'), '<ACCOUNT>'),
+            (re.compile(r'[A-Z]{5}[0-9]{4}[A-Z]{1}'), '<PAN>'),
+            (re.compile(r'\d{4}\s\d{4}\s\d{4}'), '<AADHAAR>'),
+        ]
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if any LLM service is available."""
+        return HAS_LLAMA_CPP # or bool(self.groq_api_key)
+
+    def _sanitize_for_external(self, text: str) -> str:
+        """Extra PII scrub before sending to any external/third-party LLM API."""
+        if not text:
+            return text
+        text = re.sub(r'(?i)(Dear|Hello|Hi)\s+[A-Za-z\s]+,', r'\1 Customer,', text)
+        for pattern, label in self._pii_patterns:
+            text = pattern.sub(label, text)
+        return text
+
+    async def generate_response(
+        self, 
+        prompt: str, 
+        system_prompt: Optional[str] = "You are a helpful financial assistant.",
+        temperature: float = 0.5,
+        response_format: Optional[str] = None,
+        timeout: float = 120.0 # Increased timeout for local inference
+    ) -> Optional[str]:
+        """Generic method to generate a response, prioritizing local execution."""
+        global HAS_LLAMA_CPP
+        
+        # 1. Try Local Engine (Primary — high privacy, no costs)
+        if HAS_LLAMA_CPP:
+            # We run in a threadpool to avoid blocking the event loop
+            try:
+                loop = asyncio.get_event_loop()
+                res = await loop.run_in_executor(
+                    None, 
+                    self.local_engine.generate, 
+                    prompt, 
+                    system_prompt, 
+                    temperature
+                )
+                if res:
+                    logger.info(">>> LLM_ENGINE: Local (Gemma 4) success.")
+                    return res
+                # If we get here it means inference failed or engine is broken
+            except Exception as e:
+                # If it fails once with a severe error (like shared lib missing), we can disable it 
+                # for the rest of this worker's lifecycle to stop log spam.
+                if "shared object file" in str(e) or "libc" in str(e).lower():
+                    HAS_LLAMA_CPP = False
+                    logger.error(f">>> LLM_ENGINE: Fatal library error. Disabling local LLM: {e}")
+                else:
+                    logger.warning(f">>> LLM_ENGINE: Local engine runtime error: {e}")
+
+        # 2. Try Groq (Fallback — external API, sanitize content)
+        # if self.groq_api_key:
+        #     logger.info(f">>> LLM_ENGINE: Falling back to Groq ({self.groq_model})...")
+        #     sanitized_prompt = self._sanitize_for_external(prompt)
+        #     result = await self._call_groq(sanitized_prompt, system_prompt, temperature, response_format, timeout)
+        #     if result:
+        #         logger.info(">>> LLM_ENGINE: Groq success.")
+        #     return result
+            
+        logger.warning("Local LLM engine is unavailable. Groq fallback is disabled.")
+        return None
+
+    async def _call_groq(
+        self, 
+        prompt: str, 
+        system_prompt: str, 
+        temperature: float, 
+        response_format: Optional[str], 
+        timeout: float
+    ) -> Optional[str]:
+        """Call the Groq API (Fallback provider). Content must be pre-sanitized."""
+        headers = {
+            "Authorization": f"Bearer {self.groq_api_key}",
+            "Content-Type": "application/json"
+        }
+
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+
+        payload = {
+            "model": self.groq_model,
+            "messages": messages,
+            "temperature": temperature
+        }
+
+        if response_format == "json_object":
+            payload["response_format"] = {"type": "json_object"}
+
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.post(self.groq_url, headers=headers, json=payload, timeout=timeout)
+                if resp.status_code == 200:
+                    return resp.json()['choices'][0]['message']['content']
+                elif resp.status_code == 429:
+                    logger.error(f"Groq API Rate Limit Reached (429). Falling back to Regex engine.")
+                    return None
+                else:
+                    logger.error(f"Groq API Error ({resp.status_code}): {resp.text[:200]}")
+                    return None
+        except Exception as e:
+            logger.error(f"Groq Connection Error: {type(e).__name__}: {e}")
+            return None
+
+    async def generate_json(
+        self, 
+        prompt: str, 
+        system_prompt: Optional[str] = "You are a financial intelligence engine. Always output valid JSON objects.",
+        temperature: float = 0.2,
+        timeout: float = 60.0
+    ) -> Optional[Dict[str, Any]]:
+        """Method specifically for JSON responses with robust parsing."""
+        content = await self.generate_response(
+            prompt=prompt,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            response_format="json_object",
+            timeout=timeout
+        )
+        
+        if not content:
+            return None
+            
+        try:
+            json_match = re.search(r'(\{.*\})', content, re.DOTALL)
+            if json_match:
+                content = json_match.group(1)
+            
+            content = content.strip().replace('```json', '').replace('```', '').strip()
+            return json.loads(content)
+        except (json.JSONDecodeError, IndexError) as e:
+            logger.error(f"LLM JSON Decode Error: {e}. Content: {content[:200]}...")
+            try:
+                # Last resort cleanup
+                cleaned = re.sub(r',\s*([\]\}])', r'\1', content)
+                return json.loads(cleaned)
+            except Exception:
+                return None
+
+# Singleton-like instance
+_llm_service = None
+
+def get_llm_service() -> LLMService:
+    global _llm_service
+    if _llm_service is None:
+        _llm_service = LLMService()
+    return _llm_service

app/core/logging_config.py

@@ -0,0 +1,75 @@
+import logging
+import sys
+import os
+import re
+from logging.handlers import RotatingFileHandler
+
+from app.core.config import get_settings
+
+# PII Patterns (Sync with SanitizerService)
+PII_PATTERNS = {
+    # 'UPI': re.compile(r'[a-zA-Z0-9.\-_]{2,}@[a-zA-Z]{2,}'),
+    'EMAIL': re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'),
+    'PHONE': re.compile(r'(?:\+?91|0)?[6-9]\d{9}'),
+    'CARD': re.compile(r'(?:\d[ -]*?){12,19}'),
+    'ACCOUNT': re.compile(r'[Xx]+\d{3,6}'),
+    'PAN': re.compile(r'[A-Z]{5}[0-9]{4}[A-Z]{1}'),
+    'AADHAAR': re.compile(r'\d{4}\s\d{4}\s\d{4}'),
+}
+
+class PIISanitizingFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        # Original formatted message
+        message = super().format(record)
+        
+        # Sanitize greetings
+        message = re.sub(r'(?i)(Dear|Hello|Hi)\s+[A-Za-z\s]+,', r'\1 Customer,', message)
+        
+        # Sanitize patterns
+        for label, pattern in PII_PATTERNS.items():
+            message = pattern.sub(f'<{label}>', message)
+            
+        return message
+
+# Configure basic logging to output to console and file
+def setup_logging():
+    settings = get_settings()
+    log_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    
+    # Custom Formatter
+    formatter = PIISanitizingFormatter(log_format)
+    
+    # Console Handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    handlers = [console_handler]
+    
+    # Only add file logging if in local environment (Vercel has read-only FS)
+    if settings.ENVIRONMENT == "local":
+        # Ensure logs directory exists
+        log_dir = "logs"
+        if not os.path.exists(log_dir):
+            os.makedirs(log_dir)
+        
+        log_file = os.path.join(log_dir, "app.log")
+        file_handler = RotatingFileHandler(log_file, maxBytes=5*1024*1024, backupCount=5)
+        file_handler.setFormatter(formatter)
+        handlers.append(file_handler)
+    
+    # Reset any existing handlers
+    root_logger = logging.getLogger()
+    for h in root_logger.handlers[:]:
+        root_logger.removeHandler(h)
+        
+    logging.basicConfig(
+        level=logging.INFO,
+        handlers=handlers
+    )
+    
+    # Set levels for noisy libraries
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+    logging.getLogger("python_multipart").setLevel(logging.WARNING)
+
+# Removed setup_logging() call from here - it's called in app/main.py
+logger = logging.getLogger("app")

app/core/middleware.py

@@ -0,0 +1,74 @@
+from fastapi import Request, Response, status
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from jose import jwt, JWTError
+from app.core.config import get_settings
+
+settings = get_settings()
+import logging
+logger = logging.getLogger(__name__)
+
+class AuthenticationMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        # 1. Check for Bypass/Exception Routes
+        path = request.url.path
+        
+        is_exception = False
+        for route in settings.EXCEPTION_ROUTES:
+            if route == "/":
+                if path == "/":
+                    is_exception = True
+                    break
+            elif path.startswith(route):
+                is_exception = True
+                break
+        
+        if is_exception:
+            logger.debug(f"Bypassing authentication for path: {path}")
+            return await call_next(request)
+        
+        # 2. Extract Token
+        auth_header = request.headers.get("Authorization")
+        if not auth_header or not auth_header.startswith("Bearer "):
+            logger.warning(f"Authentication failed: Missing or invalid token for path {path}")
+            return JSONResponse(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                content={"detail": "Not authenticated"}
+            )
+        
+        token = auth_header.split(" ")[1]
+        
+        # 3. Validate Token
+        try:
+            payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+            email: str = payload.get("sub")
+            if email is None:
+                raise JWTError
+        except JWTError:
+            logger.warning(f"Authentication failed: Invalid token for path {path}")
+            return JSONResponse(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                content={"detail": "Could not validate credentials"}
+            )
+            
+        # 4. Stateless Authentication
+        # We trust the token signature. We do NOT hit the DB here.
+        # Downstream dependencies (get_current_user) will fetch the full user object if needed.
+        request.state.user_email = email
+        # logger.debug(f"Token valid for {email}, proceeding statelessly for {path}")
+        
+        # 5. Process request
+        import time
+        start_time = time.perf_counter()
+        try:
+            response = await call_next(request)
+            process_time = (time.perf_counter() - start_time) * 1000
+            logger.info(f"PERF: {response.status_code} for {path} | Total: {process_time:.2f}ms")
+            return response
+        except Exception as e:
+            logger.error(f"Error in middleware processing {path}: {e}", exc_info=True)
+            return JSONResponse(
+                status_code=500,
+                content={"detail": "Internal Server Error in Middleware", "msg": str(e)}
+            )
+

app/core/scheduler.py

@@ -0,0 +1,395 @@
+
+import logging
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from apscheduler.triggers.cron import CronTrigger
+from sqlalchemy.ext.asyncio import AsyncSession
+from typing import Optional
+
+from app.core.database import AsyncSessionLocal
+from app.core.config import get_settings
+from app.features.wealth.service import WealthService
+from app.features.sync.service import SyncService
+from app.features.transactions.service import TransactionService
+from app.features.categories.service import CategoryService
+from app.core.llm import get_llm_service
+from sqlalchemy import select, and_
+from datetime import datetime, date, timedelta
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+scheduler = AsyncIOScheduler()
+
+async def run_daily_price_sync():
+    """
+    Task to sync prices for all investment holdings.
+    Runs daily.
+    """
+    logger.info("Starting Daily Price Sync...")
+    from app.features.auth.models import User
+    from app.features.wealth.models import InvestmentHolding, InvestmentSnapshot
+    from app.features.credit_cards.models import CreditCard
+    from app.features.bills.models import Bill
+    
+    async with AsyncSessionLocal() as db:
+        service = WealthService(db)
+        try:
+            # We need to implement sync_all_holdings in WealthService first
+            await service.sync_all_holdings_prices() 
+            logger.info("Daily Price Sync Completed Successfully.")
+        except Exception as e:
+            logger.error(f"Daily Price Sync Failed: {e}", exc_info=True)
+
+async def run_surety_reminders():
+    """
+    Check for payments due exactly 1 or 2 days from today and send notifications.
+    Includes explicit Bills, Credit Cards, and Auto-detected Sureties.
+    """
+    logger.info("Starting Surety Reminders Scan (1 & 2 days prior)...")
+    import zoneinfo
+    from app.features.auth.models import User
+    from app.features.bills.service import BillService
+    from app.features.credit_cards.service import CreditCardService
+    from app.features.notifications.service import NotificationService
+    
+    tz = zoneinfo.ZoneInfo(settings.APP_TIMEZONE)
+    today = datetime.now(tz).date()
+    target_dates = [today + timedelta(days=1), today + timedelta(days=2)]
+    
+    async with AsyncSessionLocal() as db:
+        llm_service = get_llm_service()
+        notification_service = NotificationService(db, llm_service)
+        bill_service = BillService()
+        cc_service = CreditCardService()
+        
+        # 1. Fetch all users
+        stmt_users = select(User)
+        res_users = await db.execute(stmt_users)
+        users = res_users.scalars().all()
+        
+        for user in users:
+            full_name = user.full_name or user.email.split('@')[0]
+            
+            # --- PART A: Credit Cards ---
+            try:
+                cards = await cc_service.get_user_cards(db, user.id, active_only=True)
+                for card in cards:
+                    # Calculate next payment due date in Asia/Kolkata
+                    due_day = card.payment_due_date
+                    try:
+                        due_date = today.replace(day=due_day)
+                    except ValueError:
+                        from calendar import monthrange
+                        last_day = monthrange(today.year, today.month)[1]
+                        due_date = today.replace(day=last_day)
+                        
+                    if due_date < today:
+                        # Move to next month
+                        if today.month == 12:
+                            next_month = date(today.year + 1, 1, 1)
+                        else:
+                            next_month = date(today.year, today.month + 1, 1)
+                        try:
+                            due_date = next_month.replace(day=due_day)
+                        except ValueError:
+                            from calendar import monthrange
+                            last_day = monthrange(next_month.year, next_month.month)[1]
+                            due_date = next_month.replace(day=last_day)
+                            
+                    if due_date in target_dates:
+                        # Calculate unbilled amount
+                        from app.utils.finance_utils import get_billing_cycle_dates
+                        cycle_dates = get_billing_cycle_dates(card.statement_date)
+                        unbilled = await cc_service.get_unbilled_amount(
+                            db,
+                            card.id,
+                            cycle_dates["cycle_start"],
+                            cycle_dates["cycle_end"]
+                        )
+                        if unbilled > 0:
+                            await notification_service.send_surety_reminder(
+                                user.id,
+                                full_name,
+                                f"{card.card_name} Payment",
+                                float(unbilled),
+                                datetime.combine(due_date, datetime.min.time())
+                            )
+                            logger.info(f"Sent credit card reminder for card: {card.card_name} to user {user.id}")
+            except Exception as e:
+                logger.error(f"Failed to check credit card reminders for user {user.id}: {e}")
+
+            # --- PART B: Bills & Auto-detected Sureties ---
+            try:
+                ledger = await bill_service.get_obligations_ledger(db, user.id, days_ahead=60, include_hidden=False)
+                for item in ledger["items"]:
+                    if item.type in ["BILL", "SURETY_TXN"]:
+                        if item.status in ["PROJECTED", "PENDING", "OVERDUE"]:
+                            # We check if due date matches one of our target dates
+                            if item.due_date in target_dates:
+                                await notification_service.send_surety_reminder(
+                                    user.id,
+                                    full_name,
+                                    item.title,
+                                    float(item.amount),
+                                    datetime.combine(item.due_date, datetime.min.time())
+                                )
+                                logger.info(f"Sent reminder for {item.type}: {item.title} to user {user.id}")
+            except Exception as e:
+                logger.error(f"Failed to check ledger reminders for user {user.id}: {e}")
+                
+    logger.info("Surety Reminders Completed.")
+
+async def run_weekly_insights():
+    """
+    Analyze spending for the last 7 days and send insights if growth is detected.
+    """
+    logger.info("Starting Weekly Insights Analysis...")
+    from sqlalchemy import func
+    from app.features.auth.models import User
+    from app.features.transactions.models import Transaction
+    from app.features.bills.models import Bill
+    from app.features.credit_cards.models import CreditCard
+    from app.features.notifications.service import NotificationService
+    
+    async with AsyncSessionLocal() as db:
+        llm_service = get_llm_service()
+        notification_service = NotificationService(db, llm_service)
+        
+        # 1. Find categories where spend > 1000 in last 7 days
+        # Exclude 'Investment'
+        seven_days_ago = datetime.now() - timedelta(days=7)
+        
+        stmt = (
+            select(User.id, User.full_name, Transaction.category, func.sum(func.abs(Transaction.amount)).label("total"))
+            .join(Transaction, User.id == Transaction.user_id)
+            .where(Transaction.transaction_date >= seven_days_ago.date())
+            .where(Transaction.category != 'Investment')
+            .group_by(User.id, User.full_name, Transaction.category)
+            .having(func.sum(func.abs(Transaction.amount)) > 1000)
+        )
+        
+        result = await db.execute(stmt)
+        data = result.all()
+        logger.info(f"Weekly Insights: Found {len(data)} user/category pairs over ₹1,000 threshold.")
+        
+        # 2. Group by user for consolidated emails
+        user_insights = {}
+        for user_id, full_name, category, total in data:
+            if user_id not in user_insights:
+                user_insights[user_id] = {
+                    "full_name": full_name,
+                    "items": []
+                }
+            user_insights[user_id]["items"].append({
+                "category": category,
+                "amount": float(total)
+            })
+            
+        # 3. Send consolidated emails
+        for user_id, info in user_insights.items():
+            try:
+                await notification_service.send_weekly_summary(
+                    user_id, 
+                    info["full_name"], 
+                    info["items"]
+                )
+                logger.info(f"Sent consolidated weekly recap to user {user_id} ({len(info['items'])} categories)")
+            except Exception as e:
+                logger.error(f"Failed to send weekly recap for user {user_id}: {e}")
+
+    logger.info("Weekly Insights Completed.")
+
+
+async def run_monthly_report(target_date: Optional[date] = None):
+    """
+    Generate and send a comprehensive monthly report for the previous month.
+    Generally runs on the 1st of the month.
+    """
+    logger.info("Starting Monthly Report Generation...")
+    from app.features.auth.models import User
+    from app.features.bills.models import Bill
+    from app.features.credit_cards.models import CreditCard
+    from app.features.analytics.service import AnalyticsService
+    
+    # If today is March 1st, we want February's data
+    ref_date = target_date or date.today()
+    if ref_date.day == 1:
+        prev_month_date = ref_date - timedelta(days=1)
+        month_idx = prev_month_date.month
+        year_idx = prev_month_date.year
+    else:
+        month_idx = ref_date.month
+        year_idx = ref_date.year
+
+    async with AsyncSessionLocal() as db:
+        from app.features.notifications.service import NotificationService
+        notification_service = NotificationService(db)
+        analytics_service = AnalyticsService()
+        
+        result = await db.execute(select(User))
+        users = result.scalars().all()
+        
+        for user in users:
+            try:
+                # Get full monthly summary & variance
+                summary = await analytics_service.get_monthly_summary(db, user.id, month=month_idx, year=year_idx)
+                variance = await analytics_service.get_variance_analysis(db, user.id, month=month_idx, year=year_idx)
+                
+                await notification_service.send_monthly_report(
+                    user_id=user.id,
+                    full_name=user.full_name,
+                    summary=summary,
+                    variance=variance
+                )
+                logger.info(f"Sent monthly report to {user.id} for {month_idx}/{year_idx}")
+            except Exception as e:
+                logger.error(f"Failed monthly report for {user.id}: {e}")
+
+    logger.info("Monthly Report Job Completed.")
+    
+async def run_lifestyle_insights(override_date: Optional[date] = None):
+    """
+    Perform periodic checks for inactivity and special events (like Fridays).
+    """
+    logger.info(f"Starting Lifestyle Insights Trigger... (Override: {override_date})")
+    from app.features.auth.models import User
+    from app.features.transactions.models import Transaction
+    from app.features.bills.models import Bill
+    from app.features.credit_cards.models import CreditCard
+    from app.features.analytics.service import AnalyticsService
+    from sqlalchemy import func
+    
+    today = override_date or date.today()
+    
+    async with AsyncSessionLocal() as db:
+        from app.features.notifications.service import NotificationService
+        notification_service = NotificationService(db)
+        analytics_service = AnalyticsService()
+        
+        # 1. Fetch all users
+        result = await db.execute(select(User))
+        users = result.scalars().all()
+        
+        for user in users:
+            try:
+                # --- CHECK 1: INACTIVITY ---
+                # Check for the last transaction date
+                stmt = select(func.max(Transaction.transaction_date)).where(Transaction.user_id == user.id)
+                res = await db.execute(stmt)
+                last_txn_date = res.scalar()
+                
+                if last_txn_date:
+                    days_diff = (today - last_txn_date).days
+                    # If inactive for exactly 7 or 14 days, send a nudge
+                    if days_diff in [7, 14]:
+                        await notification_service.send_inactivity_nudge(user.id, user.full_name, days_diff)
+                        logger.info(f"Sent inactivity nudge to {user.id} ({days_diff} days)")
+
+                # --- CHECK 2: BUFFER EMERGENCY BRAKE ---
+                # Check if safe-to-spend is below the required buffer
+                sts_data = await analytics_service.calculate_safe_to_spend_amount(db, user.id)
+                # If safe-to-spend is zero or negative, it means the buffer is exhausted
+                if sts_data.safe_to_spend <= 0:
+                    await notification_service.send_buffer_alert(user.id, user.full_name, float(sts_data.safe_to_spend))
+                    logger.info(f"Sent buffer emergency brake to {user.id}")
+
+                # --- CHECK 3: WEEKEND (FRIDAY) ---
+                if today.weekday() == 4: # 4 is Friday
+                    # Calculate safe-to-spend for this user
+                    sts_data = await analytics_service.calculate_safe_to_spend_amount(db, user.id)
+                    
+                    # Fetch top category for the last 7 days for more insight
+                    seven_days_ago = today - timedelta(days=7)
+                    cat_stmt = (
+                        select(Transaction.category, func.sum(func.abs(Transaction.amount)).label("total"))
+                        .where(Transaction.user_id == user.id)
+                        .where(Transaction.transaction_date >= seven_days_ago)
+                        .where(Transaction.category.notin_(["Income", "Transfer"]))
+                        .group_by(Transaction.category)
+                        .order_by(func.sum(func.abs(Transaction.amount)).desc())
+                        .limit(1)
+                    )
+                    cat_res = await db.execute(cat_stmt)
+                    top_cat_row = cat_res.first()
+                    top_category = top_cat_row.category if top_cat_row else None
+                    
+                    # Trigger the AI-driven weekend insight with more context
+                    await notification_service.send_weekend_insight(
+                        user_id=user.id, 
+                        full_name=user.full_name, 
+                        safe_to_spend=float(sts_data.safe_to_spend),
+                        current_balance=float(sts_data.current_balance),
+                        top_category=top_category
+                    )
+                    logger.info(f"Sent weekend insight to {user.id}")
+                    
+            except Exception as e:
+                logger.error(f"Error in lifestyle insight for user {user.id}: {e}")
+                
+    logger.info("Lifestyle Insights Completed.")
+
+async def run_gmail_sync():
+    """
+    Task to sync Gmail transactions for all users.
+    """
+    logger.info("Starting Gmail Sync...")
+    async with AsyncSessionLocal() as db:
+        # Import models inside function to avoid circular imports and ensure registry is ready
+        from app.features.auth.models import User
+        # Ensure relationships are loaded
+        from app.features.credit_cards.models import CreditCard
+        from app.features.bills.models import Bill
+        from app.features.notifications.service import NotificationService
+        
+        # Instantiate services
+        llm_service = get_llm_service()
+        cat_service = CategoryService(db)
+        wealth_service = WealthService(db)
+        txn_service = TransactionService(db)
+        notif_service = NotificationService(db, llm_service)
+        sync_service = SyncService(db, txn_service, cat_service, wealth_service, notif_service, llm_service)
+        
+        # Fetch users with gmail credentials
+        stmt = select(User).where(User.gmail_credentials.isnot(None))
+        result = await db.execute(stmt)
+        users = result.scalars().all()
+        
+        logger.info(f"Found {len(users)} users with Gmail credentials.")
+        
+        for user in users:
+            try:
+                logger.info(f"Syncing Gmail for user {user.id}...")
+                await sync_service.execute_sync(user.id, "SCHEDULED_TASK")
+            except Exception as e:
+                logger.error(f"Gmail sync failed for user {user.id}: {e}")
+                
+    logger.info("Gmail Sync Completed.")
+
+def start_scheduler():
+    """
+    Start the scheduler if ENABLE_SCHEDULER is True.
+    Set ENABLE_SCHEDULER=False when using external cron (e.g., GitHub Actions).
+    """
+    if not settings.ENABLE_SCHEDULER:
+        logger.info("Scheduler disabled (ENABLE_SCHEDULER=False). Using external cron.")
+        return
+    
+    # Schedule the job to run at 3:30 PM IST (10:00 AM UTC)
+    # IST is UTC+5:30. 15:30 IST = 10:00 UTC.
+    trigger = CronTrigger(hour=10, minute=0)  # 10:00 AM UTC = 3:30 PM IST
+    
+    scheduler.add_job(run_daily_price_sync, trigger)
+    
+    # Run Gmail sync every hour
+    scheduler.add_job(run_gmail_sync, 'interval', hours=1)
+    
+    # Run Surety reminders daily at 7:00 AM IST (1:30 AM UTC)
+    reminder_trigger = CronTrigger(hour=1, minute=30)
+    scheduler.add_job(run_surety_reminders, reminder_trigger)
+    
+    # Run Weekly Insights on Sunday at 10:00 AM IST (4:30 AM UTC)
+    insight_trigger = CronTrigger(day_of_week='sun', hour=4, minute=30)
+    scheduler.add_job(run_weekly_insights, insight_trigger)
+    
+    scheduler.start()
+    logger.info("Scheduler started. Jobs scheduled.")

app/core/security.py

@@ -0,0 +1,28 @@
+from datetime import datetime, timedelta
+from typing import Optional
+from jose import jwt
+from passlib.context import CryptContext
+from app.core.config import get_settings
+
+settings = get_settings()
+
+pwd_context = CryptContext(schemes=["argon2", "bcrypt"], deprecated="auto")
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    # Bcrypt has a max length limit of 72 bytes, truncate input to avoid crash
+    return pwd_context.verify(plain_password[:72], hashed_password)
+
+def get_password_hash(password: str) -> str:
+    # Bcrypt has a max length limit of 72 bytes for passwords
+    # We truncate excessively long passwords to prevent crashing
+    return pwd_context.hash(password[:72])
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
+    to_encode = data.copy()
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+    return encoded_jwt

app/features/analytics/router.py

@@ -0,0 +1,85 @@
+from typing import Annotated, Optional
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.database import get_db
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.analytics.schemas import (
+    VarianceAnalysis,
+    FrozenFundsBreakdown,
+    SafeToSpendResponse,
+    MonthlySummaryResponse,
+    SpendTrendResponse,
+    SpendTrendFrequency
+)
+from app.features.analytics.service import AnalyticsService
+
+router = APIRouter()
+
+@router.get("/summary/", response_model=MonthlySummaryResponse)
+async def get_monthly_summary(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[AnalyticsService, Depends()],
+    month: Optional[int] = Query(None, ge=1, le=12),
+    year: Optional[int] = Query(None, ge=2000, le=2100),
+    scope: str = Query("month", enum=["month", "year", "all"])
+):
+    """
+    Get financial summary (Income vs Expense) for a specific scope.
+    """
+    return await service.get_monthly_summary(db, current_user.id, month, year, scope)
+
+
+@router.get("/variance/", response_model=VarianceAnalysis)
+async def get_variance_analysis(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[AnalyticsService, Depends()],
+    month: Optional[int] = Query(None, ge=1, le=12),
+    year: Optional[int] = Query(None, ge=2000, le=2100)
+):
+    """
+    Get spending variance analysis for a specific period.
+    """
+    return await service.get_variance_analysis(db, current_user.id, month, year)
+
+
+@router.get("/burden/", response_model=FrozenFundsBreakdown)
+async def get_burden_calculation(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[AnalyticsService, Depends()]
+):
+    """
+    Calculate total frozen funds (burden).
+    Formula: UnpaidBills + ProjectedSuretyBills + UnbilledCC
+    """
+    return await service.calculate_burden(db, current_user.id)
+
+
+@router.get("/safe-to-spend/", response_model=SafeToSpendResponse)
+async def get_safe_to_spend(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[AnalyticsService, Depends()]
+):
+    """
+    Calculate safe-to-spend amount with AI-predicted buffer till salary (1st of next month).
+    Buffer = AI prediction of discretionary expenses till next salary
+    Formula: Balance - FrozenFunds - AI Buffer
+    """
+    return await service.calculate_safe_to_spend_amount(db, current_user.id)
+
+@router.get("/trends/spend/", response_model=SpendTrendResponse)
+async def get_spend_trends(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[AnalyticsService, Depends()],
+    days: int = Query(30, ge=7, le=90),
+    frequency: SpendTrendFrequency = Query(SpendTrendFrequency.DAILY)
+):
+    """
+    Get spending trends for the last N days with specific frequency.
+    """
+    return await service.get_spend_trends(db, current_user.id, days, frequency)

app/features/analytics/schemas.py

@@ -0,0 +1,68 @@
+from enum import Enum
+from typing import Dict, List, Optional
+from pydantic import BaseModel
+from decimal import Decimal
+from datetime import date
+
+class SpendTrendFrequency(str, Enum):
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+
+class CategoryVariance(BaseModel):
+    current: Decimal
+    previous: Decimal
+    variance_amount: Decimal
+    variance_percentage: float
+    trend: str # "up", "down", "stable"
+
+class VarianceAnalysis(BaseModel):
+    current_month_total: Decimal
+    last_month_total: Decimal
+    variance_amount: Decimal
+    variance_percentage: float
+    category_breakdown: Dict[str, CategoryVariance]
+
+class IdentifiedObligation(BaseModel):
+    id: str
+    title: str
+    amount: Decimal
+    due_date: date
+    type: str # "BILL", "SIP", "SURETY_TXN", "GOAL"
+    status: str # "OVERDUE", "PENDING", "PROJECTED"
+    category: Optional[str] = None
+    sub_category: Optional[str] = None
+    source_id: Optional[str] = None
+
+class FrozenFundsBreakdown(BaseModel):
+    unpaid_bills: Decimal
+    projected_surety: Decimal
+    unbilled_cc: Decimal
+    active_goals: Decimal = Decimal(0)
+    total_frozen: Decimal
+    obligations: List[IdentifiedObligation] = []
+
+class SafeToSpendResponse(BaseModel):
+    current_balance: Decimal
+    frozen_funds: FrozenFundsBreakdown
+    buffer_amount: Decimal
+    buffer_percentage: float
+    safe_to_spend: Decimal
+    recommendation: str
+    status: str # "success", "warning", "critical", "negative"
+
+class MonthlySummaryResponse(BaseModel):
+    total_income: Decimal
+    total_expense: Decimal
+    balance: Decimal
+    month: str
+    year: int
+    current_period_expense: Decimal = Decimal(0)
+    prior_period_settlement: Decimal = Decimal(0)
+
+class SpendTrendPoint(BaseModel):
+    date: date
+    amount: Decimal
+
+class SpendTrendResponse(BaseModel):
+    trends: List[SpendTrendPoint]

app/features/analytics/service.py

@@ -0,0 +1,582 @@
+import logging
+import asyncio
+import calendar
+import time
+from uuid import UUID
+from decimal import Decimal
+from typing import List, Optional, Dict
+from datetime import date, timedelta
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func, case
+from app.features.transactions.models import Transaction, AccountType
+from app.features.goals.models import Goal
+from app.features.analytics.schemas import (
+    CategoryVariance,
+    VarianceAnalysis,
+    FrozenFundsBreakdown,
+    SafeToSpendResponse,
+    MonthlySummaryResponse
+)
+from app.features.bills.service import BillService
+from app.features.credit_cards.service import CreditCardService
+from app.utils.finance_utils import (
+    calculate_frozen_funds,
+    calculate_safe_to_spend,
+    calculate_variance_percentage,
+    get_trend_indicator,
+    get_month_date_range,
+    get_previous_month_date_range,
+    get_year_date_range
+)
+
+from datetime import datetime, date, timedelta
+import zoneinfo
+from app.core.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+class AnalyticsService:
+    
+    def __init__(self):
+        self.bill_service = BillService()
+        self.cc_service = CreditCardService()
+        self._tz = zoneinfo.ZoneInfo(settings.APP_TIMEZONE)
+
+    def _get_today(self) -> date:
+        """Get current date in the configured timezone."""
+        return datetime.now(self._tz).date()
+    
+    async def get_variance_analysis(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        month: Optional[int] = None,
+        year: Optional[int] = None
+    ) -> VarianceAnalysis:
+        """Calculate period vs previous period variance."""
+        target_date = self._get_today()
+        if month and year:
+            target_date = date(year, month, 1)
+            
+        current_range = get_month_date_range(target_date)
+        previous_range = get_previous_month_date_range(target_date)
+        
+        # Current month spending
+        # Prepare Current month spending query
+        current_stmt = (
+            select(
+                Transaction.category,
+                func.sum(Transaction.amount).label("total")
+            )
+            .where(Transaction.user_id == user_id)
+            .where(Transaction.category.notin_(["Income"]))
+            .where(Transaction.transaction_date >= current_range["month_start"])
+            .where(Transaction.transaction_date <= current_range["month_end"])
+            .group_by(Transaction.category)
+        )
+        
+        # Prepare Previous month spending query
+        previous_stmt = (
+            select(
+                Transaction.category,
+                func.sum(Transaction.amount).label("total")
+            )
+            .where(Transaction.user_id == user_id)
+            .where(Transaction.category.notin_(["Income"]))
+            .where(Transaction.transaction_date >= previous_range["month_start"])
+            .where(Transaction.transaction_date <= previous_range["month_end"])
+            .group_by(Transaction.category)
+        )
+        
+        # Execute sequentially to avoid "another operation is in progress" errors
+        current_res = await db.execute(current_stmt)
+        previous_res = await db.execute(previous_stmt)
+        
+        current_by_category = {row.category: abs(row.total or Decimal("0")) for row in current_res.all()}
+        current_total = sum(current_by_category.values())
+        
+        previous_by_category = {row.category: abs(row.total or Decimal("0")) for row in previous_res.all()}
+        previous_total = sum(previous_by_category.values())
+        
+        # Calculate category-level variance
+        all_categories = set(current_by_category.keys()) | set(previous_by_category.keys())
+        category_breakdown = {}
+        
+        for category in all_categories:
+            current_amount = current_by_category.get(category, Decimal("0"))
+            previous_amount = previous_by_category.get(category, Decimal("0"))
+            variance_amt = current_amount - previous_amount
+            variance_pct = calculate_variance_percentage(current_amount, previous_amount)
+            
+            category_breakdown[category] = CategoryVariance(
+                current=current_amount,
+                previous=previous_amount,
+                variance_amount=variance_amt,
+                variance_percentage=variance_pct,
+                trend=get_trend_indicator(variance_pct)
+            )
+        
+        # Overall variance
+        total_variance = current_total - previous_total
+        total_variance_pct = calculate_variance_percentage(
+            Decimal(str(current_total)),
+            Decimal(str(previous_total))
+        )
+        
+        return VarianceAnalysis(
+            current_month_total=Decimal(str(current_total)),
+            last_month_total=Decimal(str(previous_total)),
+            variance_amount=Decimal(str(total_variance)),
+            variance_percentage=total_variance_pct,
+            category_breakdown=category_breakdown
+        )
+    
+    async def calculate_burden(
+        self,
+        db: AsyncSession,
+        user_id: UUID
+    ) -> FrozenFundsBreakdown:
+        """Calculate total frozen funds (burden) with a detailed obligation ledger."""
+        try:
+            from app.features.analytics.schemas import IdentifiedObligation
+            import calendar
+            # wealth_service removed for decoupling
+
+            
+            today = self._get_today()
+            _, last_day = calendar.monthrange(today.year, today.month)
+            days_till_month_end = last_day - today.day
+            
+            goal_stmt = (
+                select(Goal)
+                .where(Goal.user_id == user_id)
+                .where(Goal.is_active == True)
+            )
+            
+            # 1. Execute multiple independent checks sequentially to avoid concurrency conflicts
+            ledger_data = await self.bill_service.get_obligations_ledger(db, user_id, days_ahead=days_till_month_end)
+            unbilled_cc = await self.cc_service.get_all_unbilled_for_user(db, user_id)
+            goal_res = await db.execute(goal_stmt)
+
+            # 2. Process Bill/Surety results
+            unpaid_bills_total = ledger_data["unpaid_total"]
+            projected_surety_bills = ledger_data["projected_total"]
+            all_obligations = ledger_data["items"]
+            
+            # 3. Process SIP Commitments (Placeholder)
+            sip_total = Decimal("0")
+            total_projected_surety = projected_surety_bills + sip_total
+            
+            # 4. Process Goals
+            active_goals_total = Decimal("0")
+            goals = goal_res.scalars().all()
+            for g in goals:
+                amt = Decimal(str(g.monthly_contribution))
+                active_goals_total += amt
+                # Add goals to ledger items
+                all_obligations.append(IdentifiedObligation(
+                    id=f"goal-{g.id}",
+                    title=f"Goal: {g.name}",
+                    amount=amt,
+                    due_date=date.today() + timedelta(days=15),
+                    type="GOAL",
+                    status="PROJECTED",
+                    category="Goal",
+                    sub_category=g.category
+                ))
+            
+            total_frozen = calculate_frozen_funds(unpaid_bills_total, total_projected_surety, unbilled_cc) + active_goals_total
+            
+            return FrozenFundsBreakdown(
+                unpaid_bills=unpaid_bills_total,
+                projected_surety=total_projected_surety,
+                unbilled_cc=unbilled_cc,
+                active_goals=active_goals_total,
+                total_frozen=total_frozen,
+                obligations=all_obligations
+            )
+
+
+        except Exception as e:
+            logger.error(f"Error calculating burden: {e}")
+            # Return safe zeros to prevent 500
+            zero = Decimal("0.00")
+            return FrozenFundsBreakdown(
+                unpaid_bills=zero,
+                projected_surety=zero,
+                unbilled_cc=zero,
+                active_goals=zero,
+                total_frozen=zero
+            )
+    
+    # Global memory cache for Safe-to-Spend results
+    _safe_spend_cache = {} # user_id -> (result, timestamp)
+    SAFE_SPEND_TTL = 60 # 60 seconds
+
+    async def calculate_safe_to_spend_amount(self, db: AsyncSession, user_id: UUID, days_till_salary: Optional[int] = None) -> SafeToSpendResponse:
+        """Calculate the amount the user can safely spend until next salary."""
+        # 0. Check Hot Cache
+        now = time.time()
+        if user_id in self._safe_spend_cache:
+            res_obj, timestamp = self._safe_spend_cache[user_id]
+            if now - timestamp < self.SAFE_SPEND_TTL:
+                return res_obj
+
+        try:
+            # Calculate days till salary (1st of next month)
+            today = self._get_today()
+            if today.day == 1:
+                # If today is 1st, assume salary already received, buffer till next month's 1st
+                days_till_salary = 30  # Approximate
+            else:
+                # Days remaining in current month
+                import calendar
+                _, last_day = calendar.monthrange(today.year, today.month)
+                days_till_salary = last_day - today.day + 1
+            
+            # 1. Prepare combined query to fetch everything in ONE trip
+            today_date = self._get_today()
+            thirty_days_ago = today_date - timedelta(days=30)
+            
+            # Subquery for discretionary sum
+            discretionary_sub = (
+                select(func.sum(Transaction.amount))
+                .where(Transaction.user_id == user_id)
+                .where(Transaction.category.notin_(["Income", "Investment", "Housing", "Bill Payment", "Transfer", "EMI", "Loan", "Insurance", "Misc"]))
+                .where(Transaction.sub_category != "Credit Card Payment")
+                .where(Transaction.is_surety == False)
+                .where(func.abs(Transaction.amount) <= 5000)
+                .where(Transaction.transaction_date >= thirty_days_ago)
+                .where(Transaction.transaction_date <= today_date)
+                .scalar_subquery()
+            )
+
+            # Subquery for Goals
+            goal_sub = (
+                select(func.sum(Goal.monthly_contribution))
+                .where(Goal.user_id == user_id)
+                .where(Goal.is_active == True)
+                .scalar_subquery()
+            )
+
+            # Subquery for unbilled CC
+            # We only count UNSETTLED and NON-SURETY transactions to avoid double counting with obligations
+            unbilled_cc_sub = (
+                select(func.sum(Transaction.amount))
+                .where(Transaction.user_id == user_id)
+                .where(Transaction.category != "Income")
+                .where(Transaction.account_type == AccountType.CREDIT_CARD)
+                .where(Transaction.is_settled == False)
+                .where(Transaction.is_surety == False)
+                .scalar_subquery()
+            )
+
+            # Mega query: Total Balance, Txn Count, Discretionary Sum, Goals, and Unbilled CC
+            mega_stmt = (
+                select(
+                    func.sum(Transaction.amount).label("balance"),
+                    func.count(Transaction.id).label("txn_count"),
+                    discretionary_sub.label("discretionary_sum"),
+                    goal_sub.label("goals_total"),
+                    unbilled_cc_sub.label("unbilled_cc")
+                )
+                .where(Transaction.user_id == user_id)
+                .where(Transaction.account_type.in_([AccountType.CASH, AccountType.SAVINGS]))
+            )
+
+            # 2. Execute sequentially - only 2 main hits: Mega + Ledger
+            mega_res = (await db.execute(mega_stmt)).one()
+            # We still need the ledger for specific unpaid bills and projections
+            ledger_data = await self.bill_service.get_obligations_ledger(db, user_id, days_ahead=days_till_salary)
+            
+            # 3. Process results
+            current_balance = mega_res.balance or Decimal("0")
+            total_transactions = mega_res.txn_count or 0
+            is_new_user = total_transactions == 0
+            total_discretionary_30d = abs(mega_res.discretionary_sum or Decimal("0"))
+            
+            # Extract combined burden components
+            unpaid_bills = ledger_data["unpaid_total"]
+            projected_surety = ledger_data["projected_total"]
+            unbilled_cc = abs(mega_res.unbilled_cc or Decimal("0"))
+            active_goals = mega_res.goals_total or Decimal("0")
+            
+            total_frozen = unpaid_bills + projected_surety + unbilled_cc + active_goals
+            
+            frozen_breakdown = FrozenFundsBreakdown(
+                unpaid_bills=unpaid_bills,
+                projected_surety=projected_surety,
+                unbilled_cc=unbilled_cc,
+                active_goals=active_goals,
+                total_frozen=total_frozen,
+                obligations=ledger_data["items"]
+            )
+            
+            # Calculate average daily discretionary expense
+            avg_daily_discretionary = total_discretionary_30d / Decimal("30")
+            
+            # Buffer = Average daily discretionary × days till salary
+            buffer = avg_daily_discretionary * Decimal(str(days_till_salary))
+            
+            # Only enforce minimum buffer if user has positive balance
+            if current_balance > 0:
+                min_buffer = Decimal("500")
+                buffer = max(buffer, min_buffer)
+            else:
+                # No/negative balance means no buffer needed
+                buffer = Decimal("0")
+            
+            # Set method for display
+            buffer_method = "average"
+            buffer_confidence = "medium"
+            
+            # Calculate safe-to-spend
+            # If balance is zero or negative, safe_to_spend should be 0 (can't spend what you don't have)
+            if current_balance <= 0:
+                safe_amount = Decimal("0")
+            else:
+                safe_amount = current_balance - frozen_breakdown.total_frozen - buffer
+                # Cap at 0 minimum (can't spend negative amounts)
+                safe_amount = max(Decimal("0"), safe_amount)
+            
+            # Calculate buffer as percentage for response (for UI display)
+            buffer_percentage = float(buffer / current_balance) if current_balance > 0 else 0.0
+            
+            # Format salary date for display
+            next_month = today.replace(day=1) + timedelta(days=32)
+            salary_date = next_month.replace(day=1)
+            salary_str = salary_date.strftime("%b %d")
+            
+            # Generate recommendation based on user state
+            status = "success"
+            
+            if is_new_user:
+                recommendation = "👋 Welcome! Add your first transaction to start tracking your finances."
+                status = "success"
+            elif current_balance < 0:
+                deficit = abs(current_balance)
+                recommendation = f"📉 Balance is ₹{deficit:.0f} in deficit. Add income to recover."
+                status = "negative"
+            elif current_balance == 0:
+                recommendation = "⚠️ No liquid balance available. Please add income transactions."
+                status = "warning"
+            elif safe_amount == 0:
+                overextended = frozen_breakdown.total_frozen + buffer - current_balance
+                recommendation = f"🔒 Overextended by ₹{overextended:.0f}. Frozen + Buffer exceed balance."
+                status = "critical"
+            elif safe_amount < (current_balance * Decimal("0.20")):
+                recommendation = f"⚡ Low capacity. ₹{buffer:.0f} reserved till salary ({salary_str})"
+                status = "warning"
+            else:
+                recommendation = f"✅ Healthy! ₹{buffer:.0f} buffered till salary ({salary_str})"
+                status = "success"
+            
+            response = SafeToSpendResponse(
+                current_balance=current_balance,
+                frozen_funds=frozen_breakdown,
+                buffer_amount=buffer,
+                buffer_percentage=buffer_percentage,
+                safe_to_spend=safe_amount,
+                recommendation=recommendation,
+                status=status
+            )
+            
+            # Update Hot Cache
+            self._safe_spend_cache[user_id] = (response, time.time())
+            return response
+        except Exception as e:
+            logger.error(f"Error calculating safe to spend: {e}")
+            # ... (error handling code remains the same) ...
+            # Return safe default
+            zero = Decimal("0.00")
+            empty_breakdown = FrozenFundsBreakdown(
+                unpaid_bills=zero,
+                projected_surety=zero,
+                unbilled_cc=zero,
+                active_goals=zero,
+                total_frozen=zero
+            )
+            return SafeToSpendResponse(
+                current_balance=zero,
+                frozen_funds=empty_breakdown,
+                buffer_amount=zero,
+                buffer_percentage=0.0,
+                safe_to_spend=zero,
+                recommendation="⚠️ Unable to calculate. Please check system logs.",
+                status="warning"
+            )
+
+    async def debug_buffer_Calculation(self, db: AsyncSession, user_id: UUID):
+        """Debug method to show WHAT is being included in buffer calculation."""
+        today_date = self._get_today()
+        thirty_days_ago = today_date - timedelta(days=30)
+        
+        # EXACT SAME logic as calculation
+        stmt = (
+            select(Transaction)
+            .where(Transaction.user_id == user_id)
+            .where(Transaction.category.notin_(["Income", "Investment", "Housing", "Bill Payment", "Transfer", "EMI", "Loan", "Insurance", "Misc"]))
+            .where(Transaction.sub_category != "Credit Card Payment")
+            .where(Transaction.is_surety == False)
+            .where(func.abs(Transaction.amount) <= 5000)  # Exclude large one-off purchases > 5k
+            .where(Transaction.transaction_date >= thirty_days_ago)
+            .where(Transaction.transaction_date <= today_date)
+            .order_by(Transaction.amount) # Sort by amount (negative first = biggest spenders)
+        )
+        
+        result = await db.execute(stmt)
+        txns = result.scalars().all()
+        
+        total = sum(abs(t.amount) for t in txns)
+        
+        return {
+            "total_discretionary_30d": total,
+            "daily_average": total / 30,
+            "count": len(txns),
+            "transactions": [
+                {
+                    "date": t.transaction_date,
+                    "amount": t.amount,
+                    "merchant": t.merchant_name,
+                    "category": t.category,
+                    "sub_category": t.sub_category
+                }
+                for t in txns
+            ]
+        }
+
+    async def get_monthly_summary(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        month: Optional[int] = None,
+        year: Optional[int] = None,
+        scope: str = "month"
+    ) -> MonthlySummaryResponse:
+        import datetime
+        
+        target_date = self._get_today()
+        if month and year:
+            target_date = date(year, month, 1)
+        
+        # Determine date range based on scope
+        if scope == "year":
+            date_range = get_year_date_range(target_date)
+            start_date = date_range["year_start"]
+            end_date = date_range["year_end"]
+            period_label = str(start_date.year)
+        elif scope == "all":
+            # For all time, start from year 2000
+            start_date = date(2000, 1, 1)
+            end_date = date(2100, 12, 31)
+            period_label = "All Time"
+        else:
+            # Default to month
+            date_range = get_month_date_range(target_date)
+            start_date = date_range["month_start"]
+            end_date = date_range["month_end"]
+            period_label = start_date.strftime("%B")
+
+        # Consolidated Summary Query
+        # We use conditional aggregation (CASE statements) to get all totals in one trip
+        # This replaces 4 sequential trips with 1.
+        summary_stmt = (
+            select(
+                func.sum(case((Transaction.category == "Income", Transaction.amount), else_=0)).label("total_income"),
+                func.sum(case((Transaction.category != "Income", Transaction.amount), else_=0)).label("total_expense_raw"),
+                func.sum(case((Transaction.sub_category == "Credit Card Payment", Transaction.amount), else_=0)).label("prior_settlement"),
+                func.sum(Transaction.amount).label("net_balance")
+            )
+            .where(Transaction.user_id == user_id)
+            .where(Transaction.transaction_date >= start_date)
+            .where(Transaction.transaction_date <= end_date)
+        )
+        
+        res = (await db.execute(summary_stmt)).one()
+        
+        total_income = res.total_income or Decimal("0")
+        total_expense_raw = abs(res.total_expense_raw or Decimal("0"))
+        prior_period_settlement = abs(res.prior_settlement or Decimal("0"))
+        net_balance = res.net_balance or Decimal("0")
+        
+        # Current Period Expense is Total Expense minus the settlements
+        current_period_expense = total_expense_raw - prior_period_settlement
+        
+        return MonthlySummaryResponse(
+            total_income=total_income,
+            total_expense=total_expense_raw,
+            balance=net_balance,
+            month=period_label,
+            year=target_date.year,
+            current_period_expense=current_period_expense,
+            prior_period_settlement=prior_period_settlement
+        )
+
+    async def get_spend_trends(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        days: int = 30,
+        frequency: str = "daily"
+    ):
+        """Get spending trends for the last N days/weeks/months."""
+        from app.features.analytics.schemas import SpendTrendPoint, SpendTrendResponse
+        
+        today = self._get_today()
+        
+        if frequency == "monthly":
+            # Group by month for last 6 months
+            start_date = (today.replace(day=1) - timedelta(days=180)).replace(day=1)
+            date_field = func.date_trunc('month', Transaction.transaction_date)
+            limit_points = 6
+        elif frequency == "weekly":
+            # Group by week for last 12 weeks
+            start_date = today - timedelta(weeks=12)
+            date_field = func.date_trunc('week', Transaction.transaction_date)
+            limit_points = 12
+        else:
+            # Default Daily
+            start_date = today - timedelta(days=days + 5)
+            date_field = Transaction.transaction_date
+            limit_points = days
+
+        stmt = (
+            select(
+                date_field.label("date"),
+                func.sum(func.abs(Transaction.amount)).label("amount")
+            )
+            .where(Transaction.user_id == user_id)
+            .where(Transaction.category.notin_(["Income", "Transfer"]))
+            .where(Transaction.transaction_date >= start_date)
+            .where(Transaction.transaction_date <= today)
+            .group_by(date_field)
+            .order_by(date_field)
+        )
+        
+        result = await db.execute(stmt)
+        data_points = result.all()
+        
+        if frequency == "daily":
+            # Apply 3-day rolling average for daily
+            trends_map = {row.date: row.amount for row in data_points}
+            all_daily = []
+            full_start = today - timedelta(days=days + 2)
+            for i in range(days + 3):
+                d = full_start + timedelta(days=i)
+                all_daily.append({"date": d, "amount": trends_map.get(d, Decimal("0"))})
+            
+            final_trends = []
+            for i in range(2, len(all_daily)):
+                d = all_daily[i]["date"]
+                if d < today - timedelta(days=days - 1): continue
+                avg_amount = (all_daily[i]["amount"] + all_daily[i-1]["amount"] + all_daily[i-2]["amount"]) / 3
+                final_trends.append(SpendTrendPoint(date=d, amount=avg_amount))
+            return SpendTrendResponse(trends=final_trends)
+
+        # For Weekly and Monthly, just return the data points
+        return SpendTrendResponse(trends=[
+            SpendTrendPoint(date=row.date if isinstance(row.date, date) else row.date.date(), amount=row.amount)
+            for row in data_points
+        ])

app/features/auth/deps.py

@@ -0,0 +1,53 @@
+from fastapi import Request, HTTPException, status, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.features.auth.models import User
+from app.core.database import get_db
+
+import time
+
+# Global in-memory user cache
+_user_cache = {} # email -> (user_obj, timestamp)
+USER_CACHE_TTL = 600 # 10 minutes
+
+async def get_current_user(request: Request, db: AsyncSession = Depends(get_db)) -> User:
+    # 1. Check if user is already attached to this specific request
+    if hasattr(request.state, "user") and request.state.user:
+        return request.state.user
+
+    # 2. Check for email claim from stateless middleware
+    email = getattr(request.state, "user_email", None)
+    if not email:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required"
+        )
+    
+    # 3. Check Global Memory Cache
+    now = time.time()
+    if email in _user_cache:
+        user, expiry = _user_cache[email]
+        if now < expiry:
+            request.state.user = user
+            return user
+    
+    # 4. Fetch User from DB (Cache Miss)
+    result = await db.execute(select(User).where(User.email == email))
+    user = result.scalar_one_or_none()
+    
+    if not user:
+         raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found"
+        )
+        
+    if not user.is_active:
+         raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Inactive user"
+        )
+
+    # 5. Update Global Cache
+    _user_cache[email] = (user, now + USER_CACHE_TTL)
+    request.state.user = user
+    return user

app/features/auth/models.py

@@ -0,0 +1,23 @@
+import uuid
+from sqlalchemy import String, Boolean, DateTime, JSON
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+from app.core.database import Base
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    email: Mapped[str] = mapped_column(String, unique=True, index=True)
+    full_name: Mapped[str] = mapped_column(String, nullable=True)
+    hashed_password: Mapped[str] = mapped_column(String)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    fcm_token: Mapped[str] = mapped_column(String, nullable=True)
+    gmail_credentials: Mapped[dict] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    
+    verification_code: Mapped[str] = mapped_column(String, nullable=True)
+    verification_code_expires_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), nullable=True)
+    
+    credit_cards: Mapped[list["CreditCard"]] = relationship("CreditCard", back_populates="user")
+    bills: Mapped[list["Bill"]] = relationship("Bill", back_populates="user")

app/features/auth/router.py

@@ -0,0 +1,269 @@
+from datetime import timedelta, datetime, timezone
+from typing import Annotated, Optional
+from fastapi import APIRouter, Depends, HTTPException, status, BackgroundTasks
+from fastapi.security import OAuth2PasswordRequestForm
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from pydantic import BaseModel
+from google.oauth2 import id_token
+from google.auth.transport import requests as google_requests
+
+from app.core.database import get_db
+from app.core.security import create_access_token, get_password_hash, verify_password
+from app.features.auth.models import User
+from app.features.auth import schemas
+from app.core.config import get_settings
+from app.core.llm import get_llm_service
+from app.features.notifications.service import NotificationService
+
+import logging
+import random
+import string
+
+router = APIRouter()
+settings = get_settings()
+logger = logging.getLogger(__name__)
+
+class GoogleLoginRequest(BaseModel):
+    token: str
+
+@router.post("/register", response_model=dict)
+async def register_user(
+    user_in: schemas.UserCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    background_tasks: BackgroundTasks
+):
+    # Check if user exists
+    result = await db.execute(select(User).where(User.email == user_in.email))
+    existing_user = result.scalar_one_or_none()
+    
+    from app.core.email import send_otp_email
+
+    otp = ''.join(random.choices(string.digits, k=6))
+    otp_expiry = datetime.now(timezone.utc) + timedelta(minutes=10)
+
+    if existing_user:
+        if existing_user.is_active:
+            raise HTTPException(
+                status_code=400,
+                detail="User with this email already exists"
+            )
+        else:
+            # Resend OTP
+            existing_user.hashed_password = get_password_hash(user_in.password)
+            existing_user.verification_code = otp
+            existing_user.verification_code_expires_at = otp_expiry
+            db.add(existing_user)
+            await db.commit()
+            
+            background_tasks.add_task(send_otp_email, user_in.email, otp)
+            return {"message": "OTP sent to email", "email": user_in.email}
+    
+    user = User(
+        email=user_in.email,
+        hashed_password=get_password_hash(user_in.password),
+        is_active=False,
+        verification_code=otp,
+        verification_code_expires_at=otp_expiry
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    
+    background_tasks.add_task(send_otp_email, user_in.email, otp)
+    return {"message": "OTP sent to email", "email": user_in.email}
+
+@router.post("/google/one-tap", response_model=schemas.Token)
+async def google_one_tap(
+    payload: dict,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    background_tasks: BackgroundTasks
+):
+    """
+    Combined Login + Gmail Sync authorization.
+    Exchanges an Authorization Code for tokens, registers the user, 
+    and saves Gmail credentials in one go.
+    """
+    from app.features.sync.router import get_google_flow
+    
+    code = payload.get("code")
+    redirect_uri = payload.get("redirect_uri", "postmessage")
+    
+    if not code:
+        raise HTTPException(status_code=400, detail="Missing authorization code")
+
+    try:
+        # 1. Exchange Code for Tokens
+        flow = get_google_flow(redirect_uri)
+        flow.fetch_token(code=code)
+        creds = flow.credentials
+        
+        # 2. Extract Identity from ID Token
+        # We need to manually verify the ID token if fetch_token doesn't expose it ready-to-use
+        # or use creds.id_token
+        id_info = id_token.verify_oauth2_token(
+            creds.id_token, 
+            google_requests.Request(), 
+            settings.GOOGLE_CLIENT_ID
+        )
+        
+        email = id_info['email']
+        full_name = id_info.get('name')
+
+        # 3. Handle User Record
+        result = await db.execute(select(User).where(User.email == email))
+        user = result.scalar_one_or_none()
+        
+        is_new_user = False
+        if not user:
+            user = User(
+                email=email,
+                full_name=full_name,
+                is_active=True,
+                hashed_password="EXTERNAL_AUTH_GOOGLE"
+            )
+            db.add(user)
+            is_new_user = True
+        
+        # 4. Save Gmail Credentials
+        # We store the dict format of credentials
+        user.gmail_credentials = {
+            "token": creds.token,
+            "refresh_token": creds.refresh_token,
+            "token_uri": creds.token_uri,
+            "client_id": creds.client_id,
+            "client_secret": creds.client_secret,
+            "scopes": creds.scopes
+        }
+        user.is_active = True # Ensure they are active if they reconnect
+
+        await db.commit()
+        await db.refresh(user)
+
+        # 5. Welcome Email for New Users
+        if is_new_user:
+            from app.features.notifications.service import NotificationService
+            llm = get_llm_service()
+            notif_service = NotificationService(db, llm)
+            background_tasks.add_task(notif_service.send_welcome_email, email, full_name)
+
+        # 6. Generate Grip Token
+        access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+        access_token = create_access_token(
+            data={"sub": user.email}, expires_delta=access_token_expires
+        )
+        return {"access_token": access_token, "token_type": "bearer"}
+
+    except Exception as e:
+        logger.error(f"Google One-Tap Error: {e}")
+        raise HTTPException(status_code=400, detail=f"Authentication failed: {str(e)}")
+
+@router.post("/google-login", response_model=schemas.Token)
+async def google_login(
+    login_data: GoogleLoginRequest,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    background_tasks: BackgroundTasks
+):
+    """Verifies Google ID Token and logs the user in (or registers them)."""
+    try:
+        idinfo = id_token.verify_oauth2_token(
+            login_data.token, 
+            google_requests.Request(), 
+            settings.GOOGLE_CLIENT_ID
+        )
+
+        email = idinfo['email']
+        full_name = idinfo.get('name')
+
+        result = await db.execute(select(User).where(User.email == email))
+        user = result.scalar_one_or_none()
+
+        is_new_user = False
+        if not user:
+            user = User(
+                email=email,
+                full_name=full_name,
+                is_active=True,
+                hashed_password="EXTERNAL_AUTH_GOOGLE"
+            )
+            db.add(user)
+            await db.commit()
+            await db.refresh(user)
+            is_new_user = True
+        elif not user.is_active:
+            user.is_active = True
+            await db.commit()
+            is_new_user = True
+
+        if is_new_user:
+            llm = get_llm_service()
+            notif_service = NotificationService(db, llm)
+            background_tasks.add_task(notif_service.send_welcome_email, email, full_name)
+
+        access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+        access_token = create_access_token(
+            data={"sub": user.email}, expires_delta=access_token_expires
+        )
+        return {"access_token": access_token, "token_type": "bearer"}
+    except Exception as e:
+        logger.error(f"Google Login error: {e}")
+        raise HTTPException(status_code=400, detail="Invalid Google token")
+
+@router.post("/verify-otp", response_model=schemas.Token)
+async def verify_otp(
+    verify_in: schemas.VerifyOTP,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    background_tasks: BackgroundTasks
+):
+    result = await db.execute(select(User).where(User.email == verify_in.email))
+    user = result.scalar_one_or_none()
+
+    if not user or user.verification_code != verify_in.otp:
+        raise HTTPException(status_code=400, detail="Invalid OTP")
+
+    if user.verification_code_expires_at < datetime.now(timezone.utc):
+        raise HTTPException(status_code=400, detail="OTP expired")
+
+    user.is_active = True
+    user.verification_code = None
+    user.verification_code_expires_at = None
+    await db.commit()
+    
+    llm = get_llm_service()
+    notif_service = NotificationService(db, llm)
+    background_tasks.add_task(notif_service.send_welcome_email, user.email, user.full_name)
+
+    access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    access_token = create_access_token(
+        data={"sub": user.email}, expires_delta=access_token_expires
+    )
+    return {"access_token": access_token, "token_type": "bearer"}
+
+@router.post("/token", response_model=schemas.Token)
+async def login_for_access_token(
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    result = await db.execute(select(User).where(User.email == form_data.username))
+    user = result.scalar_one_or_none()
+    if not user or not verify_password(form_data.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    if not user.is_active:
+        raise HTTPException(status_code=400, detail="User not verified")
+    access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    access_token = create_access_token(data={"sub": user.email}, expires_delta=access_token_expires)
+    return {"access_token": access_token, "token_type": "bearer"}
+
+from app.features.auth.deps import get_current_user
+@router.post("/verify")
+async def verify_user_password(
+    data: schemas.PasswordVerification,
+    current_user: Annotated[User, Depends(get_current_user)]
+):
+    if not verify_password(data.password, current_user.hashed_password):
+        raise HTTPException(status_code=400, detail="Invalid password")
+    return {"valid": True}

app/features/auth/schemas.py

@@ -0,0 +1,30 @@
+from typing import Optional
+from pydantic import BaseModel, EmailStr
+import uuid
+
+class Token(BaseModel):
+    access_token: str
+    token_type: str
+
+class TokenData(BaseModel):
+    email: Optional[str] = None
+
+class UserBase(BaseModel):
+    email: EmailStr
+    is_active: Optional[bool] = True
+
+class UserCreate(UserBase):
+    password: str
+
+class UserResponse(UserBase):
+    id: uuid.UUID
+    
+    class Config:
+        from_attributes = True
+
+class PasswordVerification(BaseModel):
+    password: str
+
+class VerifyOTP(BaseModel):
+    email: EmailStr
+    otp: str

app/features/bills/models.py

@@ -0,0 +1,42 @@
+import uuid
+from decimal import Decimal
+from typing import Optional
+from datetime import date
+from sqlalchemy import String, ForeignKey, Numeric, Boolean, Integer, DateTime, Date
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+from app.core.database import Base
+
+class Bill(Base):
+    __tablename__ = "bills"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"))
+    title: Mapped[str] = mapped_column(String, nullable=False)
+    amount: Mapped[Decimal] = mapped_column(Numeric(10, 2), nullable=False)
+    due_date: Mapped[date] = mapped_column(Date, nullable=False)
+    is_paid: Mapped[bool] = mapped_column(Boolean, default=False)
+    is_recurring: Mapped[bool] = mapped_column(Boolean, default=False)
+    recurrence_day: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    category: Mapped[str] = mapped_column(String, nullable=False)
+    sub_category: Mapped[str] = mapped_column(String, nullable=False)
+    created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    user: Mapped["User"] = relationship("User", back_populates="bills")
+
+class BillExclusion(Base):
+    __tablename__ = "bill_exclusions"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"))
+    
+    # For skipping a specific projection from a specific transaction
+    source_transaction_id: Mapped[Optional[uuid.UUID]] = mapped_column(ForeignKey("transactions.id"), nullable=True)
+    
+    # For permanent exclusion logic
+    merchant_pattern: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    subcategory_pattern: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    
+    exclusion_type: Mapped[str] = mapped_column(String)  # 'SKIP', 'PERMANENT'
+    
+    created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now())

app/features/bills/router.py

@@ -0,0 +1,147 @@
+from typing import Annotated, List, Optional
+from uuid import UUID
+from decimal import Decimal
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.database import get_db
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.bills.schemas import (
+    BillCreate,
+    BillUpdate,
+    BillResponse,
+    MarkPaidRequest,
+    BillResponse,
+    MarkPaidRequest,
+    UpcomingBillsResponse,
+    SuretyExclusionCreate
+)
+from app.features.bills.service import BillService
+
+router = APIRouter()
+
+@router.get("/surety/list")
+async def list_sureties(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()],
+    include_hidden: bool = True
+):
+    """List all detected surety obligations, including hidden/excluded ones."""
+    ledger = await service.get_obligations_ledger(db, current_user.id, days_ahead=60, include_hidden=include_hidden)
+    # Filter only Surety items
+    sureties = [item for item in ledger["items"] if item.type == "SURETY_TXN"]
+    return sureties
+
+@router.post("/surety/exclusion")
+async def create_exclusion(
+    exclusion_data: SuretyExclusionCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()]
+):
+    """Create an exclusion rule for a surety."""
+    excl = await service.create_surety_exclusion(db, current_user.id, exclusion_data)
+    return {"status": "success", "id": str(excl.id)}
+
+
+@router.post("", response_model=BillResponse, status_code=status.HTTP_201_CREATED)
+async def create_bill(
+    bill_data: BillCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()]
+):
+    """Create a new bill (one-time or recurring)."""
+    bill = await service.create_bill(db, current_user.id, bill_data)
+    return bill
+
+
+@router.get("", response_model=List[BillResponse])
+async def list_bills(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()],
+    paid: Optional[bool] = Query(None, description="Filter by paid status")
+):
+    """List all bills for the current user."""
+    bills = await service.get_user_bills(db, current_user.id, paid_filter=paid)
+    return bills
+
+
+@router.get("/upcoming", response_model=UpcomingBillsResponse)
+async def get_upcoming_bills(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()],
+    days: int = Query(30, ge=1, le=90, description="Number of days to look ahead")
+):
+    """Get unpaid bills due in the next X days."""
+    bills = await service.get_upcoming_bills(db, current_user.id, days_ahead=days)
+    
+    total_amount = sum(bill.amount for bill in bills)
+    
+    return UpcomingBillsResponse(
+        upcoming_bills=bills,
+        total_amount=Decimal(str(total_amount)),
+        count=len(bills)
+    )
+
+
+@router.get("/{bill_id}", response_model=BillResponse)
+async def get_bill(
+    bill_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()]
+):
+    """Get details of a specific bill."""
+    bill = await service.get_bill_by_id(db, bill_id, current_user.id)
+    
+    if not bill:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Bill not found"
+        )
+    
+    return bill
+
+
+@router.put("/{bill_id}", response_model=BillResponse)
+async def update_bill(
+    bill_id: UUID,
+    bill_data: BillUpdate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()]
+):
+    """Update a bill."""
+    bill = await service.update_bill(db, bill_id, current_user.id, bill_data)
+    
+    if not bill:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Bill not found"
+        )
+    
+    return bill
+
+
+@router.post("/{bill_id}/mark-paid", response_model=BillResponse)
+async def mark_bill_paid(
+    bill_id: UUID,
+    request: MarkPaidRequest,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[BillService, Depends()]
+):
+    """Mark a bill as paid or unpaid."""
+    bill = await service.mark_paid(db, bill_id, current_user.id, request.paid)
+    
+    if not bill:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Bill not found"
+        )
+    
+    return bill

app/features/bills/schemas.py

@@ -0,0 +1,49 @@
+from typing import Optional
+from uuid import UUID
+from datetime import datetime, date
+from decimal import Decimal
+from pydantic import BaseModel, Field
+
+class BillBase(BaseModel):
+    title: str = Field(..., description="Bill title (e.g., 'Rent', 'Electricity')")
+    amount: Decimal = Field(..., description="Bill amount")
+    due_date: date = Field(..., description="Due date for the bill")
+    is_recurring: bool = Field(default=False, description="Whether this is a recurring bill")
+    recurrence_day: Optional[int] = Field(None, ge=1, le=31, description="Day of month for recurring bills")
+    category: str
+    sub_category: str
+
+class BillCreate(BillBase):
+    pass
+
+class BillUpdate(BaseModel):
+    title: Optional[str] = None
+    amount: Optional[Decimal] = None
+    due_date: Optional[date] = None
+    is_recurring: Optional[bool] = None
+    recurrence_day: Optional[int] = Field(None, ge=1, le=31)
+    category: Optional[str] = None
+    sub_category: Optional[str] = None
+
+class BillResponse(BillBase):
+    id: UUID
+    user_id: UUID
+    is_paid: bool
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+class MarkPaidRequest(BaseModel):
+    paid: bool = True
+
+class UpcomingBillsResponse(BaseModel):
+    upcoming_bills: list[BillResponse]
+    total_amount: Decimal
+    count: int
+
+class SuretyExclusionCreate(BaseModel):
+    source_transaction_id: Optional[UUID] = None
+    merchant_pattern: Optional[str] = None
+    subcategory_pattern: Optional[str] = None
+    exclusion_type: str  # 'SKIP', 'PERMANENT'

app/features/bills/service.py

@@ -0,0 +1,525 @@
+import logging
+import asyncio
+from uuid import UUID
+from datetime import date, datetime, timedelta
+import zoneinfo
+from decimal import Decimal
+from typing import List, Optional, Set, Tuple
+from calendar import monthrange
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func, or_, null
+from app.core.config import get_settings
+from app.features.bills.models import Bill, BillExclusion
+from app.features.bills.schemas import BillCreate, BillUpdate, SuretyExclusionCreate
+
+settings = get_settings()
+logger = logging.getLogger(__name__)
+
+from app.features.categories.models import SubCategory
+from app.features.transactions.models import Transaction
+
+class BillService:
+    def __init__(self):
+        self._tz = zoneinfo.ZoneInfo(settings.APP_TIMEZONE)
+
+    def _get_today(self) -> date:
+        """Get current date in the configured timezone."""
+        return datetime.now(self._tz).date()
+    
+    async def create_bill(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        bill_data: BillCreate
+    ) -> Bill:
+        """Create a new bill."""
+        data = bill_data.model_dump()
+        # Default recurrence_day to due_date day if it's recurring but day not specified
+        if data.get("is_recurring") and not data.get("recurrence_day"):
+            data["recurrence_day"] = data["due_date"].day
+            
+        bill = Bill(
+            user_id=user_id,
+            **data
+        )
+        db.add(bill)
+        await db.commit()
+        await db.refresh(bill)
+        logger.info(f"Created bill '{bill.title}' for user {user_id}")
+        return bill
+    
+    async def get_user_bills(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        paid_filter: Optional[bool] = None
+    ) -> List[Bill]:
+        """Get all bills for a user with optional paid/unpaid filter."""
+        stmt = select(Bill).where(Bill.user_id == user_id)
+        
+        if paid_filter is not None:
+            stmt = stmt.where(Bill.is_paid == paid_filter)
+        
+        stmt = stmt.order_by(Bill.due_date)
+        
+        result = await db.execute(stmt)
+        return list(result.scalars().all())
+    
+    async def get_bill_by_id(
+        self,
+        db: AsyncSession,
+        bill_id: UUID,
+        user_id: UUID
+    ) -> Optional[Bill]:
+        """Get a specific bill by ID."""
+        stmt = select(Bill).where(
+            Bill.id == bill_id,
+            Bill.user_id == user_id
+        )
+        result = await db.execute(stmt)
+        return result.scalar_one_or_none()
+    
+    async def update_bill(
+        self,
+        db: AsyncSession,
+        bill_id: UUID,
+        user_id: UUID,
+        bill_data: BillUpdate
+    ) -> Optional[Bill]:
+        """Update a bill."""
+        bill = await self.get_bill_by_id(db, bill_id, user_id)
+        
+        if not bill:
+            return None
+        
+        update_data = bill_data.model_dump(exclude_unset=True)
+        # If toggling recurring on but no recurrence_day, default from existing or new due_date
+        if update_data.get("is_recurring") and not update_data.get("recurrence_day") and not bill.recurrence_day:
+            due_date = update_data.get("due_date") or bill.due_date
+            update_data["recurrence_day"] = due_date.day
+
+        for field, value in update_data.items():
+            setattr(bill, field, value)
+        
+        await db.commit()
+        await db.refresh(bill)
+        logger.info(f"Updated bill {bill_id}")
+        return bill
+    
+    async def mark_paid(
+        self,
+        db: AsyncSession,
+        bill_id: UUID,
+        user_id: UUID,
+        paid: bool = True
+    ) -> Optional[Bill]:
+        """Mark a bill as paid or unpaid. For recurring bills, advances the due date."""
+        bill = await self.get_bill_by_id(db, bill_id, user_id)
+        
+        if not bill:
+            return None
+        
+        if paid and bill.is_recurring:
+            # Advance due date to next month
+            today = self._get_today()
+            r_day = bill.recurrence_day or bill.due_date.day
+            next_due = self._calculate_next_recurrence(r_day, today)
+            
+            # If next_due is same as current due_date (e.g. paying today's bill), 
+            # we must ensure we move to the month AFTER.
+            if next_due <= bill.due_date:
+                # Force next month
+                next_month = bill.due_date + timedelta(days=32)
+                next_due = self._calculate_next_recurrence(r_day, next_month)
+            
+            bill.due_date = next_due
+            bill.is_paid = False # Reset for next cycle
+            logger.info(f"Advanced recurring bill {bill_id} to {next_due}")
+        else:
+            bill.is_paid = paid
+            
+        await db.commit()
+        await db.refresh(bill)
+        logger.info(f"Marked bill {bill_id} status updated (paid={paid})")
+        return bill
+    
+    async def get_upcoming_bills(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        days_ahead: int = 30
+    ) -> List[Bill]:
+        """Get unpaid bills due within the next X days."""
+        today = self._get_today()
+        threshold_date = today + timedelta(days=days_ahead)
+        
+        stmt = (
+            select(Bill)
+            .where(Bill.user_id == user_id)
+            .where(Bill.is_paid == False)
+            .where(Bill.due_date <= threshold_date)
+            .order_by(Bill.due_date)
+        )
+        
+        result = await db.execute(stmt)
+        return list(result.scalars().all())
+
+    async def create_surety_exclusion(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        data: SuretyExclusionCreate
+    ) -> BillExclusion:
+        """Create an exclusion rule for auto-detected sureties."""
+        excl = BillExclusion(
+            user_id=user_id,
+            source_transaction_id=data.source_transaction_id,
+            merchant_pattern=data.merchant_pattern,
+            subcategory_pattern=data.subcategory_pattern,
+            exclusion_type=data.exclusion_type
+        )
+        db.add(excl)
+        await db.commit()
+        await db.refresh(excl)
+        logger.info(f"Created exclusion rule type {data.exclusion_type} for user {user_id}")
+        return excl
+    
+    async def get_obligations_ledger(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        days_ahead: int = 30,
+        include_hidden: bool = False
+    ) -> dict:
+        """
+        Get a full ledger of all identified obligations.
+        Returns: {
+            "unpaid_total": Decimal,
+            "projected_total": Decimal,
+            "items": List[IdentifiedObligation]
+        }
+        """
+        from app.features.analytics.schemas import IdentifiedObligation
+        from app.features.categories.models import SubCategory
+        from app.utils.finance_utils import get_month_date_range, get_previous_month_date_range
+        
+        today = self._get_today()
+        threshold_date = today + timedelta(days=days_ahead)
+        
+        ledger_items = []
+        unpaid_total = Decimal("0.00")
+        projected_total = Decimal("0.00")
+        
+        from sqlalchemy import literal_column
+        # 1. Create a unified query to fetch everything in ONE trip
+        # We use a discriminator 'source_type' to tell them apart
+        
+        # Bills subquery
+        b_sub = select(
+            Bill.id.label("id"),
+            Bill.title.label("title"),
+            Bill.amount.label("amount"),
+            Bill.due_date.label("date"),
+            literal_column("'BILL'").label("source_type"),
+            Bill.is_paid.label("is_paid"),
+            Bill.is_recurring.label("is_recurring"),
+            Bill.category.label("category"),
+            Bill.sub_category.label("sub_category"),
+            null().label("source_id")
+        ).where(Bill.user_id == user_id).where(or_(Bill.is_paid == False, Bill.is_recurring == True))
+
+        # Exclusions subquery
+        e_sub = select(
+            BillExclusion.id.label("id"),
+            BillExclusion.merchant_pattern.label("title"),
+            literal_column("0").label("amount"),
+            literal_column("NULL").label("date"),
+            literal_column("'EXCLUSION'").label("source_type"),
+            literal_column("FALSE").label("is_paid"),
+            literal_column("FALSE").label("is_recurring"),
+            BillExclusion.subcategory_pattern.label("category"),
+            BillExclusion.exclusion_type.label("sub_category"),
+            BillExclusion.source_transaction_id.label("source_id")
+        ).where(BillExclusion.user_id == user_id)
+
+        # Surety Subcategories for filtering txns
+        surety_sub_names = select(SubCategory.name).where(SubCategory.is_surety == True)
+
+        # Transactions subquery (Last 60 days)
+        sixty_days_ago = today - timedelta(days=60)
+        t_sub = select(
+            Transaction.id.label("id"),
+            Transaction.merchant_name.label("title"),
+            Transaction.amount.label("amount"),
+            Transaction.transaction_date.label("date"),
+            literal_column("'TXN'").label("source_type"),
+            literal_column("FALSE").label("is_paid"),
+            Transaction.is_surety.label("is_recurring"), # Using recurrence field for is_surety flag
+            Transaction.category.label("category"),
+            Transaction.sub_category.label("sub_category"),
+            null().label("source_id")
+        ).where(Transaction.user_id == user_id).where(Transaction.transaction_date >= sixty_days_ago).where(or_(
+            Transaction.is_surety == True,
+            Transaction.sub_category.in_(surety_sub_names)
+        ))
+
+        unified_stmt = b_sub.union_all(e_sub, t_sub)
+        unified_res = await db.execute(unified_stmt)
+        rows = unified_res.all()
+
+        # 2. Distribute results into local variables
+        all_bills = []
+        exclusions = []
+        past_txns = []
+        curr_txns = []
+
+        prev_range = get_previous_month_date_range(today)
+        curr_range = get_month_date_range(today)
+
+        for row in rows:
+            stype = row.source_type
+            if stype == 'BILL':
+                # Re-map back to objects for existing logic
+                all_bills.append(Bill(id=row.id, title=row.title, amount=row.amount, due_date=row.date, is_paid=row.is_paid, is_recurring=row.is_recurring, category=row.category, sub_category=row.sub_category))
+            elif stype == 'EXCLUSION':
+                exclusions.append(BillExclusion(
+                    id=row.id,
+                    merchant_pattern=row.title,
+                    subcategory_pattern=row.category,
+                    exclusion_type=row.sub_category,
+                    source_transaction_id=row.source_id
+                ))
+            elif stype == 'TXN':
+                txn_obj = Transaction(id=row.id, merchant_name=row.title, amount=row.amount, transaction_date=row.date, is_surety=row.is_recurring, category=row.category, sub_category=row.sub_category)
+                if prev_range["month_start"] <= row.date <= prev_range["month_end"]:
+                    past_txns.append(txn_obj)
+                elif curr_range["month_start"] <= row.date <= curr_range["month_end"]:
+                    curr_txns.append(txn_obj)
+
+        unpaid_bills = [b for b in all_bills if not b.is_paid]
+        recurring_bills = [b for b in all_bills if b.is_recurring]
+
+        skipped_source_ids = {e.source_transaction_id for e in exclusions if e.exclusion_type == 'SKIP' and e.source_transaction_id}
+        manual_paid_ids = {e.source_transaction_id for e in exclusions if e.exclusion_type == 'MANUAL_PAID' and e.source_transaction_id}
+        permanent_patterns = [
+            (e.merchant_pattern.lower() if e.merchant_pattern else None, 
+             e.subcategory_pattern.lower() if e.subcategory_pattern else None)
+            for e in exclusions if e.exclusion_type == 'PERMANENT'
+        ]
+
+        covered_signatures: Set[Tuple[str, Decimal]] = set()
+        
+        # 1. Process unpaid bills
+        for bill in unpaid_bills:
+            status = "OVERDUE" if bill.due_date < today else "PENDING"
+            ledger_items.append(IdentifiedObligation(
+                id=str(bill.id),
+                title=bill.title,
+                amount=bill.amount,
+                due_date=bill.due_date,
+                type="BILL",
+                status=status,
+                category=bill.category,
+                sub_category=bill.sub_category,
+                source_id=None
+            ))
+            unpaid_total += bill.amount
+            if bill.is_recurring:
+                covered_signatures.add((bill.sub_category.lower(), bill.amount))
+
+        # 2. Project NEXT instances for Recurring Bills
+        for bill in recurring_bills:
+            r_day = bill.recurrence_day or bill.due_date.day
+            next_due = self._calculate_next_recurrence(r_day, today)
+            if today <= next_due <= threshold_date:
+                if next_due > bill.due_date or bill.is_paid:
+                    ledger_items.append(IdentifiedObligation(
+                        id=f"proj-{bill.id}",
+                        title=f"{bill.title} (Projected)",
+                        amount=bill.amount,
+                        due_date=next_due,
+                        type="BILL",
+                        status="PROJECTED",
+                        category=bill.category,
+                        sub_category=bill.sub_category,
+                        source_id=None
+                    ))
+                    projected_total += bill.amount
+                    covered_signatures.add((bill.sub_category.lower(), bill.amount))
+
+        # 3. Process Surety
+        # Transactions are already filtered by the DB query above.
+        
+        matched_curr_ids = set()
+        
+        for p_txn in past_txns:
+            # Prepare status
+            is_excluded = False
+            exclusion_reason = ""
+            
+            # Check Skip Exclusion
+            if p_txn.id in skipped_source_ids:
+                is_excluded = True
+                exclusion_reason = "SKIPPED"
+
+            # Check Manual Paid
+            if str(p_txn.id) in {str(id) for id in manual_paid_ids}:
+                is_excluded = True
+                exclusion_reason = "PAID"
+            
+            # Check Permanent Exclusion
+            # Check Permanent Exclusion
+            if not is_excluded:
+                p_m = (p_txn.merchant_name or "").lower()
+                p_s = (p_txn.sub_category or "").lower()
+                for emp, esp in permanent_patterns:
+                    match_m = (emp == p_m) if emp is not None else True
+                    match_s = (esp == p_s) if esp is not None else True
+                    if match_m and match_s:
+                        is_excluded = True
+                        exclusion_reason = "TERMINATED"
+                        break
+            
+            # Check Covered by Bill
+            # Relaxed check: subcategory AND amount
+            if not is_excluded:
+                # Need to handle Decimal comparison carefully? set handles it.
+                if (p_txn.sub_category.lower(), p_txn.amount) in covered_signatures:
+                    is_excluded = True
+                    exclusion_reason = "COVERED"
+            
+            # estimated due date
+            due_day = p_txn.transaction_date.day
+            try:
+                p_date = today.replace(day=min(due_day, curr_range["month_end"].day))
+            except:
+                p_date = today
+
+            # Find partner in current month (regardless of exclusion, to determine projected vs done?)
+            # Actually if it's already done (partner found), we don't project anyway.
+            partner_found = False
+            for c_txn in curr_txns:
+                if c_txn.id not in matched_curr_ids:
+                    if abs(p_txn.amount) == abs(c_txn.amount):
+                        p_m = (p_txn.merchant_name or "").lower()
+                        c_m = (c_txn.merchant_name or "").lower()
+                        
+                        match_merch = (p_m == c_m)
+                        # Relaxed match: SubCategory match is sufficient if amount is exact
+                        match_sub = (p_txn.sub_category.lower() == c_txn.sub_category.lower())
+                        
+                        # Even more relaxed: If one merchant contains the other (e.g. "Google" vs "Google Services")
+                        match_fuzzy = (p_m and c_m) and (p_m in c_m or c_m in p_m)
+                        
+                        if match_merch or match_sub or match_fuzzy:
+                            matched_curr_ids.add(c_txn.id)
+                            partner_found = True
+                            break
+            
+            if partner_found:
+                if include_hidden:
+                     ledger_items.append(IdentifiedObligation(
+                        id=f"auto-{p_txn.id}",
+                        title=f"{p_txn.merchant_name or p_txn.sub_category} (Auto-detected)",
+                        amount=abs(p_txn.amount),
+                        due_date=p_date, # Use estimated date
+                        type="SURETY_TXN",
+                        status="PAID",
+                        sub_category=p_txn.sub_category,
+                        source_id=str(p_txn.id)
+                    ))
+                continue # Already paid this month, no obligation
+
+
+            # Does it pass filter?
+            if is_excluded and not include_hidden:
+                continue
+                
+
+            
+            date_status = "PROJECTED"
+            if p_date < today:
+                date_status = "OVERDUE"
+            
+            final_status = date_status
+            if is_excluded:
+                final_status = exclusion_reason
+            
+            # Date filter only applies if active (PROJECTED/OVERDUE)
+            # If excluded, we include it regardless of date if include_hidden is True?
+            # Or still respect threshold? Let's respect threshold for "Upcoming" logic, but maybe relax for "Management"?
+            # Let's keep threshold strict for now.
+            if today <= p_date <= threshold_date or final_status in ["OVERDUE", "SKIPPED", "TERMINATED", "COVERED", "PAID"]:
+                 if include_hidden or not is_excluded:
+                    ledger_items.append(IdentifiedObligation(
+                        id=f"auto-{p_txn.id}",
+                        title=f"{p_txn.merchant_name or p_txn.sub_category} (Auto-detected)",
+                        amount=abs(p_txn.amount),
+                        due_date=p_date,
+                        type="SURETY_TXN",
+                        status=final_status,
+                        sub_category=p_txn.sub_category,
+                        source_id=str(p_txn.id)
+                    ))
+                    if final_status == "PROJECTED":
+                        projected_total += abs(p_txn.amount)
+                    elif final_status == "OVERDUE":
+                        unpaid_total += abs(p_txn.amount)
+        
+        return {
+            "unpaid_total": unpaid_total,
+            "projected_total": projected_total,
+            "items": ledger_items
+        }
+
+    async def get_projected_surety_bills(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        days_ahead: int = 30
+    ) -> Decimal:
+        """Legay wrapper for projection total."""
+        res = await self.get_obligations_ledger(db, user_id, days_ahead)
+        return res["projected_total"]
+
+    async def get_unpaid_bills_total(
+        self,
+        db: AsyncSession,
+        user_id: UUID
+    ) -> Decimal:
+        """Legacy wrapper for unpaid total."""
+        res = await self.get_obligations_ledger(db, user_id)
+        return res["unpaid_total"]
+
+    
+    def _calculate_next_recurrence(
+        self,
+        recurrence_day: int,
+        reference_date: date
+    ) -> date:
+        """Calculate the next occurrence date for a recurring bill."""
+        try:
+            next_date = date(
+                reference_date.year,
+                reference_date.month,
+                min(recurrence_day, monthrange(reference_date.year, reference_date.month)[1])
+            )
+            
+            if next_date >= reference_date:
+                return next_date
+        except ValueError:
+            pass
+        
+        # Move to next month
+        if reference_date.month == 12:
+            next_month = 1
+            next_year = reference_date.year + 1
+        else:
+            next_month = reference_date.month + 1
+            next_year = reference_date.year
+        
+        return date(
+            next_year,
+            next_month,
+            min(recurrence_day, monthrange(next_year, next_month)[1])
+        )

app/features/categories/__init__.py

@@ -0,0 +1 @@
+from .models import Category, SubCategory

app/features/categories/models.py

@@ -0,0 +1,31 @@
+import uuid
+from typing import List, Optional
+from sqlalchemy import String, ForeignKey, Text, Boolean
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from app.core.database import Base
+
+class Category(Base):
+    __tablename__ = "categories"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String, index=True)
+    icon: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    color: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    type: Mapped[str] = mapped_column(String, default="EXPENSE") # EXPENSE, INCOME, INVESTMENT
+    user_id: Mapped[Optional[uuid.UUID]] = mapped_column(ForeignKey("users.id"), nullable=True) # None for system categories
+
+    sub_categories: Mapped[List["SubCategory"]] = relationship("SubCategory", back_populates="category", cascade="all, delete-orphan", lazy="selectin")
+
+class SubCategory(Base):
+    __tablename__ = "sub_categories"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String)
+    icon: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    color: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    type: Mapped[str] = mapped_column(String, default="EXPENSE")
+    is_surety: Mapped[bool] = mapped_column(Boolean, default=False)
+    category_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("categories.id"))
+    user_id: Mapped[Optional[uuid.UUID]] = mapped_column(ForeignKey("users.id"), nullable=True)
+
+    category: Mapped["Category"] = relationship("Category", back_populates="sub_categories")

app/features/categories/router.py

@@ -0,0 +1,69 @@
+from typing import Annotated, List
+from uuid import UUID
+from fastapi import APIRouter, Depends
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.categories import schemas
+from app.features.categories.service import CategoryService
+
+router = APIRouter()
+
+@router.get("/", response_model=List[schemas.CategoryResponse])
+async def get_categories(
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    return await service.get_cached_categories(user_id=current_user.id)
+
+@router.post("/", response_model=schemas.CategoryResponse)
+async def create_category(
+    data: schemas.CategoryCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    return await service.create_category(user_id=current_user.id, data=data)
+
+@router.post("/sub-categories", response_model=schemas.SubCategoryResponse)
+async def create_sub_category(
+    data: schemas.SubCategoryCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    return await service.create_sub_category(user_id=current_user.id, data=data)
+
+@router.delete("/{category_id}")
+async def delete_category(
+    category_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    await service.delete_category(user_id=current_user.id, category_id=category_id)
+    return {"status": "success"}
+
+@router.delete("/sub-categories/{sub_category_id}")
+async def delete_sub_category(
+    sub_category_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    await service.delete_sub_category(user_id=current_user.id, sub_category_id=sub_category_id)
+    return {"status": "success"}
+
+@router.patch("/{category_id}", response_model=schemas.CategoryResponse)
+async def update_category(
+    category_id: UUID,
+    data: schemas.CategoryUpdate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    return await service.update_category(user_id=current_user.id, category_id=category_id, data=data)
+
+@router.patch("/sub-categories/{sub_category_id}", response_model=schemas.SubCategoryResponse)
+async def update_sub_category(
+    sub_category_id: UUID,
+    data: schemas.SubCategoryUpdate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[CategoryService, Depends()]
+):
+    return await service.update_sub_category(user_id=current_user.id, sub_category_id=sub_category_id, data=data)
+

app/features/categories/schemas.py

@@ -0,0 +1,54 @@
+import uuid
+from typing import List, Optional, Literal
+from pydantic import BaseModel
+
+CategoryType = Literal["EXPENSE", "INCOME", "INVESTMENT"]
+
+class SubCategoryBase(BaseModel):
+    name: str
+    icon: Optional[str] = None
+    color: Optional[str] = None
+    type: CategoryType = "EXPENSE"
+    is_surety: bool = False
+
+class SubCategoryCreate(SubCategoryBase):
+    category_id: uuid.UUID
+
+class SubCategoryUpdate(BaseModel):
+    name: Optional[str] = None
+    icon: Optional[str] = None
+    color: Optional[str] = None
+    type: Optional[CategoryType] = None
+    is_surety: Optional[bool] = None
+
+class SubCategoryResponse(SubCategoryBase):
+    id: uuid.UUID
+    category_id: uuid.UUID
+    user_id: Optional[uuid.UUID] = None
+    is_surety: bool = False
+
+    class Config:
+        from_attributes = True
+
+class CategoryBase(BaseModel):
+    name: str
+    icon: Optional[str] = None
+    color: Optional[str] = None
+    type: CategoryType = "EXPENSE"
+
+class CategoryCreate(CategoryBase):
+    pass
+
+class CategoryUpdate(BaseModel):
+    name: Optional[str] = None
+    icon: Optional[str] = None
+    color: Optional[str] = None
+    type: Optional[CategoryType] = None
+
+class CategoryResponse(CategoryBase):
+    id: uuid.UUID
+    user_id: Optional[uuid.UUID] = None
+    sub_categories: List[SubCategoryResponse] = []
+
+    class Config:
+        from_attributes = True

app/features/categories/service.py

@@ -0,0 +1,138 @@
+from uuid import UUID
+from typing import List, Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from sqlalchemy.orm import selectinload, with_loader_criteria
+from fastapi import HTTPException, Depends
+from app.features.categories.models import Category, SubCategory
+from app.features.categories import schemas
+from app.core.database import get_db
+
+import time
+
+class CategoryService:
+    _cache = None
+    _cache_time = 0
+    CACHE_TTL = 3600  # 1 hour
+
+    def __init__(self, db: AsyncSession = Depends(get_db)):
+        self.db = db
+
+    async def get_cached_categories(self, user_id: UUID) -> List[Category]:
+        """Get categories with a simple memory cache to save DB round-trips."""
+        now = time.time()
+        # Note: In a multi-user environment, we'd need a per-user cache key
+        # but since system categories are shared, we cache those globally.
+        if CategoryService._cache is None or (now - CategoryService._cache_time) > self.CACHE_TTL:
+            CategoryService._cache = await self.get_categories(user_id)
+            CategoryService._cache_time = now
+        return CategoryService._cache
+
+    async def get_categories(self, user_id: UUID) -> List[Category]:
+        # Fetch both system categories (user_id=None) and user-specific categories
+        # Use contains_eager with explicit join to fetch everything in a SINGLE round-trip
+        from sqlalchemy.orm import contains_eager
+        stmt = (
+            select(Category)
+            .outerjoin(Category.sub_categories)
+            .where((Category.user_id == None) | (Category.user_id == user_id))
+            .where((SubCategory.user_id == None) | (SubCategory.user_id == user_id))
+            .options(contains_eager(Category.sub_categories))
+        )
+        result = await self.db.execute(stmt)
+        # unique() is required when using eager loading on collections
+        return result.unique().scalars().all()
+
+    @classmethod
+    def invalidate_cache(cls):
+        """Force the cache to refresh on the next request."""
+        cls._cache = None
+        cls._cache_time = 0
+
+    async def create_category(self, user_id: UUID, data: schemas.CategoryCreate) -> Category:
+        category = Category(
+            name=data.name,
+            icon=data.icon,
+            color=data.color,
+            type=data.type,
+            user_id=user_id
+        )
+        self.db.add(category)
+        await self.db.commit()
+        self.invalidate_cache()
+        return category
+
+    async def create_sub_category(self, user_id: UUID, data: schemas.SubCategoryCreate) -> SubCategory:
+        # Auto-inherit color from parent category if not provided
+        color = data.color
+        if not color:
+            stmt = select(Category.color).where(Category.id == data.category_id)
+            result = await self.db.execute(stmt)
+            color = result.scalar()
+
+        sub_category = SubCategory(
+            name=data.name,
+            icon=data.icon,
+            color=color,
+            type=data.type,
+            category_id=data.category_id,
+            user_id=user_id,
+            is_surety=data.is_surety
+        )
+        self.db.add(sub_category)
+        await self.db.commit()
+        self.invalidate_cache()
+        return sub_category
+
+    async def delete_category(self, user_id: UUID, category_id: UUID):
+        stmt = select(Category).where(Category.id == category_id, Category.user_id == user_id)
+        result = await self.db.execute(stmt)
+        category = result.scalar_one_or_none()
+        if not category:
+            raise HTTPException(status_code=404, detail="Category not found or you don't have permission")
+        await self.db.delete(category)
+        await self.db.commit()
+        self.invalidate_cache()
+
+    async def delete_sub_category(self, user_id: UUID, sub_category_id: UUID):
+        stmt = select(SubCategory).where(SubCategory.id == sub_category_id, SubCategory.user_id == user_id)
+        result = await self.db.execute(stmt)
+        sub_category = result.scalar_one_or_none()
+        if not sub_category:
+            raise HTTPException(status_code=404, detail="SubCategory not found or you don't have permission")
+        await self.db.delete(sub_category)
+        await self.db.commit()
+        self.invalidate_cache()
+
+    async def update_category(self, user_id: UUID, category_id: UUID, data: schemas.CategoryUpdate) -> Category:
+        stmt = select(Category).where(Category.id == category_id, Category.user_id == user_id)
+        result = await self.db.execute(stmt)
+        category = result.scalar_one_or_none()
+        if not category:
+            raise HTTPException(status_code=404, detail="Category not found or you don't have permission")
+        
+        update_data = data.model_dump(exclude_unset=True)
+        for key, value in update_data.items():
+            setattr(category, key, value)
+            
+        await self.db.commit()
+        await self.db.refresh(category)
+        self.invalidate_cache()
+        return category
+
+    async def update_sub_category(self, user_id: UUID, sub_category_id: UUID, data: schemas.SubCategoryUpdate) -> SubCategory:
+        stmt = select(SubCategory).where(SubCategory.id == sub_category_id, SubCategory.user_id == user_id)
+        result = await self.db.execute(stmt)
+        sub_category = result.scalar_one_or_none()
+        if not sub_category:
+            raise HTTPException(status_code=404, detail="SubCategory not found or you don't have permission")
+        
+        update_data = data.model_dump(exclude_unset=True)
+        for key, value in update_data.items():
+            setattr(sub_category, key, value)
+            
+        await self.db.commit()
+        await self.db.refresh(sub_category)
+        self.invalidate_cache()
+        return sub_category
+

app/features/credit_cards/models.py

@@ -0,0 +1,24 @@
+import uuid
+from decimal import Decimal
+from typing import Optional
+from sqlalchemy import String, ForeignKey, Numeric, Boolean, Integer, DateTime
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+from app.core.database import Base
+
+
+class CreditCard(Base):
+    __tablename__ = "credit_cards"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"))
+    card_name: Mapped[str] = mapped_column(String, nullable=False)
+    last_four_digits: Mapped[Optional[str]] = mapped_column(String(4), nullable=True)
+    statement_date: Mapped[int] = mapped_column(Integer, nullable=False)
+    payment_due_date: Mapped[int] = mapped_column(Integer, nullable=False)
+    credit_limit: Mapped[Optional[Decimal]] = mapped_column(Numeric(10, 2), nullable=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    user: Mapped["User"] = relationship("User", back_populates="credit_cards")
+    transactions: Mapped[list["Transaction"]] = relationship("Transaction", back_populates="credit_card")

app/features/credit_cards/router.py

@@ -0,0 +1,115 @@
+from typing import Annotated, List
+from uuid import UUID
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.database import get_db
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.credit_cards.schemas import (
+    CreditCardCreate,
+    CreditCardUpdate,
+    CreditCardResponse,
+    CreditCardCycleInfo
+)
+from app.features.credit_cards.service import CreditCardService
+
+router = APIRouter()
+
+
+@router.post("", response_model=CreditCardResponse, status_code=status.HTTP_201_CREATED)
+async def create_credit_card(
+    card_data: CreditCardCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[CreditCardService, Depends()]
+):
+    """Create a new credit card with billing cycle information."""
+    card = await service.create_card(db, current_user.id, card_data)
+    return card
+
+
+@router.get("", response_model=List[CreditCardResponse])
+async def list_credit_cards(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[CreditCardService, Depends()],
+    active_only: bool = True
+):
+    """List all credit cards for the current user."""
+    cards = await service.get_user_cards(db, current_user.id, active_only)
+    return cards
+
+
+@router.get("/{card_id}", response_model=CreditCardResponse)
+async def get_credit_card(
+    card_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[CreditCardService, Depends()]
+):
+    """Get details of a specific credit card."""
+    card = await service.get_card_by_id(db, card_id, current_user.id)
+    
+    if not card:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Credit card not found"
+        )
+    
+    return card
+
+
+@router.put("/{card_id}", response_model=CreditCardResponse)
+async def update_credit_card(
+    card_id: UUID,
+    card_data: CreditCardUpdate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[CreditCardService, Depends()]
+):
+    """Update a credit card."""
+    card = await service.update_card(db, card_id, current_user.id, card_data)
+    
+    if not card:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Credit card not found"
+        )
+    
+    return card
+
+
+@router.delete("/{card_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def deactivate_credit_card(
+    card_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[CreditCardService, Depends()]
+):
+    """Deactivate a credit card (soft delete)."""
+    success = await service.deactivate_card(db, card_id, current_user.id)
+    
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Credit card not found"
+        )
+
+
+@router.get("/{card_id}/cycle-info", response_model=CreditCardCycleInfo)
+async def get_billing_cycle_info(
+    card_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[CreditCardService, Depends()]
+):
+    """Get current billing cycle information for a credit card."""
+    cycle_info = await service.get_cycle_info(db, card_id, current_user.id)
+    
+    if not cycle_info:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Credit card not found"
+        )
+    
+    return cycle_info

app/features/credit_cards/schemas.py

@@ -0,0 +1,52 @@
+from typing import Optional
+from uuid import UUID
+from datetime import datetime, date
+from decimal import Decimal
+from pydantic import BaseModel, Field
+
+
+class CreditCardBase(BaseModel):
+    card_name: str = Field(..., description="User-defined name for the card (e.g., 'HDFC Regalia')")
+    last_four_digits: Optional[str] = Field(None, max_length=4, description="Last 4 digits of card number")
+    statement_date: int = Field(..., ge=1, le=31, description="Day of month when statement is generated")
+    payment_due_date: int = Field(..., ge=1, le=31, description="Day of month when payment is due")
+    credit_limit: Optional[Decimal] = Field(None, description="Credit limit of the card")
+
+
+class CreditCardCreate(CreditCardBase):
+    pass
+
+
+class CreditCardUpdate(BaseModel):
+    card_name: Optional[str] = None
+    last_four_digits: Optional[str] = Field(None, max_length=4)
+    statement_date: Optional[int] = Field(None, ge=1, le=31)
+    payment_due_date: Optional[int] = Field(None, ge=1, le=31)
+    credit_limit: Optional[Decimal] = None
+    is_active: Optional[bool] = None
+
+
+class CreditCardResponse(CreditCardBase):
+    id: UUID
+    user_id: UUID
+    is_active: bool
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class CreditCardCycleInfo(BaseModel):
+    card_id: UUID
+    card_name: str
+    cycle_start: date
+    cycle_end: date
+    next_statement_date: date
+    days_until_statement: int
+    unbilled_amount: Decimal
+    credit_limit: Optional[Decimal]
+    utilization_percentage: Optional[float]
+
+
+class CreditCardWithCycleInfo(CreditCardResponse):
+    cycle_info: CreditCardCycleInfo

app/features/credit_cards/service.py

@@ -0,0 +1,189 @@
+import logging
+from uuid import UUID
+from datetime import date
+from decimal import Decimal
+from typing import List, Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from app.features.credit_cards.models import CreditCard
+from app.features.credit_cards.schemas import CreditCardCreate, CreditCardUpdate, CreditCardCycleInfo
+from app.features.transactions.models import Transaction
+from app.utils.finance_utils import get_billing_cycle_dates
+
+logger = logging.getLogger(__name__)
+
+
+class CreditCardService:
+    
+    async def create_card(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        card_data: CreditCardCreate
+    ) -> CreditCard:
+        """Create a new credit card."""
+        card = CreditCard(
+            user_id=user_id,
+            **card_data.model_dump()
+        )
+        db.add(card)
+        await db.commit()
+        await db.refresh(card)
+        logger.info(f"Created credit card {card.card_name} for user {user_id}")
+        return card
+    
+    async def get_user_cards(
+        self,
+        db: AsyncSession,
+        user_id: UUID,
+        active_only: bool = True
+    ) -> List[CreditCard]:
+        """Get all credit cards for a user."""
+        stmt = select(CreditCard).where(CreditCard.user_id == user_id)
+        
+        if active_only:
+            stmt = stmt.where(CreditCard.is_active == True)
+        
+        result = await db.execute(stmt)
+        return list(result.scalars().all())
+    
+    async def get_card_by_id(
+        self,
+        db: AsyncSession,
+        card_id: UUID,
+        user_id: UUID
+    ) -> Optional[CreditCard]:
+        """Get a specific credit card by ID."""
+        stmt = select(CreditCard).where(
+            CreditCard.id == card_id,
+            CreditCard.user_id == user_id
+        )
+        result = await db.execute(stmt)
+        return result.scalar_one_or_none()
+    
+    async def update_card(
+        self,
+        db: AsyncSession,
+        card_id: UUID,
+        user_id: UUID,
+        card_data: CreditCardUpdate
+    ) -> Optional[CreditCard]:
+        """Update a credit card."""
+        card = await self.get_card_by_id(db, card_id, user_id)
+        
+        if not card:
+            return None
+        
+        update_data = card_data.model_dump(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(card, field, value)
+        
+        await db.commit()
+        await db.refresh(card)
+        logger.info(f"Updated credit card {card_id}")
+        return card
+    
+    async def deactivate_card(
+        self,
+        db: AsyncSession,
+        card_id: UUID,
+        user_id: UUID
+    ) -> bool:
+        """Deactivate a credit card (soft delete)."""
+        card = await self.get_card_by_id(db, card_id, user_id)
+        
+        if not card:
+            return False
+        
+        card.is_active = False
+        await db.commit()
+        logger.info(f"Deactivated credit card {card_id}")
+        return True
+    
+    async def get_unbilled_amount(
+        self,
+        db: AsyncSession,
+        card_id: UUID,
+        cycle_start: date,
+        cycle_end: date
+    ) -> Decimal:
+        """
+        Calculate total unsettled debt for the card.
+        Ignores cycle dates in favor of explicit 'is_settled' status.
+        """
+        stmt = (
+            select(func.sum(Transaction.amount))
+            .where(Transaction.credit_card_id == card_id)
+            .where(Transaction.is_settled == False) # Only include unpaid transactions
+        )
+        
+        result = await db.execute(stmt)
+        amount = result.scalar() or Decimal("0.00")
+        # Transactions are stored as: Expense negative (-), Income positive (+)
+        # Unbilled amount (Debt) should be positive for expenses.
+        # So we negate the sum. (-(-1000) = 1000 debt).
+        return -amount
+    
+    async def get_cycle_info(
+        self,
+        db: AsyncSession,
+        card_id: UUID,
+        user_id: UUID
+    ) -> Optional[CreditCardCycleInfo]:
+        """Get current billing cycle information for a card."""
+        card = await self.get_card_by_id(db, card_id, user_id)
+        
+        if not card:
+            return None
+        
+        cycle_dates = get_billing_cycle_dates(card.statement_date)
+        unbilled = await self.get_unbilled_amount(
+            db,
+            card_id,
+            cycle_dates["cycle_start"],
+            cycle_dates["cycle_end"]
+        )
+        
+        utilization = None
+        if card.credit_limit and card.credit_limit > 0:
+            utilization = float((unbilled / card.credit_limit) * 100)
+        
+        return CreditCardCycleInfo(
+            card_id=card.id,
+            card_name=card.card_name,
+            cycle_start=cycle_dates["cycle_start"],
+            cycle_end=cycle_dates["cycle_end"],
+            next_statement_date=cycle_dates["next_statement_date"],
+            days_until_statement=cycle_dates["days_until_statement"],
+            unbilled_amount=unbilled,
+            credit_limit=card.credit_limit,
+            utilization_percentage=utilization
+        )
+    
+    async def get_all_unbilled_for_user(
+        self,
+        db: AsyncSession,
+        user_id: UUID
+    ) -> Decimal:
+        """Get total unbilled amount across all active credit cards for a user."""
+        # 1. Get all active card IDs for this user
+        card_stmt = select(CreditCard.id).where(CreditCard.user_id == user_id, CreditCard.is_active == True)
+        card_res = await db.execute(card_stmt)
+        card_ids = [row[0] for row in card_res.all()]
+        
+        if not card_ids:
+            return Decimal("0.00")
+            
+        # 2. Get sum of all unsettled transactions for these cards
+        # Note: We use is_settled=False as the source of truth for unbilled debt
+        stmt = (
+            select(func.sum(Transaction.amount))
+            .where(Transaction.credit_card_id.in_(card_ids))
+            .where(Transaction.is_settled == False)
+        )
+        
+        result = await db.execute(stmt)
+        amount = result.scalar() or Decimal("0.00")
+        
+        # Expenses are negative, so negate to get positive debt amount
+        return -amount

app/features/dashboard/router.py

@@ -0,0 +1,112 @@
+from typing import Annotated, Dict, Optional
+import asyncio
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func, case
+from app.core.database import get_db
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.transactions.models import Transaction
+
+from app.features.dashboard.service import get_daily_expenses, get_category_expenses_history, get_monthly_category_breakdown, get_category_daily_expenses
+from app.features.forecasting.service import ForecastingService
+
+router = APIRouter()
+
+@router.get("/liquidity")
+async def get_liquidity_dashboard(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)]
+):
+    balance_stmt = (
+        select(func.sum(Transaction.amount))
+        .where(Transaction.user_id == current_user.id)
+        .where(Transaction.account_type.in_(["CASH", "SAVINGS"]))
+    )
+    
+    cc_stmt = (
+        select(func.sum(Transaction.amount))
+        .where(Transaction.user_id == current_user.id)
+        .where(Transaction.category != "Income")
+        .where(Transaction.account_type == "CREDIT_CARD")
+        .where(Transaction.is_settled == False)
+    )
+    
+    bills_stmt = (
+        select(func.sum(Transaction.amount))
+        .where(Transaction.user_id == current_user.id)
+        .where(Transaction.sub_category.in_(["Rent", "Maintenance", "Credit Card Payment"]))
+    )
+
+    balance_res = await db.execute(balance_stmt)
+    cc_res = await db.execute(cc_stmt)
+    bills_res = await db.execute(bills_stmt)
+
+    balance = balance_res.scalar() or 0
+    unbilled_cc = cc_res.scalar() or 0
+    bills = bills_res.scalar() or 0
+    
+    # Liquidity is the sum of liquid balance + CC debt (which is negative)
+    # If balance is 10,000 and CC debt is -2,000, liquidity is 8,000.
+    return {
+        "liquidity": balance + unbilled_cc,
+        "breakdown": {
+            "balance": balance,
+            "unbilled_cc": abs(unbilled_cc),
+            "bills": abs(bills)
+        }
+    }
+
+@router.get("/investments")
+async def get_investments_dashboard(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    month: Optional[int] = Query(None, ge=1, le=12),
+    year: Optional[int] = Query(None, ge=2000, le=2100)
+):
+    from datetime import date
+    from app.utils.finance_utils import get_month_date_range
+
+    # Aggregate by SubCategory for Investment Category
+    stmt = (
+        select(Transaction.sub_category, func.sum(Transaction.amount))
+        .where(Transaction.user_id == current_user.id)
+        .where(Transaction.category == "Investment")
+    )
+
+    if month and year:
+        target_date = date(year, month, 1)
+        rng = get_month_date_range(target_date)
+        stmt = stmt.where(Transaction.transaction_date >= rng["month_start"])
+        stmt = stmt.where(Transaction.transaction_date <= rng["month_end"])
+
+    stmt = stmt.group_by(Transaction.sub_category)
+    result = await db.execute(stmt)
+    breakdown = {str(row[0]): abs(row[1]) for row in result.all()}
+    
+    total = abs(sum(breakdown.values()))
+    
+    return {
+        "total_investments": total,
+        "breakdown": breakdown
+    }
+
+@router.get("/forecast")
+async def get_financial_forecast(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[ForecastingService, Depends()]
+):
+    # Execute data gathering sequentially to ensure stability with asyncpg
+    category_daily = await get_category_daily_expenses(db, current_user.id, days=120)
+    monthly_breakdown = await get_monthly_category_breakdown(db, current_user.id, months=4)
+    
+    forecast = await service.calculate_safe_to_spend(category_daily, monthly_breakdown)
+    
+    return {
+        "predicted_burden_30d": forecast.amount,
+        "confidence": forecast.confidence,
+        "description": forecast.reason,
+        "time_frame": forecast.time_frame,
+        "breakdown": forecast.breakdown
+    }

app/features/dashboard/service.py

@@ -0,0 +1,176 @@
+from datetime import datetime, timedelta
+from sqlalchemy import select, func, cast, Date
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.features.transactions.models import Transaction
+
+async def get_daily_expenses(db: AsyncSession, user_id: str, days: int = 90):
+    """Return daily aggregated expenses for forecasting."""
+    # Ensure start_date is a date object for comparison with transaction_date
+    start_date = (datetime.now() - timedelta(days=days)).date()
+    
+    stmt = (
+        select(
+            Transaction.transaction_date.label("day"),
+            func.sum(Transaction.amount).label("total")
+        )
+        .where(Transaction.user_id == user_id)
+        .where(Transaction.category != "Income")
+        .where(Transaction.transaction_date >= start_date)
+        .group_by("day")
+        .order_by("day")
+    )
+    
+    
+    result = await db.execute(stmt)
+    rows = result.all()
+    
+    # Return absolute values because expenses are stored as negative, 
+    # but forecasting expects positive magnitude of spend.
+    return [
+        {"ds": row.day.isoformat(), "y": abs(float(row.total or 0))}
+        for row in rows
+        if row.day is not None # Filter out any missing dates if they exist
+    ]
+
+async def get_category_expenses_history(db: AsyncSession, user_id: str, days: int = 90):
+    """Return aggregated expenses by category for the last N days."""
+    start_date = (datetime.now() - timedelta(days=days)).date()
+    
+    stmt = (
+        select(
+            Transaction.category,
+            func.sum(Transaction.amount).label("total")
+        )
+        .where(Transaction.user_id == user_id)
+        .where(Transaction.category != "Income")
+        .where(Transaction.transaction_date >= start_date)
+        .group_by(Transaction.category)
+        .order_by(func.sum(Transaction.amount).asc()) # Expenses are negative, so ASC puts biggest spenders first
+    )
+    
+    result = await db.execute(stmt)
+    rows = result.all()
+    
+    return [
+        {"category": row.category, "total": abs(float(row.total or 0))}
+        for row in rows
+    ]
+
+
+async def get_discretionary_daily_expenses(db: AsyncSession, user_id: str, days: int = 30):
+    """Return daily discretionary expenses (excluding Investment, Housing, Bills, Transfers, Surety)."""
+    start_date = (datetime.now() - timedelta(days=days)).date()
+    
+    stmt = (
+        select(
+            Transaction.transaction_date.label("day"),
+            func.sum(Transaction.amount).label("total")
+        )
+        .where(Transaction.user_id == user_id)
+        .where(Transaction.category.notin_(["Income", "Investment", "Housing", "Bill Payment", "Transfer"]))
+        .where(Transaction.is_surety == False)
+        .where(Transaction.transaction_date >= start_date)
+        .group_by("day")
+        .order_by("day")
+    )
+    
+    result = await db.execute(stmt)
+    rows = result.all()
+    
+    return [
+        {"ds": row.day.isoformat(), "y": abs(float(row.total or 0))}
+        for row in rows
+        if row.day is not None
+    ]
+
+async def get_monthly_category_breakdown(db: AsyncSession, user_id: str, months: int = 4):
+    """Return aggregated expenses by month and category for the last N months."""
+    # Approximate days
+    days = months * 30
+    start_date = (datetime.now() - timedelta(days=days)).replace(day=1).date()
+    
+    # Extract year and month. For SQLite/Postgres compatibility, we might just fetch date 
+    # and group in python, or use a universally supported truncate/extract.
+    # But for now, let's fetch all transactions (filtered) and group in Python to be safe 
+    # and allow for complex "Sub Category" logic if needed later.
+    
+    stmt = (
+        select(
+            Transaction.transaction_date,
+            Transaction.category,
+            Transaction.sub_category,
+            Transaction.amount
+        )
+        .where(Transaction.user_id == user_id)
+        .where(Transaction.category != "Income")
+        .where(Transaction.transaction_date >= start_date)
+        .order_by(Transaction.transaction_date)
+    )
+    
+    result = await db.execute(stmt)
+    rows = result.all()
+    
+    # Process in Python
+    # Structure: { "2023-10": { "Housing": 2000, "Food": 500, "Rent": 2000 } }
+    # Note: collecting SubCategories for "Rent" visibility
+    
+    breakdown = {}
+    
+    for row in rows:
+        if not row.transaction_date:
+            continue
+            
+        month_key = row.transaction_date.strftime("%Y-%m") # YYYY-MM
+        amount = abs(float(row.amount or 0))
+        cat = row.category
+        sub = row.sub_category
+        
+        if month_key not in breakdown:
+            breakdown[month_key] = {}
+            
+        # Aggregate by Category
+        breakdown[month_key][cat] = breakdown[month_key].get(cat, 0) + amount
+        
+        # ALSO explicitly capture likely Fixed Expenses as pseudo-categories for the LLM
+        # This helps 'sanitized' data requirement by not sending every subcategory, 
+        # but prominently featuring "Rent", "EMI", "Insurance"
+        if sub and sub in ["Rent", "Maintenance", "EMI", "Insurance", "Education"]:
+           breakdown[month_key][f"_{sub}"] = breakdown[month_key].get(f"_{sub}", 0) + amount
+
+    # Convert to list for easier JSON serialization
+    # [ { "month": "2023-10", "breakdown": {...} }, ... ]
+    formatted = []
+    for m in sorted(breakdown.keys()):
+        formatted.append({
+            "month": m,
+            "categories": breakdown[m]
+        })
+        
+    return formatted
+
+
+async def get_category_daily_expenses(db: AsyncSession, user_id: str, days: int = 120):
+    """Return daily aggregated expenses by category for forecasting."""
+    start_date = (datetime.now() - timedelta(days=days)).date()
+    
+    stmt = (
+        select(
+            Transaction.category,
+            Transaction.transaction_date.label("day"),
+            func.sum(Transaction.amount).label("total")
+        )
+        .where(Transaction.user_id == user_id)
+        .where(Transaction.category != "Income")
+        .where(Transaction.transaction_date >= start_date)
+        .group_by(Transaction.category, "day")
+        .order_by(Transaction.category, "day")
+    )
+    
+    result = await db.execute(stmt)
+    rows = result.all()
+    
+    return [
+        {"category": row.category, "ds": row.day.isoformat(), "y": abs(float(row.total or 0))}
+        for row in rows
+        if row.day is not None
+    ]

app/features/export/router.py

@@ -0,0 +1,28 @@
+from fastapi import APIRouter, Depends
+from fastapi.responses import Response
+from typing import Annotated
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.core.database import get_db
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.export.service import generate_csv_export
+
+router = APIRouter()
+
+@router.get("/csv")
+async def export_transactions_csv(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)]
+):
+    """
+    Export all transactions as a CSV file.
+    """
+    csv_content = await generate_csv_export(db, current_user.id)
+    
+    return Response(
+        content=csv_content,
+        media_type="text/csv",
+        headers={
+            "Content-Disposition": f"attachment; filename=grip_transactions_backup.csv"
+        }
+    )

app/features/export/service.py

@@ -0,0 +1,39 @@
+import csv
+import io
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from app.features.transactions.models import Transaction
+
+async def generate_csv_export(db: AsyncSession, user_id: str) -> str:
+    """
+    Generates a CSV string containing all transaction data for the user.
+    """
+    stmt = select(Transaction).where(Transaction.user_id == user_id).order_by(Transaction.transaction_date.desc())
+    result = await db.execute(stmt)
+    transactions = result.scalars().all()
+
+    output = io.StringIO()
+    writer = csv.writer(output)
+    
+    # Header
+    writer.writerow([
+        "Date", "Amount", "Currency", "Merchant", "Category", 
+        "Sub Category", "Account Type", "Status", "Is Manual", "Remarks", "Tags"
+    ])
+
+    for t in transactions:
+        writer.writerow([
+            t.transaction_date.isoformat() if t.transaction_date else "",
+            t.amount,
+            t.currency,
+            t.merchant_name or "",
+            t.category,
+            t.sub_category,
+            t.account_type,
+            t.status,
+            "Yes" if t.is_manual else "No",
+            t.remarks or "",
+            ",".join(t.tags) if t.tags else ""
+        ])
+    
+    return output.getvalue()

app/features/forecasting/schemas.py

@@ -0,0 +1,15 @@
+from typing import List, Optional
+from pydantic import BaseModel
+from decimal import Decimal
+
+class CategoryForecast(BaseModel):
+    category: str
+    predicted_amount: Decimal
+    reason: str
+
+class ForecastResponse(BaseModel):
+    amount: Decimal
+    reason: str
+    time_frame: str
+    confidence: str = "high"
+    breakdown: List[CategoryForecast] = []

app/features/forecasting/service.py

@@ -0,0 +1,394 @@
+import logging
+import json
+from decimal import Decimal
+from typing import List, Optional
+from fastapi import Depends
+
+from app.core.config import get_settings
+
+# Lazy import Prophet to avoid crashes if not installed/compiled
+# Prophet is used only if manually installed (not available on Vercel)
+try:
+    from prophet import Prophet
+    import pandas as pd
+    PROPHET_AVAILABLE = True
+except ImportError:
+    PROPHET_AVAILABLE = False
+    
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+from datetime import date, timedelta
+from app.features.forecasting.schemas import ForecastResponse, CategoryForecast
+from app.core.llm import get_llm_service, LLMService
+import calendar
+
+class ForecastingService:
+    def __init__(self, llm: LLMService = Depends(get_llm_service)):
+        # Handle manual instantiation for LLM
+        from app.core.llm import LLMService as ActualLLMService
+        if isinstance(llm, ActualLLMService):
+            self.llm = llm
+        else:
+            from app.core.llm import get_llm_service
+            self.llm = get_llm_service()
+        
+
+    async def calculate_safe_to_spend(self, category_daily_history: List[dict], monthly_breakdown: List[dict] = []) -> ForecastResponse:
+        """Forecast upcoming expenses for the next full month."""
+        today = date.today()
+        # Get first day of NEXT month
+        if today.month == 12:
+            next_month_start = date(today.year + 1, 1, 1)
+        else:
+            next_month_start = date(today.year, today.month + 1, 1)
+            
+        # Get last day of NEXT month
+        _, last_day = calendar.monthrange(next_month_start.year, next_month_start.month)
+        next_month_end = date(next_month_start.year, next_month_start.month, last_day)
+        
+        days_in_next_month = (next_month_end - next_month_start).days + 1
+        time_frame_str = f"Next Month ({next_month_start.strftime('%B %Y')})"
+        
+        # LOGIC:
+        # User requested category-wise Prophet forecast.
+        
+        use_prophet = settings.USE_AI_FORECASTING and PROPHET_AVAILABLE
+        
+        if use_prophet:
+            return await self._calculate_prophet_categorywise(category_daily_history, monthly_breakdown, next_month_start, next_month_end, time_frame_str)
+        
+        # Fallback to LLM for basic total if Prophet is missing (though user wants Prophet)
+        return await self._calculate_llm(category_daily_history, monthly_breakdown, time_frame_str, days_in_next_month)
+
+    async def _calculate_prophet_categorywise(self, category_daily_history: List[dict], monthly_breakdown: List[dict], start_date: date, end_date: date, time_frame: str) -> ForecastResponse:
+        """Forecast for each category individually using Prophet or Fixed Expense logic."""
+        
+        if not category_daily_history:
+             return ForecastResponse(amount=Decimal("0.00"), reason="No historical data found.", time_frame=time_frame, confidence="low")
+
+        try:
+            df_all = pd.DataFrame(category_daily_history)
+            if df_all.empty:
+                return ForecastResponse(amount=Decimal("0.00"), reason="No historical data found.", time_frame=time_frame, confidence="low")
+                
+            categories = df_all['category'].unique()
+            
+            # Map monthly breakdown for easier recurring check
+            # Filter out pseudo-categories starting with '_' to avoid mis-detecting trends
+            cat_monthly_totals = {} 
+            for month_data in monthly_breakdown:
+                for cat, amount in month_data.get("categories", {}).items():
+                    if cat.startswith("_"): continue
+                    if cat not in cat_monthly_totals:
+                        cat_monthly_totals[cat] = []
+                    cat_monthly_totals[cat].append(amount)
+
+            breakdown = []
+            total_amount = Decimal("0.00")
+            
+            # Determine actual history days in the provided data
+            min_history_date = pd.to_datetime(df_all['ds']).min()
+            today = date.today()
+            total_history_days = (today - min_history_date.date()).days + 1
+            if total_history_days < 30: total_history_days = 120 # Fallback safety
+            
+            # Determine days to predict (from max historical date until end of next month)
+            max_history_date = pd.to_datetime(df_all['ds']).max()
+            days_to_predict = (end_date - max_history_date.date()).days
+            
+            if days_to_predict <= 0:
+                 return ForecastResponse(amount=Decimal("0.00"), reason="Data already covers the forecast period.", time_frame=time_frame)
+
+            for cat in categories:
+                cat_df_raw = df_all[df_all['category'] == cat][['ds', 'y']].copy()
+                cat_df_raw['ds'] = pd.to_datetime(cat_df_raw['ds'])
+                
+                # 1. FIXED/RECURRING DETECTION (Most accurate for Rent, SIPs, etc.)
+                monthly_values = cat_monthly_totals.get(cat, [])
+                num_months = len(monthly_values)
+                num_txns = len(cat_df_raw)
+                
+                # If it appears monthly but rarely (1-2 txns per month), it's a fixed expense
+                is_recurring = num_months >= 1 and (num_txns / max(1, num_months)) <= 4
+                
+                if is_recurring:
+                    import statistics
+                    # Use max or median for fixed costs
+                    predicted_monthly = statistics.median(monthly_values) if monthly_values else 0
+                    cat_total = Decimal(str(max(0, round(predicted_monthly, 2))))
+                    reason = "Projected based on monthly recurring patterns (Rent/SIP/RD/Bills)."
+                
+                # 2. PROPHET FOR FREQUENT DISCRETIONARY (Food, Shopping, etc.)
+                elif num_txns >= 15:
+                    try:
+                        # CRITICAL: Fill in missing days with 0 so Prophet doesn't think 
+                        # a sparse expense is a daily expense.
+                        all_dates = pd.date_range(start=min_history_date, end=max_history_date, freq='D')
+                        cat_df = cat_df_raw.set_index('ds').reindex(all_dates, fill_value=0).reset_index()
+                        cat_df.columns = ['ds', 'y']
+
+                        m = Prophet(
+                            daily_seasonality=False,
+                            weekly_seasonality=True,
+                            yearly_seasonality=False,
+                            changepoint_prior_scale=0.01 # Be conservative
+                        )
+                        m.fit(cat_df)
+                        
+                        future = m.make_future_dataframe(periods=days_to_predict)
+                        forecast = m.predict(future)
+                        
+                        start_dt = pd.to_datetime(start_date)
+                        end_dt = pd.to_datetime(end_date)
+                        mask = (forecast['ds'] >= start_dt) & (forecast['ds'] <= end_dt)
+                        predicted = forecast[mask]['yhat'].sum()
+                        
+                        # Safety Cap: Forecast should not realistically exceed 2x the historical monthly average
+                        hist_monthly_avg = (cat_df_raw['y'].sum() / total_history_days) * 30
+                        predicted = min(predicted, hist_monthly_avg * 2)
+                        
+                        cat_total = Decimal(str(max(0, round(predicted, 2))))
+                        reason = f"Trend-based forecast using {num_txns} data points."
+                    except Exception as e:
+                        logger.error(f"Error forecasting category {cat}: {e}")
+                        avg_daily = cat_df_raw['y'].sum() / total_history_days
+                        cat_total = Decimal(str(max(0, round(avg_daily * 30, 2))))
+                        reason = "Forecasting model error; used historical monthly average."
+                
+                # 3. FALLBACK: SIMPLE MOVING AVERAGE
+                else:
+                    avg_daily = cat_df_raw['y'].sum() / total_history_days
+                    cat_total = Decimal(str(max(0, round(avg_daily * 30, 2))))
+                    reason = "Forecasted using 4-month daily spend average."
+                
+                if cat_total > 50: # Filter out noise
+                    breakdown.append(CategoryForecast(
+                        category=cat,
+                        predicted_amount=cat_total,
+                        reason=reason
+                    ))
+                    total_amount += cat_total
+            
+            breakdown.sort(key=lambda x: x.predicted_amount, reverse=True)
+            
+            return ForecastResponse(
+                amount=total_amount,
+                reason=f"Multi-model forecast for {len(breakdown)} categories, optimized for monthly recurring expenses and discretionary trends.",
+                time_frame=time_frame,
+                confidence="high",
+                breakdown=breakdown
+            )
+
+        except Exception as e:
+            logger.error(f"Prophet category forecasting error: {e}")
+            return ForecastResponse(
+                amount=Decimal("0.00"),
+                reason="System error during forecasting.",
+                time_frame=time_frame,
+                confidence="low"
+            )
+
+        except Exception as e:
+            logger.error(f"Prophet category forecasting error: {e}")
+            return ForecastResponse(
+                amount=Decimal("0.00"),
+                reason="System error during forecasting.",
+                time_frame=time_frame,
+                confidence="low"
+            )
+
+    async def _calculate_llm(self, category_daily_history: List[dict], monthly_breakdown: List[dict], time_frame: str, days: int) -> ForecastResponse:
+        """Use LLM to predict remaining month expenses."""
+        default_response = ForecastResponse(
+            amount=Decimal("0.00"), 
+            reason="Insufficient data/AI service unavailable.", 
+            time_frame=time_frame,
+            confidence="low"
+        )
+
+        if not self.llm.is_enabled:
+            return default_response
+            
+        if not category_daily_history or len(category_daily_history) < 5:
+            return ForecastResponse(
+                amount=Decimal("0.00"),
+                reason="Need more historical data to generate an AI forecast.",
+                time_frame=time_frame,
+                confidence="low"
+            )
+
+        try:
+            # Prepare context for LLM from category daily history
+            df = pd.DataFrame(category_daily_history)
+            category_totals = df.groupby('category')['y'].sum().to_dict()
+            recent_daily = df.groupby('ds')['y'].sum().tail(90).to_dict()
+            
+            prompt = f"""
+            Analyze the following financial data to predict expenses for the NEXT {days} DAYS (full month).
+            
+            1. Daily History Summary: {json.dumps(recent_daily)}
+            2. Category Totals (Last 120 days): {json.dumps(category_totals)}
+            3. Monthly Category Trends (Key for recurring bills like Rent): {json.dumps(monthly_breakdown)}
+            
+            Task:
+            - Analyze the 'Monthly Category Trends' to identify recurring payments (e.g., Rent, Insurance).
+            - Note: Categories starting with '_' like '_Rent' are explicit recurring bills.
+            - Predict discretionary spending based on 'Daily History'.
+            
+            Return the TOTAL predicted expenses for the full {days} day month.
+            
+            You must return a valid JSON object.
+            Required JSON structure:
+            {{
+                "predicted_total": float,
+                "reason": "short explanation",
+                "breakdown": [
+                    {{ "category": "string", "predicted_amount": float, "reason": "string" }}
+                ]
+            }}
+            """
+
+            system_prompt = "You are a financial intelligence engine. Always output valid JSON."
+            data = await self.llm.generate_json(prompt, system_prompt=system_prompt, temperature=0.1, timeout=60.0)
+                
+            if data:
+                return ForecastResponse(
+                    amount=Decimal(str(max(0, data.get("predicted_total", 0)))),
+                    reason=data.get("reason", "Based on analysis of spending cycles."),
+                    time_frame=time_frame,
+                    confidence="medium",
+                    breakdown=data.get("breakdown", [])
+                )
+                
+        except Exception as e:
+            logger.error(f"LLM forecasting error: {e}")
+            
+        return default_response
+
+    async def _get_llm_breakdown(self, category_history: List[dict], total_forecast: float, days: int) -> dict:
+        """Helper to get just the breakdown and reason from LLM, given a known total."""
+        try:
+            prompt = f"""
+            Given the historical category spending and a STATISTICALLY FORECASTED total of {total_forecast} 
+            for the REMAINING {days} DAYS of the month:
+            1. Allocate the forecasted total to categories based on history (considering end-of-month dues).
+            2. Explain the forecast trend in 1 sentence.
+            
+            Category History (90d): {json.dumps(category_history)}
+            
+            Return ONLY a JSON object:
+            {{
+                "reason": "string",
+                "breakdown": [ {{ "category": "string", "predicted_amount": float, "reason": "string" }} ]
+            }}
+            """
+            
+            data = await self.llm.generate_json(prompt, temperature=0.1, timeout=60.0)
+            if data:
+                return data
+        except Exception as e:
+            logger.error(f"LLM breakdown error: {e}")
+            
+        return {"reason": "Statistical forecast.", "breakdown": []}
+
+    async def predict_discretionary_buffer(self, history_data: List[dict], buffer_days: int = 7) -> dict:
+        """
+        Predict discretionary spending for the next N days using AI.
+        Returns: {
+            "predicted_amount": Decimal,
+            "confidence": str,
+            "range_low": Decimal,
+            "range_high": Decimal,
+            "method": str
+        }
+        """
+        default_result = {
+            "predicted_amount": Decimal("500"),  # Minimum fallback
+            "confidence": "low",
+            "range_low": Decimal("500"),
+            "range_high": Decimal("500"),
+            "method": "fallback"
+        }
+        
+        if not history_data or len(history_data) < 7:
+            return default_result
+        
+        use_prophet = settings.USE_AI_FORECASTING and PROPHET_AVAILABLE
+        
+        try:
+            if use_prophet:
+                # Use Prophet for prediction
+                df = pd.DataFrame(history_data)
+                df['ds'] = pd.to_datetime(df['ds'])
+                
+                m = Prophet(interval_width=0.8)  # 80% confidence interval
+                m.fit(df)
+                
+                # Predict for buffer_days
+                future = m.make_future_dataframe(periods=buffer_days)
+                forecast = m.predict(future)
+                
+                # Get predictions for future days only
+                last_date = df['ds'].max()
+                future_mask = forecast['ds'] > last_date
+                future_forecast = forecast[future_mask]
+                
+                predicted_total = max(0, future_forecast['yhat'].sum())
+                range_low = max(0, future_forecast['yhat_lower'].sum())
+                range_high = max(0, future_forecast['yhat_upper'].sum())
+                
+                return {
+                    "predicted_amount": Decimal(str(predicted_total)),
+                    "confidence": "high",
+                    "range_low": Decimal(str(range_low)),
+                    "range_high": Decimal(str(range_high)),
+                    "method": "prophet"
+                }
+            
+            elif self.llm.is_enabled:
+                # Use LLM for prediction
+                history_summary = [
+                    {"date": d['ds'], "amount": float(d['y'])} 
+                    for d in history_data[-30:]  # Last 30 days
+                ]
+                
+                prompt = f"""
+                Analyze the following 30-day DISCRETIONARY expense history (Food, Shopping, Entertainment, Transport, etc.).
+                Predict the TOTAL discretionary spending for the NEXT {buffer_days} DAYS.
+                
+                Daily History: {json.dumps(history_summary)}
+                
+                Consider:
+                - Day of week patterns (weekends vs weekdays)
+                - Recent trends
+                - Typical daily variation
+                
+                Return ONLY a JSON object:
+                {{
+                    "predicted_total": float,
+                    "confidence_low": float,
+                    "confidence_high": float
+                }}
+                """
+                
+                data = await self.llm.generate_json(prompt, temperature=0.1, timeout=60.0)
+                    
+                if data:
+                    predicted = max(0, data.get("predicted_total", 0))
+                    low = max(0, data.get("confidence_low", predicted * 0.8))
+                    high = max(0, data.get("confidence_high", predicted * 1.2))
+                    
+                    return {
+                        "predicted_amount": Decimal(str(predicted)),
+                        "confidence": "medium",
+                        "range_low": Decimal(str(low)),
+                        "range_high": Decimal(str(high)),
+                        "method": "llm"
+                    }
+                    
+        except Exception as e:
+            logger.error(f"Buffer prediction error: {e}")
+        
+        return default_result
+

app/features/goals/models.py

@@ -0,0 +1,27 @@
+from datetime import date
+from uuid import UUID
+from sqlalchemy import Column, String, Float, Date, Boolean, ForeignKey, DateTime, func
+from sqlalchemy.orm import relationship
+from sqlalchemy.dialects.postgresql import UUID as PG_UUID
+from app.core.database import Base
+
+class Goal(Base):
+    __tablename__ = "goals"
+
+    id = Column(PG_UUID(as_uuid=True), primary_key=True, default=func.uuid_generate_v4())
+    user_id = Column(PG_UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+    
+    name = Column(String, nullable=False)
+    target_amount = Column(Float, nullable=False)
+    target_date = Column(Date, nullable=False)
+    
+    # The amount we need to "freeze" monthly to hit this goal
+    monthly_contribution = Column(Float, nullable=False, default=0.0)
+    
+    # Track how much has been "saved" logically (optional, for tracking logic)
+    current_saved = Column(Float, default=0.0)
+    
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime, default=func.now())
+    
+    user = relationship("User", backref="goals")

app/features/goals/router.py

@@ -0,0 +1,47 @@
+from typing import Annotated, List, Optional
+from uuid import UUID
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.goals.schemas import GoalCreate, GoalResponse, FeasibilityCheck
+from app.features.goals.service import GoalService
+
+router = APIRouter()
+
+@router.post("/feasibility", response_model=FeasibilityCheck)
+async def check_goal_feasibility(
+    goal_data: GoalCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[GoalService, Depends()]
+):
+    return await service.check_feasibility(db, current_user.id, goal_data)
+
+@router.post("/", response_model=GoalResponse)
+async def create_goal(
+    goal_data: GoalCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[GoalService, Depends()]
+):
+    return await service.create_goal(db, current_user.id, goal_data)
+
+@router.get("/", response_model=List[GoalResponse])
+async def get_my_goals(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[GoalService, Depends()]
+):
+    return await service.get_active_goals(db, current_user.id)
+
+@router.delete("/{goal_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_goal(
+    goal_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+    service: Annotated[GoalService, Depends()]
+):
+    await service.delete_goal(db, current_user.id, goal_id)

app/features/goals/schemas.py

@@ -0,0 +1,34 @@
+from pydantic import BaseModel
+from datetime import date
+from typing import Optional
+from uuid import UUID
+
+class GoalBase(BaseModel):
+    name: str # string -> str
+    target_amount: float
+    target_date: date
+
+class GoalCreate(GoalBase):
+    pass
+
+class GoalUpdate(BaseModel):
+    name: Optional[str] = None
+    target_amount: Optional[float] = None
+    target_date: Optional[date] = None
+    is_active: Optional[bool] = None
+
+class GoalResponse(GoalBase):
+    id: UUID
+    user_id: UUID
+    monthly_contribution: float
+    current_saved: float
+    is_active: bool
+    
+    class Config:
+        from_attributes = True
+
+class FeasibilityCheck(BaseModel):
+    is_feasible: bool
+    required_monthly_savings: float
+    available_monthly_liquidity: float
+    message: str

app/features/goals/service.py

@@ -0,0 +1,118 @@
+import logging
+from uuid import UUID
+from datetime import date
+from typing import List, Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func, desc
+
+from app.features.goals.models import Goal
+from app.features.goals.schemas import GoalCreate, FeasibilityCheck
+from app.features.analytics.service import AnalyticsService
+
+logger = logging.getLogger(__name__)
+
+class GoalService:
+    def __init__(self):
+        self.analytics_service = AnalyticsService()
+
+    def _calculate_monthly_contribution(self, target_amount: float, target_date: date) -> float:
+        today = date.today()
+        if target_date <= today:
+            return target_amount # If date is passed or today, we need it all now!
+        
+        # Calculate roughly months remaining
+        # We use a simple approximation: (YearDiff * 12) + MonthDiff
+        # If day is current day or later, full month counts? Let's keep it simple.
+        months_remaining = (target_date.year - today.year) * 12 + (target_date.month - today.month)
+        
+        # If less than 1 month (e.g. same month later date), treat as 1 month
+        months_remaining = max(1, months_remaining)
+        
+        return round(target_amount / months_remaining, 2)
+
+    async def check_feasibility(self, db: AsyncSession, user_id: UUID, goal: GoalCreate) -> FeasibilityCheck:
+        required_savings = self._calculate_monthly_contribution(goal.target_amount, goal.target_date)
+        
+        # Get Average Monthly Summary (Liquidity)
+        # We can use the 'get_monthly_summary' but logic needs to be predictive.
+        # Let's simplify: Take avg income - avg expense from last 3 months?
+        # Or easier: Use current safe_to_spend BEFORE goal deduction as 'Available'.
+        
+        # Actually proper way:
+        # Liquidity = Avg Income - (Avg Expenses + Avg Surety + Avg Investments)
+        # This seems complex to calculate "Active Liquidity" on the fly accurately without detailed history.
+        # PROXY: Use 'Safe to Spend' of current month as a proxy for "Monthly Free Cashflow"? 
+        # No, Safe to Spend is balance based.
+        
+        # Better: Use (Income - Expense) avg over last 3 months.
+        # But for MVP speed: Let's assume user has the safe_to_spend capacity available monthly. 
+        # Wait, safe_to_spend is CURRENT balance.
+        
+        # Let's use AnalyticsService to get a 'monthly_free_flow' estimate.
+        # We can reuse 'calculate_burden' logic.
+        
+        # Let's fetch last month's summary as a baseline.
+        # TODO: Ideally fetch avg of last 3 months.
+        last_month = await self.analytics_service.get_monthly_summary(db, user_id) 
+        # Note: This gets current month. 
+        
+        # Estimate: Income - (Surety + Avg Discretionary).
+        # Let's be conservative: Available = Total Income - Total Expense (Last Month)
+        # If last month was negative, we assume 0 available?
+        
+        # Alternative: Just return the REQUIRED amount and a message based on SafeToSpend.
+        # If Required > SafeToSpend(current), it's definitely risky for NOW.
+        
+        safe_response = await self.analytics_service.calculate_safe_to_spend_amount(db, user_id)
+        current_safe_capacity = float(safe_response.safe_to_spend)
+        
+        is_feasible = current_safe_capacity >= required_savings
+        
+        msg = "✅ Plan looks solid." if is_feasible else "⚠️ This requires more than your current safe buffer."
+        
+        return FeasibilityCheck(
+            is_feasible=is_feasible,
+            required_monthly_savings=required_savings,
+            available_monthly_liquidity=current_safe_capacity,
+            message=msg
+        )
+
+    async def create_goal(self, db: AsyncSession, user_id: UUID, goal_data: GoalCreate) -> Goal:
+        monthly_contrib = self._calculate_monthly_contribution(goal_data.target_amount, goal_data.target_date)
+        
+        goal = Goal(
+            user_id=user_id,
+            name=goal_data.name,
+            target_amount=goal_data.target_amount,
+            target_date=goal_data.target_date,
+            monthly_contribution=monthly_contrib,
+            is_active=True
+        )
+        db.add(goal)
+        await db.commit()
+        await db.refresh(goal)
+        return goal
+
+    async def get_active_goals(self, db: AsyncSession, user_id: UUID) -> List[Goal]:
+        result = await db.execute(
+            select(Goal)
+            .where(Goal.user_id == user_id)
+            .where(Goal.is_active == True)
+            .order_by(Goal.target_date)
+        )
+        return result.scalars().all()
+    
+    async def get_total_monthly_goal_contribution(self, db: AsyncSession, user_id: UUID) -> float:
+        result = await db.execute(
+            select(func.sum(Goal.monthly_contribution))
+            .where(Goal.user_id == user_id)
+            .where(Goal.is_active == True)
+        )
+        return result.scalar() or 0.0
+
+    async def delete_goal(self, db: AsyncSession, user_id: UUID, goal_id: UUID):
+        result = await db.execute(select(Goal).where(Goal.id == goal_id, Goal.user_id == user_id))
+        goal = result.scalar_one_or_none()
+        if goal:
+            await db.delete(goal)
+            await db.commit()

app/features/internal/__init__.py

@@ -0,0 +1 @@
+# internal feature package

app/features/internal/router.py

@@ -0,0 +1,43 @@
+from fastapi import APIRouter, Header, HTTPException, status
+from pydantic import BaseModel
+from typing import Optional
+from app.core.llm import get_llm_service
+from app.core.config import get_settings
+
+router = APIRouter()
+settings = get_settings()
+
+
+class GenerateRequest(BaseModel):
+    prompt: str
+    system_prompt: Optional[str] = "You are a helpful financial assistant."
+    temperature: Optional[float] = 0.8
+
+
+class GenerateResponse(BaseModel):
+    result: Optional[str]
+
+
+@router.post("/generate", response_model=GenerateResponse)
+async def generate(
+    body: GenerateRequest,
+    x_grip_secret: Optional[str] = Header(default=None),
+):
+    """
+    Internal endpoint for calling the local LLM service.
+    Protected by X-Grip-Secret header — only callable by internal services
+    (e.g., GitHub Actions scheduler) that share the secret.
+    """
+    if not settings.GRIP_SECRET or x_grip_secret != settings.GRIP_SECRET:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or missing X-Grip-Secret header."
+        )
+
+    llm = get_llm_service()
+    result = await llm.generate_response(
+        prompt=body.prompt,
+        system_prompt=body.system_prompt,
+        temperature=body.temperature,
+    )
+    return GenerateResponse(result=result)

app/features/notifications/service.py

@@ -0,0 +1,495 @@
+import uuid
+import logging
+from typing import List, Optional
+from datetime import datetime, timedelta
+from sqlalchemy import select, and_
+from sqlalchemy.ext.asyncio import AsyncSession
+from fastapi import Depends
+
+from app.core.database import get_db
+from app.core.email import send_email
+from app.core.config import get_settings
+from app.core.llm import get_llm_service, LLMService
+from app.features.auth.models import User
+from app.features.bills.models import Bill
+from app.features.transactions.models import Transaction, TransactionStatus
+
+settings = get_settings()
+logger = logging.getLogger(__name__)
+
+class NotificationService:
+    def __init__(self, db: AsyncSession = Depends(get_db), llm: LLMService = Depends(get_llm_service)):
+        self.db = db
+        # If instantiated manually (e.g. in scheduler), llm will be the Depends object
+        from app.core.llm import LLMService as ActualLLMService
+        if isinstance(llm, ActualLLMService):
+            self.llm = llm
+        else:
+            from app.core.llm import get_llm_service
+            self.llm = get_llm_service()
+
+    def _derive_name(self, email: str, full_name: Optional[str] = None) -> str:
+        if full_name:
+            return full_name
+        return email.split('@')[0].replace('.', ' ').title()
+
+    def _get_html_wrapper(self, title: str, content: str, cta_text: Optional[str] = None, cta_url: Optional[str] = None, footer_note: Optional[str] = None) -> str:
+        """Premium 'Grip Neon' design system for high-impact emails."""
+        cta_html = ""
+        if cta_text and cta_url:
+            cta_html = f"""
+            <div style="margin: 40px 0; text-align: center;">
+                <a href="{cta_url}" style="background: linear-gradient(135deg, #111 0%, #333 100%); color: #fff; padding: 18px 36px; text-decoration: none; border-radius: 14px; font-weight: 800; display: inline-block; font-size: 16px; letter-spacing: 0.02em; border: 1px solid rgba(255,255,255,0.1); box-shadow: 0 10px 20px -5px rgba(0,0,0,0.3);">{cta_text}</a>
+            </div>
+            """
+        
+        footer_note_html = ""
+        if footer_note:
+            footer_note_html = f"""
+            <p style="font-size: 13px; color: #64748b; border-top: 1px solid #f1f5f9; padding-top: 20px; margin-top: 30px; font-style: italic;">
+                {footer_note}
+            </p>
+            """
+
+        return f"""
+        <html>
+            <body style="font-family: 'Outfit', 'Inter', sans-serif; color: #1e293b; line-height: 1.6; margin: 0; padding: 0; background-color: #0c0e12;">
+                <div style="max-width: 600px; margin: 40px auto; background: #ffffff; border-radius: 32px; overflow: hidden; box-shadow: 0 40px 100px -20px rgba(0,0,0,0.5);">
+                    <!-- Header with Neon Pulse -->
+                    <div style="background: #000; padding: 40px; text-align: left; position: relative;">
+                        <div style="display: flex; align-items: center;">
+                            <div style="width: 12px; height: 12px; background: #4F46E5; border-radius: 50%; box-shadow: 0 0 15px #4F46E5; margin-right: 12px;"></div>
+                            <span style="font-size: 28px; font-weight: 900; letter-spacing: -0.04em; color: #ffffff;">{settings.APP_NAME}</span>
+                        </div>
+                        <p style="color: #94a3b8; font-size: 12px; margin: 8px 0 0 24px; text-transform: uppercase; letter-spacing: 0.2em; font-weight: 600;">Autonomous Intelligence</p>
+                    </div>
+
+                    <div style="padding: 50px 40px;">
+                        <h2 style="color: #111; margin-top: 0; font-size: 32px; font-weight: 800; letter-spacing: -0.03em; line-height: 1.1;">{title}</h2>
+                        
+                        <div style="color: #475569; font-size: 17px; margin-top: 25px;">
+                            {content}
+                        </div>
+
+                        {cta_html}
+                        {footer_note_html}
+
+                        <div style="margin-top: 50px; border-top: 1px solid #f1f5f9; padding-top: 30px;">
+                            <p style="font-size: 14px; color: #94a3b8; margin: 0;">Automated with ❤️ by</p>
+                            <p style="font-size: 16px; font-weight: 900; color: #111; margin: 4px 0; letter-spacing: -0.01em;">The GRIP Engine</p>
+                        </div>
+                    </div>
+                </div>
+                <div style="max-width: 600px; margin: 0 auto; text-align: center; padding-bottom: 40px;">
+                    <p style="font-size: 11px; color: #475569; letter-spacing: 0.05em;">SECURE • AUTONOMOUS • INTELLIGENT</p>
+                </div>
+            </body>
+        </html>
+        """
+
+    async def notify_gmail_disconnection(self, user_id: uuid.UUID, email: str, full_name: str = None):
+        """Notify user that their Gmail connection has expired or been revoked."""
+        name = self._derive_name(email, full_name)
+        subject = f"Action Required: {settings.APP_NAME} Connection Lost"
+        content = f"""
+        <p>Hello {name},</p>
+        <p>Your Gmail connection for <strong>{email}</strong> has expired or been revoked.</p>
+        <p>{settings.APP_NAME} is unable to automatically sync your latest transactions. Please reconnect your account to resume automated financial intelligence.</p>
+        """
+        html = self._get_html_wrapper(
+            title="Connection Lost",
+            content=content,
+            cta_text="Reconnect Gmail",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/sync",
+            footer_note="If you didn't expect this, it might be due to Google's security policy for applications in testing mode."
+        )
+        send_email(email, subject, html)
+
+    async def send_welcome_email(self, email: str, full_name: Optional[str] = None):
+        """Send a witty, high-premium welcome email to new users."""
+        name = self._derive_name(email, full_name)
+        subject = f"Initiating Grip Protocol: Welcome, {name}"
+        
+        welcome_message = f"Welcome to {settings.APP_NAME}. You've just taken the first step toward absolute financial sovereignty. Your inbox is now your intelligence hub."
+        
+        if self.llm.is_enabled:
+            prompt = f"""
+            Task: Write a witty, premium welcome message for {name}. 
+            Context: They just joined Grip, an autonomous financial intelligence hub.
+            - Persona: Futuristic, cheeky financial AI.
+            - Max 30 words. No quotes.
+            Example: 'Initiation complete, {name}. I'm now minding your balance while you focus on the vision. Welcome to the hub.'
+            """
+            resp = await self.llm.generate_response(prompt, temperature=0.8, timeout=30.0)
+            if resp:
+                welcome_message = resp.strip().replace('"', '')
+
+        content = f"""
+        <p>Hello {name},</p>
+        <div style="background: #fff; border: 1px solid #e2e8f0; padding: 25px; border-radius: 16px; margin: 25px 0;">
+            <p style="margin: 0; font-size: 18px; color: #111; font-style: italic; line-height: 1.6;">"{welcome_message}"</p>
+        </div>
+        <p>Grip is now scanning for your financial 'Sureties' and building your high-precision Wealth map. Connect Gmail to unlock full autonomous mode.</p>
+        """
+        html = self._get_html_wrapper(
+            title="Welcome to the Hub",
+            content=content,
+            cta_text="Enter Dashboard",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/dashboard"
+        )
+        send_email(email, subject, html)
+
+    async def send_surety_reminder(self, user_id: uuid.UUID, full_name: str, bill_title: str, amount: float, due_date: datetime):
+        """Send a reminder before a fixed obligation (surety) is due."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        import zoneinfo
+        tz = zoneinfo.ZoneInfo(settings.APP_TIMEZONE)
+        today = datetime.now(tz).date()
+        days_left = (due_date.date() - today).days
+        
+        due_str = f"in {days_left} days" if days_left > 1 else "tomorrow"
+        if days_left <= 0:
+            due_str = "today"
+
+        name = self._derive_name(user.email, full_name)
+        
+        # Premium dynamic subject lines
+        if days_left == 1:
+            subject = f"Final Reminder: Payment Due Tomorrow for {bill_title}"
+        elif days_left == 2:
+            subject = f"Reminder: Payment Due in 2 Days for {bill_title}"
+        else:
+            subject = f"Reminder: Payment Due for {bill_title}"
+            
+        reminder_message = f"Your recurring payment for {bill_title} is due {due_str}."
+        
+        if self.llm.is_enabled:
+            prompt = f"""
+            Persona: Sassy, witty, premium personal CFO.
+            Task: Write a reminder message for {name} regarding their upcoming payment.
+            Context: The payment for '{bill_title}' of amount ₹{abs(amount):,.2f} is due {due_str} (on {due_date.strftime('%d %B, %Y')}).
+            - Max 30 words. No quotes, no markdown.
+            - Be cheeky or witty. Example: 'Grip protocol check, {name}: your rent is due soon. Make sure your account is fueled so you keep a roof over your head.'
+            """
+            resp = await self.llm.generate_response(prompt, temperature=0.8, timeout=30.0)
+            if resp:
+                reminder_message = resp.strip().replace('"', '')
+
+        content = f"""
+        <p>Hello {name},</p>
+        <div style="background: #fff; border: 1px solid #e2e8f0; padding: 25px; border-radius: 16px; margin: 25px 0;">
+            <p style="margin: 0; font-size: 18px; color: #111; font-style: italic; line-height: 1.6;">"{reminder_message}"</p>
+        </div>
+        <div style="background: #f8fafc; padding: 25px; border-radius: 12px; margin: 25px 0; border: 1px solid #f1f5f9; text-align: center;">
+            <p style="margin: 0; font-size: 14px; text-transform: uppercase; color: #64748b; letter-spacing: 0.05em;">Amount Due</p>
+            <p style="margin: 5px 0; font-size: 32px; font-weight: 800; color: #1e293b;">₹{abs(amount):,.2f}</p>
+            <p style="margin: 10px 0 0 0; font-size: 16px; color: #475569;">Due on <strong>{due_date.strftime('%d %B, %Y')}</strong></p>
+        </div>
+        <p>Ensure you have sufficient funds to avoid any late fees.</p>
+        """
+        html = self._get_html_wrapper(
+            title="Payment Reminder",
+            content=content,
+            cta_text="View Obligations",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/transactions?view=custom&category=Bills"
+        )
+        send_email(user.email, subject, html)
+
+    async def send_spending_insight(self, user_id: uuid.UUID, full_name: str, category: str, amount: float, percentage_increase: float):
+        """Notify user about abnormal spending patterns with a cheeky 'Roast'."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        name = self._derive_name(user.email, full_name)
+        subject = f"Category Alert: Your {category} spend is getting loud"
+        
+        roast_message = f"We noticed that your spending in {category} is {percentage_increase:.1f}% higher than your usual average this month."
+        
+        if self.llm.is_enabled:
+            prompt = f"""
+            Persona: Sassy, witty, premium personal CFO.
+            Task: Write a funny, slightly brutal 'Roast' for {name} regarding their {category} spending.
+            Context: They spent ₹{amount:,.0f} this week, which is {percentage_increase:.1f}% higher than normal.
+            - Max 30 words. No quotes, no markdown.
+            - Be cheeky. Example: 'Your coffee budget is starting to look like a down payment on a house, {name}. Maybe it's time to learn how a kettle works?'
+            """
+            resp = await self.llm.generate_response(prompt, temperature=0.8, timeout=60.0)
+            if resp:
+                roast_message = resp.strip()
+
+        content = f"""
+        <p>Hello {name},</p>
+        <div style="background: #fff; border: 1px solid #fee2e2; padding: 25px; border-radius: 16px; margin: 25px 0;">
+            <p style="margin: 0; font-size: 18px; color: #111; font-style: italic; line-height: 1.6;">"{roast_message}"</p>
+        </div>
+        <div style="background: #f8fafc; padding: 20px; border-radius: 12px; border: 1px solid #f1f5f9; display: flex; justify-content: space-between; align-items: center;">
+            <span style="font-size: 14px; color: #64748b;">This Week's {category}:</span>
+            <span style="font-size: 20px; font-weight: 800; color: #ef4444;">₹{amount:,.0f}</span>
+        </div>
+        """
+        html = self._get_html_wrapper(
+            title="Spending Alert",
+            content=content,
+            cta_text="Review Transactions",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/analytics"
+        )
+        send_email(user.email, subject, html)
+
+    async def send_weekly_summary(self, user_id: uuid.UUID, full_name: str, categories_data: List[dict]):
+        """Send a consolidated weekly spending roast for multiple categories."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        name = self._derive_name(user.email, full_name)
+        subject = f"Weekly Recap: Your wallet has some explaining to do"
+        
+        # Prepare context for LLM
+        context_items = [f"{item['category']}: ₹{item['amount']:,.0f}" for item in categories_data]
+        context_str = "\n".join(context_items)
+        
+        roast_message = f"You had some significant spending this week in {', '.join([item['category'] for item in categories_data])}. Keep an eye on your budget!"
+        
+        if self.llm.is_enabled:
+            prompt = f"""
+            Persona: Sassy, witty, premium personal CFO.
+            Task: Write a funny, slightly brutal consolidated 'Roast' for {name} based on their weekly spending across multiple categories.
+            Context:
+            {context_str}
+            
+            - Max 40 words. No quotes, no markdown.
+            - Be cheeky about the combination of things they are spending on.
+            """
+            resp = await self.llm.generate_response(prompt, temperature=0.8, timeout=60.0)
+            if resp:
+                roast_message = resp.strip().replace('"', '')
+
+        # Build category breakdown HTML
+        breakdown_html = ""
+        for item in categories_data:
+            breakdown_html += f"""
+            <div style="background: #f8fafc; padding: 15px; border-radius: 12px; border: 1px solid #f1f5f9; display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px;">
+                <span style="font-size: 14px; color: #64748b;">{item['category']}:</span>
+                <span style="font-size: 18px; font-weight: 700; color: #ef4444;">₹{item['amount']:,.0f}</span>
+            </div>
+            """
+
+        content = f"""
+        <p>Hello {name},</p>
+        <div style="background: #fff; border: 1px solid #fee2e2; padding: 25px; border-radius: 16px; margin: 25px 0;">
+            <p style="margin: 0; font-size: 18px; color: #111; font-style: italic; line-height: 1.6;">"{roast_message}"</p>
+        </div>
+        <h3 style="color: #1e293b; font-size: 16px; margin-bottom: 15px;">Weekly Spend Highlights</h3>
+        {breakdown_html}
+        """
+        html = self._get_html_wrapper(
+            title="Weekly Spending Alert",
+            content=content,
+            cta_text="Review Dashboard",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/dashboard"
+        )
+        send_email(user.email, subject, html)
+
+    async def send_buffer_alert(self, user_id: uuid.UUID, full_name: str, safe_to_spend: float):
+        """Emergency alert when Safe-to-Spend drops into the danger zone."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        name = self._derive_name(user.email, full_name)
+        subject = "🚨 Red Alert: Buffer Exhausted"
+        
+        content = f"""
+        <p>Hello {name}, your financial dashboard is flashing red.</p>
+        <p style="font-size: 17px; color: #111; font-weight: 600;">Your Safe-to-Spend has dropped below your safety buffer.</p>
+        
+        <div style="background: #000; color: #fff; padding: 40px; border-radius: 24px; margin: 30px 0; text-align: center; border: 2px solid #ef4444; box-shadow: 0 0 30px rgba(239, 68, 68, 0.4);">
+             <div style="width: 10px; height: 10px; background: #ef4444; border-radius: 50%; box-shadow: 0 0 15px #ef4444; margin: 0 auto 15px auto; animation: pulse 2s infinite;"></div>
+            <span style="display: block; font-size: 11px; text-transform: uppercase; letter-spacing: 0.2em; color: #94a3b8; margin-bottom: 8px;">DANGER ZONE BALANCE</span>
+            <span style="font-size: 42px; font-weight: 900; color: #ef4444; letter-spacing: -0.05em;">₹{safe_to_spend:,.2f}</span>
+        </div>
+        
+        <p style="color: #475569; font-size: 16px;">This means any further spending until your next income might cannibalize funds reserved for your upcoming bills. It's time for an elective spending freeze.</p>
+        """
+        html = self._get_html_wrapper(
+            title="Financial Flare",
+            content=content,
+            cta_text="Check Damage",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/dashboard"
+        )
+        send_email(user.email, subject, html)
+
+    async def send_inactivity_nudge(self, user_id: uuid.UUID, full_name: str, days_inactive: int):
+        """Notify user if no transactions have been synced for a while."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        name = self._derive_name(user.email, full_name)
+        subject = f"We missed you, {name}!"
+        nudge_message = f"It has been {days_inactive} days since your last transaction was synced. Financial intelligence works best with fresh data!"
+        
+        if self.llm.is_enabled:
+            prompt = f"""
+            Persona: Sassy, witty, premium personal CFO. 
+            Task: Write a funny, slightly flirty/teasing nudge for {name} who hasn't synced their bank in {days_inactive} days.
+            - Tease them about their 'ghosting' skills or 'selective memory' regarding spending.
+            - Max 30 words. 
+            - No quotes, no markdown.
+            Example: "Ghosting your finances doesn't make the bills go away, {name}. Reconnect before your budget has an identity crisis."
+            """
+            resp = await self.llm.generate_response(prompt, temperature=0.7, timeout=60.0)
+            if resp:
+                nudge_message = resp.strip().replace('"', '')
+
+        content = f"<p>Hello {name},</p><p>{nudge_message}</p>"
+        html = self._get_html_wrapper(
+            title="It's been a while...",
+            content=content,
+            cta_text="Sync Now",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/sync"
+        )
+        send_email(user.email, subject, html)
+
+    async def send_weekend_insight(self, user_id: uuid.UUID, full_name: str, safe_to_spend: float, current_balance: float, top_category: Optional[str] = None):
+        """Send a personalized, AI-generated weekend recommendation."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        name = self._derive_name(user.email, full_name)
+        ai_headline = "Ready for the Weekend?"
+        ai_message = "Your Safe-to-Spend is ready for review. Have a great weekend!"
+        ai_cta = "Check Budget"
+        subject = f"Weekend Insight: ₹{safe_to_spend:,.0f}"
+
+        if self.llm.is_enabled:
+            context_str = f"Top Spend this week: {top_category}" if top_category else ""
+            prompt = f"""
+            Persona: Witty, premium, world-class lifestyle concierge.
+            Context: User {name} has ₹{safe_to_spend:,.0f} safe to spend. {context_str}.
+            
+            Task: Write a highly personal, cheeky weekend recommendation. 
+            - If {top_category} is 'Food': Tease their palate. 
+            - If Budget > 3k: Suggest a 'treat yourself' moment.
+            - If Budget < 3k and > 1k: Suggest something in the middle.
+            - If Budget < 1k: Suggest something 'poor but gold' like a park sunset with stolen office coffee.
+            - Mood: Sophisticated but funny. Use wordplay. 
+            
+            Return JSON only, NO markdown:
+            {{ "headline": "Witty headline", "message": "The suggestion", "cta": "Cheeky CTA", "subject": "Bait-y subject line" }}
+            """
+            data = await self.llm.generate_json(prompt, temperature=0.8, timeout=60.0)
+            if data:
+                ai_headline = data.get("headline", ai_headline)
+                ai_message = data.get("message", ai_message)
+                ai_cta = data.get("cta", ai_cta)
+                subject = data.get("subject", subject)
+
+        content = f"""
+        <p>Hello {name},</p>
+        <p style="font-size: 18px; line-height: 1.5;">{ai_message}</p>
+        <div style="background: #000; color: white; padding: 40px; border-radius: 24px; margin: 30px 0; text-align: center; border: 1px solid rgba(79, 70, 229, 0.3); box-shadow: 0 10px 40px -10px rgba(79, 70, 229, 0.4);">
+            <div style="width: 8px; height: 8px; background: #4F46E5; border-radius: 50%; box-shadow: 0 0 10px #4F46E5; margin: 0 auto 15px auto;"></div>
+            <span style="display: block; font-size: 11px; text-transform: uppercase; letter-spacing: 0.2em; color: #94a3b8; margin-bottom: 8px; font-weight: 700;">Safe-to-Spend Vibe</span>
+            <span style="font-size: 42px; font-weight: 900; color: #fff; letter-spacing: -0.05em;">₹{safe_to_spend:,.2f}</span>
+        </div>
+        """
+        html = self._get_html_wrapper(
+            title=ai_headline,
+            content=content,
+            cta_text=ai_cta,
+            cta_url=f"{settings.FRONTEND_ORIGIN}/dashboard",
+            footer_note="This figure accounts for your current balance minus all upcoming obligations and safety buffers."
+        )
+        send_email(user.email, subject, html)
+
+    async def send_monthly_report(self, user_id: uuid.UUID, full_name: str, summary: any, variance: any):
+        """Send a massive monthly intelligence report with AI recommendations and data breakdown."""
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user or not user.email: return
+
+        name = self._derive_name(user.email, full_name)
+        subject = f"Monthly Intelligence: Your {summary.month} Review"
+        
+        # 1. Prepare visual breakdown (Top 5 categories)
+        sorted_cats = sorted(variance.category_breakdown.items(), key=lambda x: x[1].current, reverse=True)[:5]
+        breakdown_html = ""
+        for cat, data in sorted_cats:
+            percentage = (float(data.current) / float(summary.total_expense) * 100) if summary.total_expense > 0 else 0
+            breakdown_html += f"""
+            <div style="margin-bottom: 20px;">
+                <div style="display: flex; justify-content: space-between; font-size: 14px; margin-bottom: 6px;">
+                    <span style="color: #475569; font-weight: 600;">{cat}</span>
+                    <span style="color: #111; font-weight: 800;">₹{data.current:,.0f}</span>
+                </div>
+                <div style="width: 100%; height: 8px; background: #f1f5f9; border-radius: 4px; overflow: hidden;">
+                    <div style="width: {min(100, percentage)}%; height: 100%; background: #4F46E5; box-shadow: 0 0 10px rgba(79, 70, 229, 0.4);"></div>
+                </div>
+            </div>
+            """
+
+        # 2. Get AI Strategic Nudge
+        ai_strategy = "Great work tracking your finances this month. Keep it up for a stronger next month!"
+        if self.llm.is_enabled:
+            top_cats_str = ", ".join([f"{c}: ₹{d.current:,.0f}" for c, d in sorted_cats])
+            prompt = f"""
+            Persona: Sassy but brilliant luxury wealth manager.
+            User: {name}
+            Month: {summary.month}
+            Total Income: ₹{summary.total_income:,.0f}, Expenses: ₹{summary.total_expense:,.0f}
+            Top Spends: {top_cats_str}
+            
+            Task: Write a 2-3 sentence 'Optimization Strategy'. 
+            - Be blunt but funny. 
+            - If expenses > income, send a 'brutal' reality check. 
+            - If income > expenses, celebrate the win but suggest an 'aggressive' investment move.
+            - Max 40 words. No markdown.
+            """
+            resp = await self.llm.generate_response(prompt, temperature=0.8, timeout=10.0)
+            if resp:
+                ai_strategy = resp.strip()
+
+        content = f"""
+        <p>Hello {name}, your financial dossier for <strong>{summary.month}</strong> is ready.</p>
+        
+        <!-- Summary Cards -->
+        <div style="display: flex; gap: 15px; margin: 30px 0;">
+            <div style="flex: 1; background: #f8fafc; padding: 25px; border-radius: 20px; border: 1px solid #e2e8f0; text-align: center;">
+                <span style="display: block; font-size: 11px; text-transform: uppercase; color: #64748b; letter-spacing: 0.1em; margin-bottom: 8px; font-weight: 700;">Income</span>
+                <span style="font-size: 24px; font-weight: 900; color: #10b981;">₹{summary.total_income:,.0f}</span>
+            </div>
+            <div style="flex: 1; background: #f8fafc; padding: 25px; border-radius: 20px; border: 1px solid #e2e8f0; text-align: center;">
+                <span style="display: block; font-size: 11px; text-transform: uppercase; color: #64748b; letter-spacing: 0.1em; margin-bottom: 8px; font-weight: 700;">Expenses</span>
+                <span style="font-size: 24px; font-weight: 900; color: #ef4444;">₹{summary.total_expense:,.0f}</span>
+            </div>
+        </div>
+
+        <!-- Strategy Box -->
+        <div style="background: #000; color: white; padding: 35px; border-radius: 24px; margin: 30px 0; border: 1px solid rgba(79, 70, 229, 0.4); box-shadow: 0 20px 50px -10px rgba(0,0,0,0.3);">
+            <div style="width: 8px; height: 8px; background: #4F46E5; border-radius: 50%; box-shadow: 0 0 10px #4F46E5; margin-bottom: 15px;"></div>
+            <p style="margin: 0; font-size: 12px; text-transform: uppercase; letter-spacing: 0.2em; color: #94a3b8; font-weight: 700; border-bottom: 1px solid #333; padding-bottom: 12px; margin-bottom: 20px;">AI Wealth Strategy</p>
+            <p style="margin: 0; font-size: 17px; font-style: italic; color: #fff; line-height: 1.6;">"{ai_strategy}"</p>
+        </div>
+
+        <!-- Visual Breakdown -->
+        <div style="margin-top: 40px;">
+            <h3 style="color: #111; font-size: 20px; font-weight: 800; margin-bottom: 20px; letter-spacing: -0.02em;">Category Intelligence</h3>
+            <div style="background: white; border: 1px solid #f1f5f9; padding: 30px; border-radius: 24px;">
+                {breakdown_html}
+            </div>
+        </div>
+        """
+        html = self._get_html_wrapper(
+            title=f"{summary.month} Dossier",
+            content=content,
+            cta_text="Check Full Analytics",
+            cta_url=f"{settings.FRONTEND_ORIGIN}/analytics",
+            footer_note="Based on consolidated data from your synchronized bank accounts and manual entries."
+        )
+        send_email(user.email, subject, html)

app/features/sanitizer/service.py

@@ -0,0 +1,42 @@
+import re
+
+class SanitizerService:
+    def __init__(self):
+        # Regex Patterns
+        # Regex Patterns
+        self.patterns = {
+            # Order matters: Specific patterns first
+            # 'UPI': re.compile(r'[a-zA-Z0-9.\-_]{2,}@[a-zA-Z]{2,}'),  # Commented out so LLM can extract merchant name
+            'EMAIL': re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'),
+            'PHONE': re.compile(r'(?:\+?91|0)?[6-9]\d{9}'), # India specific mobile regex
+            'CARD': re.compile(r'(?:\d[ -]*?){12,19}'), # 12-19 digits for cards
+            'ACCOUNT': re.compile(r'[Xx]+\d{3,6}'), # Matches masked accounts like xxx1234
+            'OTP': re.compile(r'\b\d{4,8}\b'), # 4-8 digit standalone numbers (often OTPs or amounts, use carefully)
+            'PAN': re.compile(r'[A-Z]{5}[0-9]{4}[A-Z]{1}'),
+            'AADHAAR': re.compile(r'\d{4}\s\d{4}\s\d{4}'),
+        }
+    def sanitize(self, text: str) -> str:
+        if not text:
+            return text
+            
+        # Common greeting removal (Dear Customer, Hello Name)
+        text = re.sub(r'(?i)(Dear|Hello|Hi)\s+[A-Za-z\s]+,', r'\1 Customer,', text)
+        
+        for label, pattern in self.patterns.items():
+            if label == 'OTP':
+                 # Skip generic number replacement to avoid sanitizing amounts, unless it clearly looks like an OTP
+                 # For now, let's rely on LLM to ignore OTPs, or be very strict.
+                 # Actually, better to NOT sanitize simple numbers blindly as they might be amounts.
+                 continue
+                 
+            text = pattern.sub(f'<{label}>', text)
+            
+        return text
+
+_sanitizer = None
+
+def get_sanitizer_service():
+    global _sanitizer
+    if _sanitizer is None:
+        _sanitizer = SanitizerService()
+    return _sanitizer

app/features/settle_up/models.py

@@ -0,0 +1,33 @@
+import uuid
+from decimal import Decimal
+from datetime import date
+from typing import Optional
+from sqlalchemy import String, ForeignKey, Numeric, Text, DateTime, Date
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.sql import func
+from app.core.database import Base
+from app.features.auth.models import User
+from app.features.transactions.models import Transaction
+
+class SettleUpEntry(Base):
+    __tablename__ = "settle_up_entries"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), index=True)
+    
+    # Who the transaction is with (serves as the grouping key)
+    peer_name: Mapped[str] = mapped_column(String, index=True) 
+    
+    # Positive amount = They owe you (You lent them money)
+    # Negative amount = You owe them (You borrowed money, or they repaid a loan)
+    amount: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    
+    # Loose coupling to the main transaction, if it originated from a bank sync/manual entry
+    transaction_id: Mapped[Optional[uuid.UUID]] = mapped_column(ForeignKey("transactions.id", ondelete="CASCADE"), nullable=True)
+    
+    remarks: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    date: Mapped[date] = mapped_column(Date, default=date.today)
+    created_at: Mapped[DateTime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    user: Mapped["User"] = relationship("User")
+    transaction: Mapped[Optional["Transaction"]] = relationship("Transaction")

app/features/settle_up/router.py

@@ -0,0 +1,51 @@
+from uuid import UUID
+from typing import Annotated, List
+from fastapi import APIRouter, Depends
+from app.features.auth.deps import get_current_user
+from app.features.auth.models import User
+from app.features.settle_up import schemas
+from app.features.settle_up.service import SettleUpService
+
+router = APIRouter()
+
+@router.get("/balances", response_model=List[schemas.PeerBalance])
+async def get_peer_balances(
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[SettleUpService, Depends()]
+):
+    return await service.get_peer_balances(user_id=current_user.id)
+
+@router.get("/{peer_name}/history", response_model=List[schemas.SettleUpEntryResponse])
+async def get_peer_history(
+    peer_name: str,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[SettleUpService, Depends()],
+    limit: int = 50
+):
+    return await service.get_peer_history(user_id=current_user.id, peer_name=peer_name, limit=limit)
+
+@router.post("/", response_model=schemas.SettleUpEntryResponse)
+async def create_ledger_entry(
+    data: schemas.SettleUpEntryCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[SettleUpService, Depends()]
+):
+    return await service.add_ledger_entry(user_id=current_user.id, data=data)
+
+@router.put("/{entry_id}", response_model=schemas.SettleUpEntryResponse)
+async def update_settle_up_entry(
+    entry_id: UUID,
+    data: schemas.SettleUpEntryUpdate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[SettleUpService, Depends()]
+):
+    return await service.update_settle_up_entry(user_id=current_user.id, entry_id=entry_id, data=data)
+
+@router.delete("/{entry_id}")
+async def delete_settle_up_entry(
+    entry_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    service: Annotated[SettleUpService, Depends()]
+):
+    await service.delete_settle_up_entry(user_id=current_user.id, entry_id=entry_id)
+    return {"status": "success"}

app/features/settle_up/schemas.py

@@ -0,0 +1,44 @@
+from pydantic import BaseModel, Field
+from uuid import UUID
+from typing import Optional
+from datetime import date, datetime
+from decimal import Decimal
+
+class SettleUpEntryBase(BaseModel):
+    peer_name: str
+    amount: Decimal
+    remarks: Optional[str] = None
+    date: Optional[date] = None
+
+    class Config:
+        str_strip_whitespace = True
+
+class SettleUpEntryCreate(SettleUpEntryBase):
+    transaction_id: Optional[UUID] = None
+
+class SettleUpEntryUpdate(BaseModel):
+    peer_name: Optional[str] = None
+    amount: Optional[Decimal] = None
+    remarks: Optional[str] = None
+    date: Optional[date] = None
+
+    class Config:
+        str_strip_whitespace = True
+
+class SettleUpEntryResponse(SettleUpEntryBase):
+    id: UUID
+    user_id: UUID
+    date: date  # Override Optional from base — DB always has a date
+    transaction_id: Optional[UUID] = None
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+class PeerBalance(BaseModel):
+    peer_name: str
+    net_balance: Decimal
+    last_activity_date: date
+
+    class Config:
+        str_strip_whitespace = True