Financial Advisor 💰

Personal AI-Powered Financial Advisor - A multiplatform desktop application for managing your finances with AI assistance, built with Tauri, Svelte, Praxis, and PluresDB.

🎯 Overview

FinancialAdvisor is a modern personal finance management system that combines:

• Tauri Desktop App - Cross-platform desktop application (Windows, macOS, Linux)
• SvelteKit UI - Modern, reactive user interface with Svelte 5
• Praxis Framework - Schema-driven application logic and business rules
• PluresDB - Local-first data storage with real-time sync and vector storage for AI
• AI Integration - Support for multiple AI providers (OpenAI, Ollama, etc.)
• MCP Protocol - Model Context Protocol for AI agent integration

🏗️ Architecture

FinancialAdvisor/
├── 📱 src/                      # SvelteKit frontend application
│   ├── routes/                  # Application pages
│   │   ├── accounts/           # Account management
│   │   ├── transactions/       # Transaction tracking
│   │   ├── reports/            # Financial reports
│   │   └── settings/           # App settings
│   └── lib/                    # Shared libraries
│       ├── praxis/             # Praxis schema & logic
│       ├── pluresdb/           # PluresDB integration
│       ├── stores/             # Svelte stores
│       └── components/         # Reusable components
├── 🦀 src-tauri/               # Tauri Rust backend
│   ├── src/                    # Rust source code
│   ├── Cargo.toml              # Rust dependencies
│   └── tauri.conf.json         # Tauri configuration
├── 📦 packages/                # Legacy packages (being migrated)
│   ├── shared/                 # Common types and utilities
│   ├── financial-tools/        # Core financial calculations
│   ├── ai-integration/         # AI provider abstractions
│   └── mcp-server/             # MCP server implementation
└── 📚 docs/                    # Documentation

✨ Features

🏦 Financial Management

• Account Tracking - Monitor multiple accounts (checking, savings, investment, etc.)
• Transaction Management - Add and categorize transactions
• Budget Planning - Create and track budgets (coming soon)
• Goal Setting - Set and monitor financial goals (coming soon)
• Investment Analysis - Portfolio tracking (coming soon)

🤖 AI-Powered Insights

• Smart Categorization - Automatic transaction categorization using AI
• Spending Analysis - AI-powered spending pattern recognition
• Financial Advice - Personalized recommendations based on your data
• Report Generation - Automated financial reports with insights

🔐 Security & Privacy

• Local-First Storage - All data stored locally using PluresDB
• No Cloud Dependencies - Complete offline operation capability
• Data Encryption - Secure storage of sensitive information
• Vector Storage - AI embeddings stored locally for privacy

🔌 Extensibility

• Praxis Schema - Declarative data models and business rules
• AI Provider Choice - Support for OpenAI, Anthropic, Ollama, and custom providers
• MCP Protocol - Standard Model Context Protocol for AI integration
• Multiplatform - Desktop support for Windows, macOS, and Linux

🚀 Quick Start

Prerequisites

• Node.js 20+ (22+ recommended)
• Rust - Install from rustup.rs
• Platform-specific dependencies:
  • Windows: Visual Studio with C++ tools, WebView2
  • macOS: Xcode Command Line Tools
  • Linux: Build essentials, webkit2gtk-4.1, libssl-dev

Installation

# Clone the repository
git clone https://github.com/plures/FinancialAdvisor.git
cd FinancialAdvisor

# Install dependencies
npm install

# Run in development mode
npm run tauri:dev

# Build for production
npm run tauri:build

🛠️ Development

Setup Development Environment

# One-command setup
make bootstrap

# Or manually:
npm install
npm run setup:hooks
npm run build
npm run test

Available Commands

# Development
make build          # Build the project
make watch          # Watch for changes
make test           # Run all tests
make lint           # Run linting
make format         # Format code

# Quality checks
make check-all      # Run all quality checks
make coverage       # Generate coverage report
make audit          # Security audit

# Package & Release
make package        # Create VSIX package
make release-check  # Check release readiness

Project Structure

├── src/
│   ├── extension/          # VSCode extension code
│   │   ├── providers/      # Financial advice providers
│   │   └── mcp/           # MCP server integration
│   ├── mcp-server/        # MCP server implementation
│   └── shared/            # Shared types and utilities
├── test/
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
├── .github/
│   ├── workflows/         # CI/CD pipelines
│   └── ISSUE_TEMPLATE/    # Issue templates
└── docs/                  # Documentation

