📖 WealthFam — How To Use Guide

A comprehensive operating manual for both the Web Dashboard (VueJS) and the Mobile App (Flutter).

---

🚀 1. Getting Started

First-Time Registration (Web)

1. Navigate to the WealthFam URL and click Register.
2. Enter a Family Name (this creates your Tenant — the shared family workspace).
3. Fill in your email, password, and profile details (full name, avatar emoji).
4. You are now the OWNER of the tenant with full administrative rights.

Mobile App Setup

1. Install the APK on your Android device.
2. On first launch, go to Settings → Server Configuration and enter your backend URL.
3. Login with the same credentials used on the web.
4. The app will generate a unique Device ID. If required, the Tenant Admin must approve this device from Web → Settings → Devices before sync can begin.

Adding Family Members

1. Go to Settings → Family on the web dashboard.
2. Click Add Member and provide their email and assign a role:
   • Adult: Full financial access.
   • Child: Restricted to personal goals only.
   • Guest: Read-only.
3. The new member can then register with that email and will automatically join your family tenant.

---

📱 2. SMS Transaction Sync (Mobile — Android)

Initial Permission Setup

1. Open the mobile app. On first use, it will request SMS and Location permissions.
2. SMS Permission: Required for reading bank transaction messages. Grant "Allow".
3. Location Permission: Set to "Always Allow" for highest Precision precision. Without this, GPS coordinates will be missing or use last-known position.

How SMS Sync Works

• Once permissions are granted, the app listens for incoming SMS in real-time, both in foreground and background.
• Each SMS is locally hashed (SHA-256) to prevent duplicates, then sent to the backend with GPS coordinates.
• The backend's AI parser extracts the transaction details (amount, date, merchant, account) and either auto-confirms or places it in the Triage Queue for review.

Enabling the Foreground Service (Recommended)

1. Go to Mobile App → SMS Management → Toggle "Foreground Service".
2. This keeps a persistent notification showing Today: ₹X • Month: ₹Y.
3. Benefits: More reliable background operation, real-time spending awareness, and poll-based alert delivery when WebSocket is disconnected.

Manual Sync & Catch-Up

• Tap "Sync Now" on the SMS Management screen to:
  1. Retry all queued offline messages.
  2. Scan the device inbox for the last 72 hours of unprocessed messages.
• Use "Push All Unsynced" for a complete inbox scan (all time).

Checking Sync Status

• The SMS Management screen shows:
  • Last Sync Time: When the last successful sync occurred.
  • Messages Synced Today: Counter resets daily.
  • Queue Count: Number of messages waiting for retry.
  • Debug Logs: Raw payloads sent to the backend (enable in settings).

---

🏦 3. Account Setup

Adding Accounts (Web)

1. Go to Settings → Accounts and click Add Account.
2. Choose the account type:
   • Bank: Savings/Checking (enter an account mask like XX1234 for SMS matching).
   • Credit Card: Enter credit limit, billing day, and due day for cycle intelligence.
   • Wallet: Digital wallets (Paytm, PhonePe, etc.).
   • Loan: Will prompt for loan details (see Loans section).
3. The Account Mask is critical — it's the last 4+ digits of your account number that appears in bank SMS messages (e.g., *1234). This is how WealthFam knows which account an SMS transaction belongs to.

Credit Card Intelligence

Once you set the Billing Day and Due Day for a credit card, WealthFam performs Precision cycle analysis:

• Statement Balance: Automatically calculated even if the bank doesn't report it (Current Balance - Unbilled Purchases - Payments Since Statement).
• Unbilled Spend: Live tracking of new purchases in the current cycle that haven't shifted to a statement yet.
• Utilization Tracking: Visual indicators and alerts for high debt-to-limit ratios.
• Next Due Date: Real-time ticker showing days remaining until payment is required.
• Credit Outlook: A dedicated dashboard panel for aggregated debt health across all cards.

---

📧 4. Email Sync (CAMS & Bank Emails)

Setting Up Email Sync

1. Go to Settings → Email Sync on the web dashboard.
2. Click Add Email Configuration.
3. Provide:
   • IMAP Server: imap.gmail.com for Gmail, imap-mail.outlook.com for Outlook.
   • Email: Your email address.
   • Password: For Gmail, use an App Password (not your regular password).
   • Folder: Usually INBOX.
