Skip to content

FinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and data-driven decision-making in a user-friendly environment.

chore: add remaining Windows Python DLLs and update configs

tilakpatel2241d76b01abdc
diff --git a/docs/DEVELOPER_WALKTHROUGH.md b/docs/DEVELOPER_WALKTHROUGH.md
new file mode 100644
index 000000000..630905b31
--- /dev/null
+++ b/docs/DEVELOPER_WALKTHROUGH.md
@@ -0,0 +1,878 @@
+# Developer Walkthrough - Fincept Terminal
+
+**Version:** 3.0.11
+**Last Updated:** 2025-01-04
+
+## Quick Navigation
+
+- [Project Structure](#project-structure)
+- [Getting Started](#getting-started)
+- [Frontend Architecture](#frontend-architecture)
+- [Backend Architecture](#backend-architecture)
+- [Key Systems](#key-systems)
+- [Adding Features](#adding-features)
+- [Common Tasks](#common-tasks)
+
+---
+
+## Project Structure
+
+```
+fincept-terminal-desktop/
+├── src/ # Frontend React application
+│ ├── main.tsx # Entry point
+│ ├── App.tsx # Root component
+│ ├── components/ # UI components
+│ ├── contexts/ # React contexts (global state)
+│ ├── services/ # API & business logic
+│ ├── hooks/ # Custom React hooks
+│ └── lib/ # Utility libraries
+│
+├── src-tauri/ # Backend Rust application
+│ ├── src/
+│ │ ├── lib.rs # Main Tauri library
+│ │ ├── main.rs # Entry point
+│ │ ├── commands/ # Tauri commands (exposed to frontend)
+│ │ ├── data_sources/ # Data source utilities
+│ │ └── utils/ # Backend utilities
+│ ├── resources/
+│ │ ├── python/ # Bundled Python runtime
+│ │ └── scripts/ # Python analytics & agents
+│ ├── Cargo.toml # Rust dependencies
+│ └── tauri.conf.json # Tauri configuration
+│
+├── docs/ # Documentation
+├── public/ # Static assets
+└── package.json # Node.js dependencies
+```
+
+---
+
+## Getting Started
+
+### Prerequisites
+- Node.js 18+ (LTS recommended)
+- Rust 1.70+
+- Python 3.11+ (bundled with app, needed for development)
+
+### Installation
+```bash
+cd fincept-terminal-desktop
+npm install
+```
+
+### Development
+```bash
+npm run dev # Frontend only (port 1420)
+npm run tauri dev # Full app with Tauri
+```
+
+### Building
+```bash
+npm run build # Frontend build
+npm run tauri build # Production build (creates installer)
+```
+
+---
+
+## Frontend Architecture
+
+### 📁 Directory Map
+
+#### **Components** (`src/components/`)
+
+**Authentication** (`auth/`)
+- `LoginScreen.tsx` - User login
+- `RegisterScreen.tsx` - New user registration
+- `PricingScreen.tsx` - Subscription plans
+- `ForgotPasswordScreen.tsx` - Password recovery
+
+**Dashboard** (`dashboard/`)
+- `DashboardScreen.tsx` - Main terminal layout & tab management
+
+**Terminal Tabs** (`tabs/`)
+All major features are in separate tab components:
+- `DashboardTab.tsx` - Overview & metrics
+- `MarketsTab.tsx` - Real-time market data
+- `PortfolioTab.tsx` - Portfolio management → [`portfolio/`](../src/components/tabs/portfolio/)
+- `AnalyticsTab.tsx` - Financial analytics
+- `ChatTab.tsx` - AI chat (Ollama integration)
+- `NodeEditorTab.tsx` - Visual workflow builder → [`node-editor/`](../src/components/tabs/node-editor/)
+- `SettingsTab.tsx` - App configuration
+- [See full list in CLAUDE.md](../CLAUDE.md#available-terminal-tabs)
+
+**Specialized Modules**
+- [`node-editor/`](../src/components/tabs/node-editor/) - Workflow system (ReactFlow-based)
+ - `DataSourceNode.tsx` - Data source nodes
+ - `MCPToolNode.tsx` - MCP tool nodes
+ - `PythonAgentNode.tsx` - Python agent nodes
+ - `WorkflowExecutor.ts` - Execution engine
+
+- [`data-sources/`](../src/components/tabs/data-sources/) - Data connectivity
+ - [`adapters/`](../src/components/tabs/data-sources/adapters/) - 100+ data connectors
+ - `PostgreSQLAdapter.ts`, `MongoDBAdapter.ts`, `KafkaAdapter.ts`, etc.
+ - `dataSourceConfigs.ts` - Adapter registry
+
+- [`mcp/`](../src/components/tabs/mcp/) - Model Context Protocol integration
+ - `MCPServerCard.tsx` - MCP server management UI
+ - [`marketplace/`](../src/components/tabs/mcp/marketplace/) - MCP server marketplace
+ - [`docs/`](../src/components/tabs/mcp/docs/) - MCP integration guides
+
+**UI Components** (`ui/`)
+shadcn/ui based components: button, card, dialog, dropdown, etc.
+
+#### **Contexts** (`src/contexts/`)
+Global state management via React Context:
+- `AuthContext.tsx` - Authentication, user session
+- `NavigationContext.tsx` - Tab navigation state
+- `ThemeContext.tsx` - Theme preferences
+- `DataSourceContext.tsx` - Data source connections
+
+#### **Services** (`src/services/`)
+API communication & business logic:
+
+**Authentication & User**
+- `authApi.tsx` - Login, register, session management
+- `paymentApi.tsx` - Subscription payments
+- `userApi.tsx` - User profile operations
+
+**Market Data**
+- `marketDataService.ts` - Unified market data interface
+- `polygonService.ts` - Polygon.io integration
+- `alphaVantageService.ts` - Alpha Vantage API
+- `yfinanceService.ts` - Yahoo Finance wrapper
+
+**Analytics & Portfolio**
+- `portfolioService.ts` - Portfolio analytics
+- `workflowService.ts` - Workflow execution engine
+- `nodeExecutionManager.ts` - Node execution logic
+
+**AI & Agents**
+- `ollamaService.ts` - Local LLM (Ollama)
+- `pythonAgentService.ts` - Python agent execution
+- `agentLLMService.ts` - Agent-LLM bridge
+- `mcpManager.ts` - MCP server lifecycle
+- `mcpClient.ts` - MCP client implementation
+
+**Data Management**
+- `dataSourceRegistry.ts` - Register all data adapters
+- `storageService.ts` - Local storage utilities
+- `chatDatabase.ts` - Chat history (Dexie/IndexedDB)
+- `duckdbService.ts` - DuckDB integration
+
+#### **Hooks** (`src/hooks/`)
+- `useDataSource.ts` - Data source connection hook
+- `useWebSocket.ts` - WebSocket connection management
+- `useAutoUpdater.ts` - Auto-update logic
+- `use-mobile.ts` - Mobile detection
+
+---
+
+## Backend Architecture
+
+### 📁 Rust Backend (`src-tauri/src/`)
+
+#### **Main Files**
+- **`lib.rs`** - Tauri application entry, command registration
+ - MCP server management (spawn, kill, communicate)
+ - Python script execution
+ - Command handler registration (~900 commands!)
+
+- **`main.rs`** - Application bootstrap
+
+#### **Commands** (`commands/`)
+Tauri commands expose backend functionality to frontend via `invoke()`:
+
+**Market Data Commands**
+- `market_data.rs` - Generic market data operations
+- `polygon.rs` - Polygon.io API wrapper
+- `yfinance.rs` - Yahoo Finance wrapper
+- `alphavantage.rs` - Alpha Vantage API
+
+**Economic Data Commands**
+- `fred.rs` - Federal Reserve Economic Data
+- `bis.rs` - Bank for International Settlements
+- `bls.rs` - Bureau of Labor Statistics
+- `eia.rs` - Energy Information Administration
+- `ecb.rs` - European Central Bank
+- `bea.rs` - Bureau of Economic Analysis
+- `worldbank.rs` - World Bank data
+- `oecd.rs` - OECD statistics
+- `imf.rs` - International Monetary Fund
+- `unesco.rs` - UNESCO statistics
+
+**Government & Regulatory**
+- `sec.rs` - SEC filings & data
+- `cftc.rs` - CFTC Commitments of Traders
+- `congress_gov.rs` - US Congress bills & legislation
+- `government_us.rs` - US Treasury data
+- `cboe.rs` - CBOE market data
+- `nasdaq.rs` - NASDAQ data & screeners
+
+**Financial Analytics**
+- `fmp.rs` - Financial Modeling Prep API
+- `multpl.rs` - Market multiples & valuations
+- `trading_economics.rs` - Trading Economics data
+- `econdb.rs` - EconDB integration
+
+**International Data**
+- `wto.rs` - World Trade Organization
+- `canada_gov.rs`, `datagovuk.rs`, `datagov_au.rs` - Government data
+- `estat_japan.rs`, `govdata_de.rs`, `datagovsg.rs` - Regional data
+- `french_gov.rs`, `swiss_gov.rs`, `spain_data.rs` - European data
+
+**Specialized**
+- `portfolio.rs` - Portfolio analytics commands
+- `agents.rs` - Python agent execution
+- `jupyter.rs` - Jupyter notebook operations
+- `coingecko.rs` - Cryptocurrency data
+- `oscar.rs` - Satellite & instrument data
+- `sentinelhub.rs` - Satellite imagery
+
+**Command Registration**
+All commands are registered in `lib.rs` (~line 390-945):
+```rust
+.invoke_handler(tauri::generate_handler![
+ // ... 900+ commands
+])
+```
+
+#### **Utilities** (`utils/`)
+- Python path resolution
+- Bundled runtime management
+
+### 📁 Python Backend (`src-tauri/resources/scripts/`)
+
+#### **Analytics Modules** ([`Analytics/`](https://github.com/Fincept-Corporation/FinceptTerminal/tree/main/fincept-terminal-desktop/src-tauri/resources/scripts/Analytics))
+Complete CFA-level financial analytics:
+
+- **`equityInvestment/`** - Stock valuation
+ - DCF models (FCFF, FCFE)
+ - Dividend discount models
+ - Multiples analysis
+ - Fundamental analysis
+
+- **`portfolioManagement/`** - Portfolio optimization
+ - Mean-variance optimization
+ - Risk parity
+ - Black-Litterman model
+ - Factor models
+
+- **`derivatives/`** - Options pricing
+ - Black-Scholes model
+ - Greeks calculation
+ - Options strategies
+ - Hedging analysis
+
+- **`economics/`** - Economic indicators
+ - GDP analysis
+ - Inflation models
+ - Policy analysis
+
+- **`quant/`** - Quantitative finance
+ - Statistical models
+ - Backtesting frameworks
+ - Risk metrics
+
+- **`ml4Trading/`** - Machine learning
+ - Prediction models
+ - Feature engineering
+ - Model evaluation
+
+- **`technical_indicators.py`** - Technical analysis functions
+
+#### **AI Agents** ([`agents/`](https://github.com/Fincept-Corporation/FinceptTerminal/tree/main/fincept-terminal-desktop/src-tauri/resources/scripts/agents))
+
+**Investor Personas** (`TraderInvestorsAgent/`)
+- Warren Buffett strategy
+- Benjamin Graham value investing
+- Peter Lynch growth investing
+- Ray Dalio principles
+- George Soros reflexivity
+- 20+ legendary investors
+
+**Hedge Fund Strategies** (`hedgeFundAgents/`)
+- Bridgewater All-Weather portfolio
+- Citadel multi-strategy quant
+- Renaissance Technologies statistical arbitrage
+- Two Sigma ML-driven strategies
+
+**Geopolitical Analysis** (`GeopoliticsAgents/`)
+- Grand Chessboard framework
+- Prisoners of Geography analysis
+- World Order models
+- Central bank policy tracking
+
+**Economic Agents** (`EconomicAgents/`)
+- Macro analysis
+- Policy impact assessment
+- Economic forecasting
+
+#### **Data Scripts**
+Individual Python scripts for data APIs:
+- `yfinance_data.py`, `polygon_data.py`, `alphavantage_data.py`
+- `bis_data.py`, `fred_data.py`, `worldbank_data.py`
+- `sec_data.py`, `eia_data.py`, `bls_data.py`
+- 50+ data source scripts
+
+---
+
+## Key Systems
+
+### 🔐 Authentication Flow
+
+**Guest Users** (Temporary access)
+1. User clicks "Continue as Guest" → `LoginScreen.tsx`
+2. `authApi.guestLogin()` → Backend creates 24hr session
+3. `AuthContext` stores session → localStorage
+4. Navigate to dashboard
+
+**Registered Users**
+1. Login/Register → `LoginScreen.tsx` / `RegisterScreen.tsx`
+2. `authApi.login()` / `authApi.register()` → JWT token
+3. Check subscription status → redirect to pricing if needed
+4. `AuthContext` manages session
+
+**Files:**
+- Frontend: `src/components/auth/*.tsx`, `src/contexts/AuthContext.tsx`, `src/services/authApi.tsx`
+- Backend: Authentication handled by external API (not in Tauri)
+
+### 💳 Payment System
+
+1. User selects plan → `PricingScreen.tsx`
+2. `paymentApi.createOrder()` → Order ID
+3. Payment window opens (Razorpay/Stripe)
+4. Callback → verify payment → update subscription
+5. Navigate to dashboard
+
+**Files:**
+- `src/components/auth/PricingScreen.tsx`
+- `src/components/payment/*.tsx`
+- `src/services/paymentApi.tsx`
+
+### 📊 Market Data Pipeline
+
+**Unified Interface:**
+```typescript
+// Frontend
+import { marketDataService } from '@/services/marketDataService';
+const quote = await marketDataService.getQuote('AAPL');
+```
+
+**Data Flow:**
+1. Frontend calls `marketDataService.ts`
+2. Service selects provider (Polygon/Alpha Vantage/yfinance)
+3. Invokes Tauri command: `invoke('get_market_quote', { symbol })`
+4. Rust command executes Python script
+5. Python fetches from API → returns JSON
+6. Rust parses → returns to frontend
+7. Frontend updates UI
+
+**Files:**
+- Frontend: `src/services/marketDataService.ts`, `src/services/polygonService.ts`
+- Backend: `src-tauri/src/commands/market_data.rs`, `src-tauri/resources/scripts/polygon_data.py`
+
+### 🤖 AI Chat (Ollama)
+
+**Local LLM Integration:**
+1. User sends message → `ChatTab.tsx`
+2. `ollamaService.chat()` → Ollama API (local)
+3. Stream response → update UI
+4. Save to `chatDatabase.ts` (Dexie)
+
+**Optional MCP Tools:**
+- MCP servers provide tools to LLM
+- `mcpManager.ts` manages server lifecycle
+- LLM can invoke tools during chat
+
+**Files:**
+- `src/components/tabs/ChatTab.tsx`
+- `src/services/ollamaService.ts`
+- `src/services/mcpManager.ts`
+- `src/services/chatDatabase.ts`
+
+### 🔄 Workflow System (Node Editor)
+
+**Visual Programming:**
+1. User creates workflow → `NodeEditorTab.tsx` (ReactFlow)
+2. Drag nodes: Data Sources, Transformations, MCP Tools, Python Agents
+3. Connect nodes → define data flow
+4. Execute → `WorkflowExecutor.ts`
+5. Results displayed in `ResultsDisplayNode.tsx`
+
+**Node Types:**
+- **Data Source Node** (`DataSourceNode.tsx`) - Fetch data from 100+ sources
+- **MCP Tool Node** (`MCPToolNode.tsx`) - Execute MCP tools
+- **Python Agent Node** (`PythonAgentNode.tsx`) - Run AI agents
+- **Results Node** (`ResultsDisplayNode.tsx`) - Display output
+
+**Execution Engine:**
+- `WorkflowExecutor.ts` - Topological sort, dependency resolution
+- `nodeExecutionManager.ts` - Execute individual nodes
+- `workflowService.ts` - Save/load workflows
+
+**Files:**
+- `src/components/tabs/NodeEditorTab.tsx`
+- `src/components/tabs/node-editor/*`
+- `src/services/workflowService.ts`
+
+### 🔌 Data Sources (100+ Connectors)
+
+**Architecture:**
+```
+BaseAdapter (abstract)
+ ├── PostgreSQLAdapter
+ ├── MongoDBAdapter
+ ├── KafkaAdapter
+ ├── ...
+ └── RESTAdapter
+```
+
+**Adding a New Data Source:**
+1. Create adapter: `src/components/tabs/data-sources/adapters/MyAdapter.ts`
+ - Extend `BaseAdapter`
+ - Implement `connect()`, `execute()`, `disconnect()`
+2. Register: `src/components/tabs/data-sources/adapters/index.ts`
+3. Add config: `src/components/tabs/data-sources/dataSourceConfigs.ts`
+4. Now available in Node Editor + Data Sources tab
+
+**Files:**
+- All adapters: `src/components/tabs/data-sources/adapters/`
+- See [ADD_NEW_DATA_SOURCE.md](ADD_NEW_DATA_SOURCE.md)
+
+### 🛠️ MCP Integration
+
+**Model Context Protocol** - Extend AI capabilities
+
+**MCP Server Lifecycle:**
+1. User adds server → `MCPMarketplace.tsx` or `MCPAddServerModal.tsx`
+2. Frontend invokes: `invoke('spawn_mcp_server', { command, args })`
+3. Rust spawns process → manages stdin/stdout
+4. Frontend sends JSON-RPC → `mcpClient.ts`
+5. Server returns tools/resources
+6. Tools available in Node Editor & Chat
+
+**Available in:**
+- **Node Editor** - `MCPToolNode.tsx` executes MCP tools
+- **Chat** - LLM can invoke MCP tools
+- **MCP Tab** - Manage servers, view logs
+
+**Adding MCP Server:**
+- See `src/components/tabs/mcp/docs/ADDING_NEW_MCP.md`
+- Define in `src/components/tabs/mcp/marketplace/serverDefinitions.ts`
+
+**Files:**
+- `src/components/tabs/mcp/*`
+- `src/services/mcpManager.ts`, `src/services/mcpClient.ts`
+- `src-tauri/src/lib.rs` (MCP commands: spawn, send, kill)
+
+### 📈 Portfolio Analytics
+
+**CFA-Level Analytics:**
+1. User inputs portfolio → `PortfolioTab.tsx`
+2. Frontend calls: `invoke('calculate_portfolio_metrics', { holdings })`
+3. Rust executes: `src-tauri/src/commands/portfolio.rs`
+4. Python script: `src-tauri/resources/scripts/Analytics/portfolioManagement/`
+5. Returns: Sharpe ratio, VaR, beta, correlations, etc.
+
+**Available Analytics:**
+- Portfolio optimization (efficient frontier)
+- Risk metrics (VaR, CVaR, max drawdown)
+- Factor analysis
+- Scenario analysis
+- Retirement planning
+- Behavioral bias detection
+
+**Files:**
+- Frontend: `src/components/tabs/PortfolioTab.tsx`, `src/components/tabs/portfolio/*`
+- Backend: `src-tauri/src/commands/portfolio.rs`
+- Python: `src-tauri/resources/scripts/Analytics/portfolioManagement/*`
+
+### 🧠 Python Agents
+
+**Execution Flow:**
+1. User selects agent → Node Editor or Analytics tab
+2. Frontend: `invoke('execute_python_agent', { agentPath, params })`
+3. Rust: `src-tauri/src/commands/agents.rs`
+4. Python: `src-tauri/resources/scripts/agents/[AgentCategory]/agent.py`
+5. Agent executes → returns analysis
+6. Frontend displays results
+
+**Agent Categories:**
+- Investor personas (Buffett, Dalio, etc.)
+- Hedge fund strategies
+- Geopolitical analysis
+- Economic forecasting
+
+**Files:**
+- Frontend: `src/components/tabs/node-editor/PythonAgentNode.tsx`
+- Backend: `src-tauri/src/commands/agents.rs`
+- Python: `src-tauri/resources/scripts/agents/*`
+
+---
+
+## Adding Features
+
+### ✨ Add a New Terminal Tab
+
+**1. Create Component**
+```tsx
+// src/components/tabs/MyNewTab.tsx
+import React from 'react';
+
+const MyNewTab: React.FC = () => {
+ return (
+ <div className="p-4">
+ <h1>My New Feature</h1>
+ </div>
+ );
+};
+
+export default MyNewTab;
+```
+
+**2. Register Tab**
+Edit `src/components/dashboard/DashboardScreen.tsx`:
+```tsx
+import MyNewTab from '@/components/tabs/MyNewTab';
+
+// Add to tabs array
+const tabs = [
+ // ...
+ { id: 'mynew', label: 'My Feature', icon: Sparkles, component: MyNewTab },
+];
+```
+
+**3. Test**
+```bash
+npm run tauri dev
+```
+
+### 🔌 Add a Data Source Adapter
+
+**1. Create Adapter**
+```typescript
+// src/components/tabs/data-sources/adapters/MyAPIAdapter.ts
+import { BaseAdapter } from './BaseAdapter';
+
+export class MyAPIAdapter extends BaseAdapter {
+ async connect(config: any): Promise<void> {
+ // Initialize connection
+ }
+
+ async execute(query: string): Promise<any> {
+ // Fetch data
+ }
+
+ async disconnect(): Promise<void> {
+ // Cleanup
+ }
+}
+```
+
+**2. Register**
+```typescript
+// src/components/tabs/data-sources/adapters/index.ts
+export { MyAPIAdapter } from './MyAPIAdapter';
+```
+
+**3. Add Config**
+```typescript
+// src/components/tabs/data-sources/dataSourceConfigs.ts
+export const dataSourceConfigs = {
+ // ...
+ myapi: {
+ name: 'My API',
+ fields: [
+ { name: 'apiKey', label: 'API Key', type: 'password' },
+ ],
+ },
+};
+```
+
+### 🤖 Add a Python Analytics Module
+
+**1. Create Python Module**
+```python
+# src-tauri/resources/scripts/Analytics/myAnalysis/calculator.py
+import json
+import sys
+
+def calculate(data):
+ # Your analysis logic
+ result = { "metric": 42 }
+ return result
+
+if __name__ == "__main__":
+ input_data = json.loads(sys.argv[1])
+ output = calculate(input_data)
+ print(json.dumps(output))
+```
+
+**2. Create Rust Command**
+```rust
+// src-tauri/src/commands/my_analysis.rs
+use tauri::command;
+
+#[command]
+pub fn run_my_analysis(
+ app: tauri::AppHandle,
+ data: String,
+) -> Result<String, String> {
+ crate::execute_python_script(
+ app,
+ "Analytics/myAnalysis/calculator.py".to_string(),
+ vec![data],
+ None,
+ )
+}
+```
+
+**3. Register Command**
+```rust
+// src-tauri/src/commands/mod.rs
+pub mod my_analysis;
+
+// src-tauri/src/lib.rs
+.invoke_handler(tauri::generate_handler![
+ // ...
+ commands::my_analysis::run_my_analysis,
+])
+```
+
+**4. Call from Frontend**
+```typescript
+import { invoke } from '@tauri-apps/api/core';
+
+const result = await invoke('run_my_analysis', {
+ data: JSON.stringify({ values: [1, 2, 3] })
+});
+```
+
+### 🛠️ Add an MCP Server Definition
+
+**1. Define Server**
+```typescript
+// src/components/tabs/mcp/marketplace/serverDefinitions.ts
+export const serverDefinitions = {
+ // ...
+ my_tool: {
+ id: 'my_tool',
+ name: 'My Custom Tool',
+ description: 'Does something useful',
+ command: 'npx',
+ args: ['-y', '@my/mcp-server'],
+ env: {},
+ category: 'utilities',
+ },
+};
+```
+
+**2. (Optional) Create Custom Form**
+```tsx
+// src/components/tabs/mcp/marketplace/forms/MyToolForm.tsx
+export const MyToolForm: React.FC<Props> = ({ onSubmit }) => {
+ // Custom configuration UI
+};
+```
+
+**3. User Can Now:**
+- Install from MCP Marketplace tab
+- Use in Node Editor (`MCPToolNode`)
+- Available to AI chat
+
+### 🎨 Add a Custom Node Type
+
+**1. Create Node Component**
+```tsx
+// src/components/tabs/node-editor/MyCustomNode.tsx
+import { Handle, Position } from 'reactflow';
+
+export const MyCustomNode = ({ data }: NodeProps) => {
+ return (
+ <div className="custom-node">
+ <Handle type="target" position={Position.Top} />
+ <div>My Custom Logic</div>
+ <Handle type="source" position={Position.Bottom} />
+ </div>
+ );
+};
+```
+
+**2. Register Node Type**
+```typescript
+// src/components/tabs/NodeEditorTab.tsx
+const nodeTypes = {
+ // ...
+ myCustom: MyCustomNode,
+};
+```
+
+**3. Add Execution Logic**
+```typescript
+// src/components/tabs/node-editor/WorkflowExecutor.ts
+case 'myCustom':
+ result = await executeMyCustomLogic(node.data);
+ break;
+```
+
+---
+
+## Common Tasks
+
+### 🔍 Debugging
+
+**Frontend**
+```bash
+npm run dev # Open http://localhost:1420
+# Use browser DevTools (F12)
+# React DevTools extension recommended
+```
+
+**Backend (Rust)**
+```bash
+npm run tauri dev
+# Check terminal output for Rust logs
+# println!() statements appear in terminal
+```
+
+**Python Scripts**
+- Errors appear in Tauri terminal
+- Add `print()` statements for debugging
+- Output captured in Rust command
+
+### 🧪 Testing
+
+**Manual Testing**
+```bash
+npm run tauri dev # Test in development
+npm run tauri build # Test production build
+```
+
+**Test Checklist:**
+- Authentication flows (guest & registered)
+- Tab navigation
+- Data source connections
+- Workflow execution
+- Python analytics
+- MCP server spawning
+
+### 📦 Building Release
+
+**Full Build**
+```bash
+npm run build # Frontend
+npm run tauri build # Creates installer
+```
+
+**Output:**
+- Windows: `.msi` in `src-tauri/target/release/bundle/msi/`
+- macOS: `.dmg` in `src-tauri/target/release/bundle/dmg/`
+- Linux: `.AppImage`, `.deb` in `src-tauri/target/release/bundle/`
+
+**Version Bump**
+```bash
+npm run bump-version # Auto-increment version
+git tag v3.0.12
+git push --tags
+```
+
+### 🔧 Common Issues
+
+**Build fails with Rust errors:**
+```bash
+cd src-tauri
+cargo clean
+cargo build
+```
+
+**Python script not found:**
+- Check path in Rust command
+- Verify script exists in `src-tauri/resources/scripts/`
+- Ensure Python runtime is bundled
+
+**MCP server not spawning:**
+- Check server command/args in definition
+- Verify npm packages installed globally
+- Check Tauri terminal for spawn errors
+
+**Data source connection fails:**
+- Verify adapter config
+- Check API keys/credentials
+- Review adapter implementation
+
+### 📝 Code Style
+
+**TypeScript:**
+- Use functional components
+- Prefer `const` over `let`
+- Type all function parameters
+- Use interfaces for complex types
+
+**Rust:**
+- Follow Rust naming conventions
+- Use `Result<T, String>` for error handling
+- Document public functions
+
+**Python:**
+- PEP 8 style guide
+- Type hints recommended
+- JSON input/output for Tauri integration
+
+---
+
+## File Quick Reference
+
+### Essential Files
+
+| File | Purpose |
+|------|---------|
+| `src/main.tsx` | Frontend entry point |
+| `src/App.tsx` | Root component, routing |
+| `src/components/dashboard/DashboardScreen.tsx` | Main terminal layout |
+| `src/contexts/AuthContext.tsx` | Authentication state |
+| `src/services/authApi.tsx` | Auth API calls |
+| `src-tauri/src/lib.rs` | Tauri commands registration |
+| `src-tauri/src/commands/mod.rs` | Command module registry |
+| `src-tauri/tauri.conf.json` | Tauri configuration |
+| `package.json` | Node.js dependencies |
+| `src-tauri/Cargo.toml` | Rust dependencies |
+
+### Key Directories
+
+| Directory | Contents |
+|-----------|----------|
+| `src/components/tabs/` | All terminal tabs |
+| `src/components/tabs/node-editor/` | Workflow system |
+| `src/components/tabs/data-sources/adapters/` | Data connectors |
+| `src/components/tabs/mcp/` | MCP integration |
+| `src/services/` | Business logic & APIs |
+| `src-tauri/src/commands/` | Backend commands |
+| `src-tauri/resources/scripts/Analytics/` | Python analytics |
+| `src-tauri/resources/scripts/agents/` | AI agents |
+
+---
+
+## Additional Resources
+
+- [README.md](../README.md) - Project overview
+- [CLAUDE.md](../CLAUDE.md) - Detailed architecture guide
+- [ADD_NEW_DATA_SOURCE.md](ADD_NEW_DATA_SOURCE.md) - Data source tutorial
+- [src/components/tabs/mcp/docs/ADDING_NEW_MCP.md](../src/components/tabs/mcp/docs/ADDING_NEW_MCP.md) - MCP integration
+
+**External Docs:**
+- [Tauri Documentation](https://tauri.app/v2/)
+- [React 19 Docs](https://react.dev/)
+- [ReactFlow Docs](https://reactflow.dev/)
+
+---
+
+## Get Help
+
+- **Issues:** [GitHub Issues](https://github.com/Fincept-Corporation/FinceptTerminal/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/Fincept-Corporation/FinceptTerminal/discussions)
+- **Email:** [email protected]
+
+---
+
+**Happy Building! 🚀**
diff --git a/fincept-terminal-desktop/.github/workflows/build-with-updater.yml b/fincept-terminal-desktop/.github/workflows/build-with-updater.yml
index f396d81ca..5f0ff8376 100644
--- a/fincept-terminal-desktop/.github/workflows/build-with-updater.yml
+++ b/fincept-terminal-desktop/.github/workflows/build-with-updater.yml
@@ -87,9 +87,9 @@ jobs:
if [ "${{ matrix.platform }}" == "windows-latest" ]; then
./src-tauri/resources/python-windows/python.exe -m pip install -r ./src-tauri/resources/requirements.txt
elif [ "${{ matrix.platform }}" == "macos-latest" ]; then
- ./src-tauri/resources/python-macos/python/bin/python3 -m pip install -r ./src-tauri/resources/requirements.txt
+ ./src-tauri/resources/python-macos/bin/python3.12 -m pip install -r ./src-tauri/resources/requirements.txt
elif [ "${{ matrix.platform }}" == "ubuntu-22.04" ]; then
- ./src-tauri/resources/python-linux/python/bin/python3 -m pip install -r ./src-tauri/resources/requirements.txt
+ ./src-tauri/resources/python-linux/bin/python3.12 -m pip install -r ./src-tauri/resources/requirements.txt
fi
shell: bash
diff --git a/fincept-terminal-desktop/src-tauri/Cargo.lock b/fincept-terminal-desktop/src-tauri/Cargo.lock
index 983e3667a..44cc1e8c0 100644
--- a/fincept-terminal-desktop/src-tauri/Cargo.lock
+++ b/fincept-terminal-desktop/src-tauri/Cargo.lock
@@ -1073,6 +1073,12 @@ dependencies = [
"syn 2.0.106",
]
+[[package]]
+name = "data-url"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be1e0bca6c3637f992fc1cc7cbc52a78c1ef6db076dbf1059c4323d6a2048376"
+
[[package]]
name = "der"
version = "0.7.10"
@@ -1351,6 +1357,12 @@ dependencies = [
"syn 2.0.106",
]
+[[package]]
+name = "env_home"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7f84e12ccf0a7ddc17a6c41c93326024c42920d7ee630d04950e6926645c0fe"
+
[[package]]
name = "equivalent"
version = "1.0.2"
@@ -1474,12 +1486,14 @@ dependencies = [
"tauri-build",
"tauri-plugin-cors-fetch",
"tauri-plugin-dialog",
+ "tauri-plugin-http",
"tauri-plugin-opener",
"tauri-plugin-process",
"tauri-plugin-sql",
"tauri-plugin-updater",
"tokio",
"uuid",
+ "which",
]
[[package]]
@@ -5653,6 +5667,30 @@ dependencies = [
"url",
]
+[[package]]
+name = "tauri-plugin-http"
+version = "2.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c00685aceab12643cf024f712ab0448ba8fcadf86f2391d49d2e5aa732aacc70"
+dependencies = [
+ "bytes",
+ "cookie_store",
+ "data-url",
+ "http 1.3.1",
+ "regex",
+ "reqwest 0.12.23",
+ "schemars 0.8.22",
+ "serde",
+ "serde_json",
+ "tauri",
+ "tauri-plugin",
+ "tauri-plugin-fs",
+ "thiserror 2.0.16",
+ "tokio",
+ "url",
+ "urlpattern",
+]
+
[[package]]
name = "tauri-plugin-opener"
version = "2.5.0"
@@ -6746,6 +6784,18 @@ dependencies = [
"windows-core",
]
+[[package]]
+name = "which"
+version = "7.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d643ce3fd3e5b54854602a080f34fb10ab75e0b813ee32d00ca2b44fa74762"
+dependencies = [
+ "either",
+ "env_home",
+ "rustix",
+ "winsafe",
+]
+
[[package]]
name = "whoami"
version = "1.6.1"
@@ -7274,6 +7324,12 @@ dependencies = [
"windows-sys 0.59.0",
]
+[[package]]
+name = "winsafe"
+version = "0.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d135d17ab770252ad95e9a872d365cf3090e3be864a34ab46f48555993efc904"
+
[[package]]
name = "wit-bindgen"
version = "0.46.0"
diff --git a/fincept-terminal-desktop/src-tauri/Cargo.toml b/fincept-terminal-desktop/src-tauri/Cargo.toml
index db09550d9..79cafc618 100644
--- a/fincept-terminal-desktop/src-tauri/Cargo.toml
+++ b/fincept-terminal-desktop/src-tauri/Cargo.toml
@@ -23,6 +23,7 @@ tauri-build = { version = "2", features = [] }
[dependencies]
tauri = { version = "2", features = ["devtools"] }
tauri-plugin-opener = "2"
+tauri-plugin-http = "2"
tauri-plugin-cors-fetch = "4"
tauri-plugin-sql = { version = "2", features = ["sqlite"] }
tauri-plugin-dialog = "2"
@@ -37,3 +38,8 @@ chrono = "0.4"
uuid = { version = "1.11", features = ["v4", "serde"] }
reqwest = { version = "0.11", features = ["json"] }
duckdb = { version = "1.1", features = ["bundled"] }
+which = "7.0"
+
+[target.'cfg(target_os = "windows")'.dependencies]
+[target.'cfg(target_os = "macos")'.dependencies]
+[target.'cfg(target_os = "linux")'.dependencies]
diff --git a/fincept-terminal-desktop/src-tauri/capabilities/default.json b/fincept-terminal-desktop/src-tauri/capabilities/default.json
index 5ce8651dd..5751e7d71 100644
--- a/fincept-terminal-desktop/src-tauri/capabilities/default.json
+++ b/fincept-terminal-desktop/src-tauri/capabilities/default.json
@@ -6,6 +6,15 @@
"permissions": [
"core:default",
"opener:default",
+ "http:default",
+ {
+ "identifier": "http:default",
+ "allow": [
+ { "url": "http://localhost:*" },
+ { "url": "https://*" },
+ { "url": "http://*" }
+ ]
+ },
"cors-fetch:default",
"sql:default",
"sql:allow-load",
diff --git a/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140.dll b/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140.dll
new file mode 100644
index 000000000..1d2ddcb95
--- /dev/null
+++ b/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140.dll
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e2e2bcb916931f0ee6d0a567212511244e7442da574757c331c1b91087f2a0f
+size 557136
diff --git a/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140_1.dll b/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140_1.dll
new file mode 100644
index 000000000..605907b0e
--- /dev/null
+++ b/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140_1.dll
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c5ffd092ad78cbdde657e767af94eb2e83e4736c7558282e3571c9ccad85ca29
+size 35920
diff --git a/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140_2.dll b/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140_2.dll
new file mode 100644
index 000000000..7fb9c88c1
--- /dev/null
+++ b/fincept-terminal-desktop/src-tauri/resources/python-windows/msvcp140_2.dll
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:14e6ad91a01d7775410f668c60b15dd4fba1f60f33943c268b27d6250a03502c
+size 279656
diff --git a/fincept-terminal-desktop/src-tauri/resources/python-windows/python312._pth b/fincept-terminal-desktop/src-tauri/resources/python-windows/python312._pth
index 41c475a77..837f51ab2 100644
--- a/fincept-terminal-desktop/src-tauri/resources/python-windows/python312._pth
+++ b/fincept-terminal-desktop/src-tauri/resources/python-windows/python312._pth
@@ -1,5 +1,3 @@
-python312.zip
-.
-
-# Uncomment to run site.main() automatically
-import site
+version https://git-lfs.github.com/spec/v1
+oid sha256:73d752deb280f560d4a94842968a1a8f06445c88b4f49f9517a654e3b895f079
+size 103
diff --git a/fincept-terminal-desktop/src-tauri/resources/python-windows/vcruntime140.dll b/fincept-terminal-desktop/src-tauri/resources/python-windows/vcruntime140.dll
new file mode 100644
index 000000000..2f5079664
--- /dev/null
+++ b/fincept-terminal-desktop/src-tauri/resources/python-windows/vcruntime140.dll
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:60b813f8b87ff4fa344f081c163c1a2234b5e3e41f748721c28fbdecbcfecb8a
+size 124520
diff --git a/fincept-terminal-desktop/src-tauri/resources/python-windows/vcruntime140_1.dll b/fincept-terminal-desktop/src-tauri/resources/python-windows/vcruntime140_1.dll
new file mode 100644
index 000000000..bb3fb321f
--- /dev/null
+++ b/fincept-terminal-desktop/src-tauri/resources/python-windows/vcruntime140_1.dll
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e30b3f4979b63b50438d061858c9cde962f4494e585c627a11c98b6c5b7b2592
+size 49792
diff --git a/fincept-terminal-desktop/src-tauri/src/data_sources/yfinance.rs b/fincept-terminal-desktop/src-tauri/src/data_sources/yfinance.rs
index c2bd327b4..fe53fc90a 100644
--- a/fincept-terminal-desktop/src-tauri/src/data_sources/yfinance.rs
+++ b/fincept-terminal-desktop/src-tauri/src/data_sources/yfinance.rs
@@ -63,8 +63,8 @@ impl YFinanceProvider {
pub async fn get_quote(&self, symbol: &str) -> Option<QuoteData> {
match self.fetch_quote(symbol).await {
Ok(quote) => Some(quote),
- Err(_e) => {
- // Silent fail for production
+ Err(e) => {
+ eprintln!("[YFinance] Failed to fetch quote for {}: {}", symbol, e);
None
}
}
@@ -75,7 +75,10 @@ impl YFinanceProvider {
pub async fn get_quotes(&self, symbols: Vec<String>) -> Vec<QuoteData> {
match self.fetch_batch_quotes(symbols).await {
Ok(quotes) => quotes,
- Err(_) => Vec::new(),
+ Err(e) => {
+ eprintln!("[YFinance] Batch fetch failed: {}", e);
+ Vec::new()
+ },
}
}
diff --git a/fincept-terminal-desktop/src-tauri/src/lib.rs b/fincept-terminal-desktop/src-tauri/src/lib.rs
index 67c7f3088..cdf691746 100644
--- a/fincept-terminal-desktop/src-tauri/src/lib.rs
+++ b/fincept-terminal-desktop/src-tauri/src/lib.rs
@@ -383,6 +383,7 @@ pub fn run() {
tauri::Builder::default()
.plugin(tauri_plugin_opener::init())
+ .plugin(tauri_plugin_http::init())
.plugin(tauri_plugin_cors_fetch::init())
.plugin(tauri_plugin_sql::Builder::default().build())
.plugin(tauri_plugin_dialog::init())
diff --git a/fincept-terminal-desktop/src-tauri/src/utils/python.rs b/fincept-terminal-desktop/src-tauri/src/utils/python.rs
index 385b2e00a..dd94498bc 100644
--- a/fincept-terminal-desktop/src-tauri/src/utils/python.rs
+++ b/fincept-terminal-desktop/src-tauri/src/utils/python.rs
@@ -13,37 +13,121 @@ const CREATE_NO_WINDOW: u32 = 0x08000000;
/// Get the Python executable path at runtime
pub fn get_python_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
- let resource_dir = app
- .path()
- .resource_dir()
- .map_err(|e| format!("Failed to get resource directory: {}", e))?;
+ use std::process::Command;
- // Determine platform-specific directory and executable name
- let (python_dir, python_exe) = if cfg!(target_os = "windows") {
- ("python-windows", "python.exe")
- } else if cfg!(target_os = "macos") {
- ("python-macos", "python3")
- } else {
- ("python-linux", "python3")
- };
+ // Strategy for all platforms:
+ // 1. Try bundled Python first (ensures consistency)
+ // 2. Fall back to system Python (for compatibility)
+ // This ensures users don't need to install Python separately
- let python_path = resource_dir
- .join("resources")
- .join(python_dir)
- .join("python")
- .join("bin")
- .join(python_exe);
+ #[cfg(target_os = "windows")]
+ {
+ // Try bundled Python first on Windows
+ let resource_dir = app
+ .path()
+ .resource_dir()
+ .map_err(|e| format!("Failed to get resource directory: {}", e))?;
- // Verify Python exists
- if !python_path.exists() {
- return Err(format!(
- "Python executable not found at: {}. Resource dir: {}",
- python_path.display(),
- resource_dir.display()
- ));
+ let bundled_python = resource_dir
+ .join("python-windows")
+ .join("python.exe");
+
+ if bundled_python.exists() {
+ return Ok(bundled_python);
+ }
+
+ // Fallback to system Python
+ if let Ok(output) = Command::new("python").arg("--version").output() {
+ if output.status.success() {
+ if let Ok(python_path) = which::which("python") {
+ return Ok(python_path);
+ }
+ }
+ }
+
+ return Err("Python not found. Please install Python 3.x from python.org".to_string());
+ }
+
+ #[cfg(target_os = "macos")]
+ {
+ // Try bundled Python first on macOS
+ let resource_dir = app
+ .path()
+ .resource_dir()
+ .map_err(|e| format!("Failed to get resource directory: {}", e))?;
+
+ let bundled_python = resource_dir
+ .join("python-macos")
+ .join("bin")
+ .join("python3");
+
+ if bundled_python.exists() {
+ return Ok(bundled_python);
+ }
+
+ // Fallback to system python3
+ if let Ok(output) = Command::new("python3").arg("--version").output() {
+ if output.status.success() {
+ if let Ok(python_path) = which::which("python3") {
+ return Ok(python_path);
+ }
+ }
+ }
+
+ // Try python as last resort
+ if let Ok(output) = Command::new("python").arg("--version").output() {
+ if output.status.success() {
+ if let Ok(python_path) = which::which("python") {
+ return Ok(python_path);
+ }
+ }
+ }
+
+ return Err("Python not found. Please install Python 3.x:\n brew install python3".to_string());
}
- Ok(python_path)
+ #[cfg(target_os = "linux")]
+ {
+ // Try bundled Python first on Linux
+ let resource_dir = app
+ .path()
+ .resource_dir()
+ .map_err(|e| format!("Failed to get resource directory: {}", e))?;
+
+ let bundled_python = resource_dir
+ .join("python-linux")
+ .join("bin")
+ .join("python3");
+
+ if bundled_python.exists() {
+ return Ok(bundled_python);
+ }
+
+ // Fallback to system python3
+ if let Ok(output) = Command::new("python3").arg("--version").output() {
+ if output.status.success() {
+ if let Ok(python_path) = which::which("python3") {
+ return Ok(python_path);
+ }
+ }
+ }
+
+ // Try python as last resort
+ if let Ok(output) = Command::new("python").arg("--version").output() {
+ if output.status.success() {
+ if let Ok(python_path) = which::which("python") {
+ return Ok(python_path);
+ }
+ }
+ }
+
+ return Err("Python not found. Please install Python 3.x:\n sudo apt install python3 python3-pip\n OR\n sudo yum install python3 python3-pip".to_string());
+ }
+
+ #[cfg(not(any(target_os = "windows", target_os = "macos", target_os = "linux")))]
+ {
+ Err("Unsupported operating system".to_string())
+ }
}
/// Get the bundled Bun executable path at runtime
@@ -63,7 +147,6 @@ pub fn get_bundled_bun_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
};
let bun_path = resource_dir
- .join("resources")
.join(bun_dir)
.join(bun_exe);
@@ -76,16 +159,53 @@ pub fn get_bundled_bun_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
}
/// Get a Python script path at runtime
+/// Works in dev mode, production builds, and CI/CD pipelines
pub fn get_script_path(app: &tauri::AppHandle, script_name: &str) -> Result<PathBuf, String> {
- let resource_dir = app
- .path()
- .resource_dir()
- .map_err(|e| format!("Failed to get resource directory: {}", e))?;
+ // Strategy: Try multiple paths in order until we find the script
+
+ let mut candidate_paths = Vec::new();
+
+ // 1. Try Tauri's resource_dir (works in production and should work in dev)
+ if let Ok(resource_dir) = app.path().resource_dir() {
+ candidate_paths.push(resource_dir.join("scripts").join(script_name));
+ }
+
+ // 2. Try relative to current executable (production fallback)
+ if let Ok(exe_path) = std::env::current_exe() {
+ if let Some(exe_dir) = exe_path.parent() {
+ candidate_paths.push(exe_dir.join("resources").join("scripts").join(script_name));
+ candidate_paths.push(exe_dir.join("scripts").join(script_name));
+ }
+ }
+
+ // 3. Try relative to current working directory (dev mode)
+ if let Ok(cwd) = std::env::current_dir() {
+ // If CWD is src-tauri
+ candidate_paths.push(cwd.join("resources").join("scripts").join(script_name));
+ // If CWD is project root
+ candidate_paths.push(cwd.join("src-tauri").join("resources").join("scripts").join(script_name));
+ }
+
+ // Try each candidate path
+ for path in candidate_paths.iter() {
+ if path.exists() {
+ // Strip the \\?\ prefix that Python can't handle on Windows
+ let path_str = path.to_string_lossy().to_string();
+ let clean_path = if path_str.starts_with(r"\\?\") {
+ PathBuf::from(&path_str[4..])
+ } else {
+ path.clone()
+ };
+
+ return Ok(clean_path);
+ }
+ }
- Ok(resource_dir
- .join("resources")
- .join("scripts")
- .join(script_name))
+ Err(format!(
+ "Script '{}' not found in any of {} candidate locations",
+ script_name,
+ candidate_paths.len()
+ ))
}
/// Create a Command that hides console windows on Windows