🧪 Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration

# With coverage
npm run coverage

📦 Building & Packaging

# Build TypeScript
npm run build

# Package extension
npm run package

# Publish (requires tokens)
npm run publish

Manual Installation

1. Clone and Setup

 git clone https://github.com/plures/FinancialAdvisor.git
 cd FinancialAdvisor
 npm install
 npm run build

1. Install VSCode Extension

 cd packages/vscode-extension
 npm run package
 code --install-extension financial-advisor-1.0.0.vsix

1. Configure MCP Server

 # Set data directory
 export FINANCIAL_ADVISOR_DATA_DIR="$HOME/.financial-advisor"
 
 # Optional: Set encryption key
 export FINANCIAL_ADVISOR_ENCRYPTION_KEY="your-secure-key"
 
 # Start MCP server
 npm run start --workspace=@financialadvisor/mcp-server

First Steps

1. Open VSCode and activate the Financial Advisor extension
2. Setup MCP Server via Command Palette: Financial Advisor: Setup MCP Server
3. Add Your First Account using the dashboard or command: Financial Advisor: Add Account
4. Import Transactions or add them manually
5. Configure AI Provider for intelligent insights

📖 Documentation

📋 User Guide

Adding Financial Accounts

The Add Account feature allows you to register your financial accounts for tracking and analysis.

Via VS Code Extension

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run Command: Financial Advisor: Add Account
3. Fill in the details when prompted:
   • Account Name: A unique identifier for your account
   • Account Type: Choose from available types
   • Current Balance: Enter the current account balance
   • Institution (optional): Your bank or financial institution

Supported Account Types

• checking - Primary checking accounts
• savings - Savings accounts and money market accounts
• credit_card - Credit card accounts (balances can be negative)
• investment - Investment and brokerage accounts
• loan - Personal loans and lines of credit
• mortgage - Home mortgages and property loans
• retirement - 401(k), IRA, and other retirement accounts

Input Validation

The system validates your input to ensure data integrity:

• ✅ Account names must be unique - Duplicate names are not allowed
• ✅ Required fields - Name, type, and balance are mandatory
• ✅ Valid account types - Only predefined types are accepted
• ✅ Numeric balance - Balance must be a valid number (negative allowed for credit cards)
• ✅ Whitespace handling - Leading/trailing spaces are automatically trimmed

Examples

Basic Checking Account:

Name: "Primary Checking"
Type: checking
Balance: 2,500.75
Institution: "Bank of America"

Credit Card (with negative balance):

Name: "Chase Freedom"
Type: credit_card
Balance: -1,250.00
Institution: "Chase Bank"

Investment Account:

Name: "Fidelity 401k"
Type: retirement
Balance: 125,000.00
Institution: "Fidelity Investments"

Via MCP Server API

You can also add accounts programmatically via the MCP server:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_account",
    "arguments": {
      "name": "Savings Account",
      "type": "savings",
      "balance": 5000.00,
      "currency": "USD",
      "institution": "Local Credit Union"
    }
  }
}

Package Documentation

🔧 Shared Package (@financialadvisor/shared)

Common types, interfaces, and utilities used across all packages.

import { Account, Transaction, formatCurrency } from '@financialadvisor/shared';

const account: Account = {
  id: 'acc-1',
  name: 'Checking Account',
  type: AccountType.CHECKING,
  balance: 1500.00,
  currency: 'USD',
  lastUpdated: new Date(),
  isActive: true
};

console.log(formatCurrency(account.balance)); // $1,500.00

🧮 Financial Tools (@financialadvisor/financial-tools)

Core financial calculations and analysis tools.

import { BudgetCalculator, TransactionAnalyzer } from '@financialadvisor/financial-tools';

// Analyze spending patterns
const insights = TransactionAnalyzer.analyzeTransactions(transactions, timeframe);
console.log(`Savings rate: ${insights.savingsRate.toFixed(1)}%`);

// Budget analysis
const budgetAnalysis = BudgetCalculator.analyzeBudget(budget, transactions);
console.log(`Budget used: ${budgetAnalysis.percentageUsed.toFixed(1)}%`);