4. Enable Auto-Sync to let the system check for new emails every 3 hours automatically.

Manual Email Sync

• On the Email Settings page, click Sync Now to trigger an immediate scan.
• The sync will fetch unread (or all, depending on configuration) emails, filter out noise, and parse financial transactions.
• Results appear in the Sync Logs section.

CAMS / KFintech CAS Sync (Mutual Funds)

1. Ensure you have an email configuration set up.
2. Navigate to Mutual Funds → Settings (or the CAS Sync section).
3. If your CAS PDFs are password-protected, enter the standard password (usually your PAN + DOB).
4. Click Sync CAS — the system will:
   • Scan for emails from camsonline or with subject "Consolidated Account Statement".
   • Download PDF attachments.
   • Parse them via the external microservice.
   • Map extracted transactions to mutual fund schemes and update your holdings.

---

📊 5. Using the Dashboard

Web Dashboard

The dashboard is your command center. It loads automatically after login:

Card	What It Shows	Click To
Net Worth	Total (Bank + Investments - Debt) with 30-day sparkline	Go to Dashboard
Monthly Spending	This month's spending vs. last month (same-day comparison)	Go to Transactions
Mutual Funds	Portfolio value, P&L, XIRR %	Go to Mutual Funds
Remaining Budget	Budget left with % spent	Go to Budgets

Below the top cards:

• Wealth Compass: Comprehensive wealth overview visualization.
• AI Intelligence: 3 AI-generated insights (auto-refreshes every 24 hours, can force-refresh).
• Activity Pulse: Real-time family activity feed via WebSocket notifications.
• Recent Activity: Last 5 transactions with category icons and member attribution.
• Upcoming Bills: Next 30 days of recurring transactions.
• Credit Outlook: Per-card billing cycle intelligence.

Mobile Dashboard

The mobile dashboard consolidates all data into a single API call for fast loading:

• Today/Yesterday/Last Month Same Day comparison cards.
• Monthly Total with budget progress bar.
• Daily Spending Trend chart.
• Category Breakdown donut chart.
• Investment Summary (if applicable) with live XIRR.
• Recent Transactions with swipe-to-view.

---

💳 6. Managing Transactions

Viewing Transactions (Web)

1. Navigate to Transactions from the sidebar.
2. Use the filter bar to narrow by:
   • Date Range: Custom start/end dates.
   • Account: Filter by specific bank/card.
   • Category: Filter by spending category.
   • Type: Credit/Debit.
3. Click any transaction to open the Transaction Modal for full details and editing.

Editing a Transaction

In the Transaction Modal, you can:

• Change Category, Description, and Recipient.
• Assign to an Expense Group (e.g., "Vacation").
• Mark as Transfer (and link the destination account).
• Link to a Loan (for EMI tracking).
• Toggle Exclude from Reports (hides from budget calculations).
• Attach Documents from the Vault.

Transaction Triage (Review Queue)

When the parser can't fully auto-categorize a transaction OR confidence is low:

1. Navigate to Transactions → Triage tab.
2. Each pending transaction shows the parsed data alongside the raw SMS/email content.
3. You can:
   • Approve: Confirms the transaction as-is (or edit before confirming).
   • Discard: Removes it from the queue.
   • Bulk Approve: Select multiple and approve at once.
4. Approved transactions move to the main transactions table.

Adding Transactions Manually

• Web: Click the "+" button or use the import modal.
• Mobile: Go to the home screen and tap Add Transaction — fill in amount, date, description, category, and account.

---

📈 7. Mutual Funds & Investments

Viewing Your Portfolio

1. Click Mutual Funds in the sidebar (Web) or navigate to the funds tab (Mobile).
2. The overview shows all holdings grouped by scheme with:
   • Current Value, Units, Average NAV, Last NAV.
   • Profit/Loss (absolute and percentage).
   • XIRR (annualized return).

Fund Details Deep-Dive

Click any scheme to see:

• Complete Order History (BUY/SELL with dates, NAVs, and units).
• Performance timeline chart.
• Fund category classification (Equity/Debt/Hybrid).
• Option to link the holding to an Investment Goal.

Exploring New Funds

1. Navigate to Mutual Funds → Explore.
2. Search by scheme code or name (queries the AMFI database).
3. View fund house, category, ISIN, and available scheme codes.

Folio & Multi-Member Tracking

• Folio Segmentation: Asset positions are uniquely keyed by schemeCode + folioNumber. The same scheme held in different folios will appear as separate line items for accurate accounting.
• Account Ownership: Assign funds to specific family members via the owner_id to separate personal portfolios within the shared family tenant.

Recalculating Holdings (Force Refresh)

If you suspect a data discrepancy or Average Cost error:

1. Go to Mutual Funds → Sync Logs (Web) or Portfolio Settings (Mobile).
2. Click Recalculate Holdings (Web) or Rebuild Portfolio (Mobile).
3. What happens?: WealthFam acquires a global database write-lock, wipes the cached position values, and re-executes every historical order chronologically to ensure Average Cost Basis and XIRR are 100% mathematically correct.

---

⚠️ 8. Budget Management

Creating Budgets

1. Navigate to Budgets from the sidebar.
2. Click Add Budget and select a category.
3. Enter the monthly spending limit (₹).
4. Create an OVERALL budget for total family spending.

Understanding Budget Alerts

WealthFam proactively monitors your spending and sends real-time alerts:

• 80% (Info) 🟡: "You are approaching your limit. Moderate discretionary spending."
• 100% (Warning) 🟠: "Your limit has been reached."
• 120% (Breach) 🔴: "Significant overspending detected."

These alerts are delivered via:

• WebSocket to connected web/mobile clients (instant).
• Push notification on Android (via foreground service).

Hierarchical Budgets

Parent-level budgets automatically include spending from sub-categories. For example:

• Budget on "Food" ← includes all spending under "Dining Out", "Groceries", "Delivery".
• No manual aggregation needed; the system handles rollup automatically.

Budget History & Forecast

• Budget History Chart: View month-by-month spending trends for each category.
• Spending Forecast: See projected end-of-month spending based on your current daily velocity.

---

🎯 9. Investment Goals

Creating a Goal

1. Navigate to Investment Goals (Web) or Goals tab (Mobile).
2. Click Create Goal and enter:
   • Name: e.g., "Retirement Fund", "Dream Home".
   • Target Amount: Your financial target (₹).
   • Target Date: Optional deadline.
   • Icon & Color: Visual customization.
   • Owner: Assign to a specific member or the whole family.

Linking Assets to Goals

Goals support three asset types:

• Mutual Fund Holdings: Link specific scheme holdings. The goal's progress tracks real-time NAV valuations.
• Bank Accounts: Link a bank account. The goal reflects the live account balance.
• Manual Assets: Add assets like EPF, Fixed Deposits, Gold with manual amounts and optional interest rates.

Tracking Progress

• The goal card shows a progress bar (current value / target amount × 100).
• When milestones are crossed, the system broadcasts a 🎯 Goal Milestone! notification to all family members.

---

🏛️ 10. Loans & Debt Management

Adding a Loan

1. Navigate to Loans from the sidebar.
2. Click Add Loan and fill in:
   • Loan Type: Home, Personal, Car, Education, Credit Card, Other.
   • Principal Amount, Annual Interest Rate, Tenure (months).
   • EMI Amount, EMI Day (day of month).
   • Source Bank Account: Where EMI is debited from.
3. A dedicated Loan Account is automatically created.

Amortization & Installment Tracking

1. Open any loan to view its dynamic Amortization Calendar.
2. WealthFam calculates your principal/interest split for every month of the tenure.
3. Status Indicators:
   • ✅ PAID: A matching repayment transaction (EMI Date + Loan ID) was found in your ledger.
   • ⚠️ OVERDUE: The due date has passed without a matching repayment detected.
   • 🕒 PENDING: Future installments based on the original schedule.

Linking EMI Transactions

When a bank transaction matches a loan EMI:

1. Open the transaction (from Transactions or Triage).
2. In the edit view, find the Link to Loan dropdown.
3. Select the relevant loan.
4. The system updates the outstanding balance, reduces principal, and recalculates interest for the next term.

AI Loan Advisor

On the Loan Details page:

• Click "Get AI Advice" to receive Gemini-powered analysis including:
  • Interest rate comparison with market standards.
  • Prepayment strategies to save interest.
  • EMI burden assessment.
  • Specific actionable tips.
• On the Loans overview page, get portfolio-wide debt strategy (snowball vs. avalanche analysis).

---

💼 11. Expense Groups

Creating an Expense Group