🤖 AI Integration (@financialadvisor/ai-integration)

AI provider abstractions for financial analysis.

import { AIProviderFactory, AIProviderType } from '@financialadvisor/ai-integration';

// OpenAI provider
const provider = AIProviderFactory.createProvider(AIProviderType.OPENAI, {
  apiKey: 'your-api-key',
  model: 'gpt-4'
});

// Analyze financial data
const response = await provider.analyzeFinancialData(context, {
  type: 'analysis',
  prompt: 'What are my spending patterns?'
});

🔐 MCP Server (@financialadvisor/mcp-server)

Secure local storage with MCP protocol support.

import { FinancialAdvisorMCPServer } from '@financialadvisor/mcp-server';

const server = new FinancialAdvisorMCPServer({
  dbPath: './financial.db',
  encryptionKey: 'your-encryption-key',
  backupEnabled: true
});

await server.run();

VSCode Extension

The VSCode extension provides a complete UI for managing your financial data:

Commands

• Financial Advisor: Open Dashboard - Main financial dashboard
• Financial Advisor: Add Transaction - Quick transaction entry
• Financial Advisor: Add Account - Account management
• Financial Advisor: Analyze Spending - AI-powered spending analysis
• Financial Advisor: Generate Report - Custom financial reports
• Financial Advisor: Configure AI - AI provider setup

Views

• Accounts View - List and manage all accounts
• Transactions View - Recent transaction history
• Budgets View - Budget tracking and alerts
• Goals View - Financial goal monitoring

Dashboard Features

• Real-time account balances
• Transaction categorization
• Spending analysis charts
• Budget progress indicators
• Goal tracking widgets

🔧 Configuration

MCP Server Configuration

Create a .financial-advisor-config.json file:

{
  "aiModel": {
    "provider": "local",
    "model": "llama3",
    "endpoint": "http://localhost:11434"
  },
  "privacy": {
    "localOnly": true,
    "encryptData": true
  },
  "features": {
    "budgetTracking": true,
    "investmentAdvice": true,
    "goalSetting": true
  }
}

VS Code Settings

{
  "financialAdvisor.autoStart": true,
  "financialAdvisor.notifications": true,
  "financialAdvisor.dataPath": "./financial-data"
}

Quick MCP setup (Windows PowerShell)

• In VS Code, open Settings (Ctrl+,) and set:

  • financialAdvisor.mcpServer.dataDir → e.g., C:\Users\YOUR_USER\.financial-advisor
  • financialAdvisor.mcpServer.path → optional full path to financial-advisor-mcp if it’s not on PATH

• Or add to your .vscode/settings.json:

{
  "financialAdvisor.mcpServer.dataDir": "C:\\Users\\YOUR_USER\\.financial-advisor",
  "financialAdvisor.security.encryptionEnabled": true
}

• Optional: start the MCP server manually for troubleshooting:

# If installed globally or available on PATH
financial-advisor-mcp

# Or from the package (after building the monorepo)
pwsh -NoProfile -Command "npm run build:all:win; cd packages/mcp-server; node dist/cli.js"

🔒 Security & Privacy

• Local-First: Financial data never leaves your machine by default
• Encryption: Sensitive data is encrypted at rest
• Audit Trail: All operations are logged for transparency
• No Telemetry: No usage data is collected without explicit consent

Security Features

• 🔐 End-to-end encryption for financial data
• 🛡️ Regular security scans (CodeQL, OSV)
• 🔍 Dependency vulnerability monitoring
• 📋 SBOM generation for supply chain transparency

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make changes and add tests
4. Run quality checks: make check-all
5. Commit changes: git commit -m 'feat: add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Style

• TypeScript with strict mode
• ESLint + Prettier for formatting
• Conventional Commits for commit messages
• 80%+ test coverage requirement

📚 Docs & Guides

• API Documentation
• Architecture Decisions
• User Guide
• Developer Guide
• Security Guide

🗺️ Roadmap

See docs/ROADMAP.md for the prioritized MVP and 1.0.0 plan.

📊 Metrics & Analytics

• Code Coverage:
• Build Status:
• Security Score:

🆘 Support

• 📋 Issues
• 💬 Discussions
• 📧 Email: support@financial-advisor.dev
• 📚 Documentation