1. Navigate to Expense Groups from the sidebar.
2. Click Create Group and enter:
   • Name: e.g., "Goa Trip", "Wedding", "Home Renovation".
   • Budget: Total expected spending for this event.
   • Date Range: Start and end dates (optional).
   • Icon: Emoji for quick identification.

Assigning Transactions

• From the Transaction Modal, select the Expense Group dropdown.
• From the Expense Group Details page, click Manage Transactions to bulk-assign existing transactions.
• On mobile, use the Manage Group Transactions screen to search and link transactions.

Monitoring Spending

Each group card shows:

• Budget vs. Consumed with a progress bar.
• Transaction list filtered to the group.
• Date range and activity status.

---

📂 12. Document Vault

Uploading Documents (Web)

1. Navigate to Vault from the sidebar.
2. Click Upload and select a file.
3. Optionally:
   • Assign a Document Type (Receipt, Invoice, Certificate, etc.).
   • Link to a Transaction.
   • Place in a Folder.

Uploading Documents (Mobile)

1. Open the Vault tab on the mobile app.
2. Tap the Upload button and select a file from your device.
3. Thumbnails are auto-generated for images and PDFs.

Folder Management

• Create folders to organize documents (e.g., "Tax Documents", "Insurance", "Receipts").
• Drag-and-drop or use Move to rearrange documents between folders.
• Folders can be nested (parent-child hierarchy).

Version History

• Re-uploading a file with the same name in the same folder automatically creates a new version (v1, v2, v3...).
• Previous versions are preserved and accessible.

Google Drive Cloud Sync

1. Go to Vault → Settings → Cloud Sync.
2. Enter your Google OAuth2 credentials (Client ID + Client Secret).
3. Complete the authorization flow.
4. Click Sync to Cloud — all vault documents are uploaded to a WealthFam_Vault folder in your Google Drive, preserving folder structure.

Linking Documents to Transactions

• From the Transaction Modal → Documents section, attach documents.
• From the Vault, click any document and use Link to Transaction to associate it.

---

🧠 13. AI Configuration & Insights

Setting Up AI

1. Go to Settings → AI Settings.
2. Enter your Gemini API Key (from Google AI Studio).
3. Select a Model (e.g., gemini-1.5-flash).
4. Toggle Enable AI.

What AI Powers

Once configured, AI enhances multiple features:

• Dashboard Insights: 3 AI-generated observations on your spending patterns (refreshes every 24h).
• Loan Advice: Individual and portfolio-wide debt strategy analysis.
• Merchant Cleaning: Converts noisy bank descriptions into clean merchant names.
• Transaction Parsing: Smart extraction of transaction data from raw SMS/email content.
• Structured Insights: 5 detailed insights with type, title, icon, and actionable content.

Managing AI Cache

• AI insights are cached for 24 hours to minimize API usage.
• On the dashboard, a "Cached" chip appears if showing cached insights.
• Click the Refresh button to force-regenerate fresh insights (uses API quota).

---

🛡️ 14. Privacy & Security

Masking Mode

• Use Case: Before reviewing financials in public or sharing your screen.
• How: Toggle the Eye Icon (masking mode) or use the "Toggle Mask" button on the Android foreground service notification.
• Effect: All absolute currency values are obfuscated (multiplied by a large factor). Percentage-based analytics and chart trends remain intact.

Member Privacy

• Tenant Admins (OWNER role) can view aggregate family data and individual budgets.
• Admins cannot see granular private transaction notes of other "Adult" members unless explicitly shared.
• Child role members only see their personal goals and limited dashboard data.

Device Authorization

• Every new mobile device generates a unique Hardware ID.
• Navigate to Settings → Devices to see all registered devices.
• Admin must approve each device before it can submit SMS transaction data.

Session Security

• JWT tokens are tracked via per-session JTI in the UserToken table.
• Expired and revoked tokens are automatically pruned daily at 03:00 UTC.
• Multiple devices can maintain independent sessions.

---

🔄 15. Recurring Transactions

Setting Up Recurring Bills

1. Navigate to Insights → Recurring tab.
2. Click Add Recurring and fill in:
   • Name: e.g., "Netflix", "Electricity Bill".
   • Amount and Type (Debit/Credit).
   • Frequency: Daily, Weekly, Bi-Weekly, Monthly, Quarterly, Yearly.
   • Start Date and Account.
   • Category (optional).
3. The system automatically generates transactions on the scheduled dates.

How Auto-Generation Works

• The daily_recurrence_check runs every day at 00:01 UTC.
• It scans all RecurringTransaction records where next_run_date <= now and is_active == True.
• For each match, a transaction is created and next_run_date is advanced by the frequency.
• Dashboard shows upcoming bills for the next 30 days.

---

📱 16. Mobile-Specific Features

Consolidated Dashboard API

The mobile app uses a single get_consolidated_dashboard() API call that returns:

• Summary metrics (today, yesterday, monthly totals).
• Budget health.
• Daily and monthly trends.
• Category distribution.
• Investment summary.
• Recent transactions.
• Triage count. This minimizes network round-trips for a smooth mobile experience.

Spending Heatmap (Mobile)

• spending_heatmap_widget.dart — A GitHub-style calendar heatmap showing daily spending intensity.
• Color gradients indicate relative spending levels across the month.

Calendar Heatmap

• calendar_heatmap_widget.dart — Visualize spending patterns across weeks and months with color-coded cells.

Analytics Screen (Mobile)

• analytics_screen.dart (52KB) — Full analytics with charts, category breakdowns, and trend analysis optimized for mobile interaction.

---

🗂️ 17. Categories & Rules

Managing Categories

1. Go to Categories from the sidebar (Web) or Categories Management (Mobile).
2. Create categories with:
   • Name: e.g., "Food", "Transport", "Shopping".
   • Icon: Emoji representation.
   • Color: Hex color code.
   • Type: Expense or Income.
   • Parent: Optional — create sub-categories (e.g., "Dining Out" under "Food").

Auto-Categorization Rules

1. Go to Settings → Parser / Categories.
2. Create Category Rules:
   • Name: Rule identifier (e.g., "Food Apps").
   • Keywords: JSON list of matching strings (e.g., ["Zomato", "Swiggy"]).
   • Category: Target category to assign.
   • Priority: Higher priority rules execute first.
   • Is Transfer: Mark as transfer rule with destination account.
   • Exclude from Reports: Auto-exclude matched transactions.

Parser Pattern Training

1. Open the Neural Training screen (Mobile) or Transaction Training Modal (Web).
2. Select a bank SMS message from the Unparsed list.
3. Label the fields: Amount, Date, Recipient, Account Mask, Ref ID, Category, Balance, Credit Limit.
   • Tip: Labeling Balance or Credit Limit will anchor your account's "New Reality" balance.
4. Enable Retroactive Sweep to automatically test this new pattern against all other unparsed messages. Matches will be promoted to the Triage queue.
5. The system generates a regex pattern and pushes it to the parser service.
6. Future SMS from the same sender will be automatically parsed using this pattern.

---

🏷️ 18. Merchant Alias Management

Creating an Alias

1. Navigate to Transactions or Settings → Parser.
2. Click Add Merchant Alias.
3. Enter the Pattern (the noisy text from the bank, e.g., UPI/ZOMATO/TXN123) and the Clean Name (e.g., Zomato).

Retroactive Updates

• When saving an alias, toggle "Update Past Transactions".
• This will scan your entire history and rename all matching transactions to the clean name.
• Use "Preview Impact" first to see how many transactions will be affected before committing.

---

📋 19. Ingestion Audit & Spam Control

Monitoring the Audit Trail

1. Go to Settings → Devices → Event Log.
2. Here you can see every event: sms_received, device_login, parse_failed, etc.
3. Use this to debug why a specific message didn't appear or to verify background sync health.

Managing Spam & Noise

1. Navigate to Triage → Unparsed Messages.
2. For unwanted messages (OTP, marketing), you can:
   • Dismiss: Removes the single message.
   • Mark as Spam: Blocks all future messages from this sender/subject and creates a SpamFilter rule.
   • Ignore Pattern: Create an IgnoredPattern rule for specific keywords to skip in the future.

---

🏦 20. Auto-Account Discovery

How to use Auto-Discovery

1. When a transaction arrives for an unknown account, WealthFam creates a "Detected" account (e.g., Detected: SMS (XX1234)).
2. Navigate to Settings → Accounts.
3. Find the account marked with the "Unverified" badge.
4. Click Edit, provide a proper name (e.g., "HDFC Savings"), and click Verify.
5. All future transactions for this mask will now map to your verified account.