🤖 StockPal AI Architecture

Here is a complete breakdown of the highly-resilient AI architecture we built for StockPal.

How the "Waterfall" System Works (The Double-Loop)

Instead of relying on just one AI model and one API key, the system uses a matrix loop. Every time you trigger an AI feature, the system:

1. Starts with Model #1.
2. Tries it with API Key 1. If it hits a rate-limit, it immediately retries with API Key 2, then Key 3, etc. (up to 4-6 keys depending on the feature).
3. If Model #1 is completely down or exhausted across all keys, it seamlessly falls over to Model #2 and repeats the key-loop.
4. It does this instantly in milliseconds in the background. It will make up to 48 total attempts before ever failing.

Because different tasks require different capabilities, the system uses two distinct waterfalls:

1. The Core 8-Model Waterfall (Text & Analysis)

This is the workhorse of the application. It uses a strict priority list of the smartest free text/reasoning models currently available on OpenRouter.

The Priority Sequence:

1. Qwen3 Coder 480B (Primary focus: massive 1M context, best-in-class reasoning)
2. NVIDIA Nemotron 3 Ultra (High quality, 1M context)
3. Tencent Hy3 (Extremely generous token quotas)
4. NVIDIA Nemotron 3 Super (Very fast, reliable)
5. Poolside Laguna M.1 (Great coding/logic capabilities)
6. Llama 3.3 70B Instruct (Proven, highly reliable workhorse)
7. OpenAI GPT-OSS 20B (OpenAI architecture)
8. openrouter/free (Final safety net: automatically picks whatever free model is currently least congested)

Features Using This Waterfall:

• The Main Chat Assistant: General queries, price checks, and financial questions.
• Market Screener AI: When you click "Analyze AI" next to a stock you just found in the screener.
• Due Diligence Reports: The structured deep-dive reports (Overview, Financials, Sentiment, Recommendation).
• Sentiment Analysis: Reading recent news headlines and determining if the market is bullish or bearish on a ticker.
• Peer Comparisons: Creating the comparison matrix between competitors (like MSFT vs AAPL).
• Text/PDF Portfolio Imports: Reading uploaded brokerage statements or raw CSV text.

2. The Vision 4-Model Waterfall (Image Processing)

Most AI models cannot physically "see" images. If you try to send them a picture, they crash. To solve this, StockPal uses a secondary waterfall exclusively composed of Vision-Language Models (VLMs).

The Priority Sequence:

1. NVIDIA Nemotron Nano 12B VL (Excellent image processing, 128K context)
2. Qwen 2.5 VL 72B Instruct (Massive 72B vision model, incredible at reading small text/OCR)
3. Llama 3.2 11B Vision (Meta's leading free vision model)
4. NVIDIA Nemotron Nano 9B V2 (Smaller, fast fallback model)

Features Using This Waterfall:

• Image Portfolio Imports: When you upload a screenshot or PNG/JPG of your brokerage account, the backend detects the file type and automatically routes the request through this Vision Waterfall so the AI can physically "read" the numbers off the screenshot.

Summary

By splitting the models this way, 100% of your application runs entirely on free models. The text features get the smartest logic models in existence (like Qwen 480B), and the image features get specialized Vision models—all protected by multiple layers of backup API keys so it almost never goes offline.

💬 Assistant Chat

The Assistant Chat is StockPal's central interactive window. It supports conversational market research, stock searches, portfolio optimization commands, and direct alert creation.

How it Works & Data Flow

1. Chat Persistence: All messages are saved to the history table in Supabase (containing session_id, role, content, and created_at timestamp), maintaining conversation states across sessions.
2. Intent Categorization: If a query contains recommendation-related keywords (buy, sell, hold, predict, target, gain, ROI, picks), the query and generated responses are saved to the analyses table.
3. Verbal Reminder Setup: The client evaluates message text via regex matches for scheduling intents (e.g., matching "remind me to check..." or "alert me when..."). If matched, it automatically parses the requested time/price threshold and writes a new alert directly to the reminders database.
4. Dialogue Memory: Passes the last 14 messages (7 user-assistant turns) into the completion request to provide immediate contextual memory.

💼 Portfolio Dashboard

The Portfolio Dashboard manages your active equity holdings, showing real-time net returns, cash balances, and visual asset allocations.

Dashboard Operations & Document Scanning

• CRUD Operations: Directly reads, writes, and prunes from the portfolio table in Supabase via GET /api/portfolio, POST /api/portfolio, and DELETE /api/portfolio endpoints.
• Live Asset Aggregation: Computes Total Value, Cash Balance, Net ROI, and Day's Return by calling Yahoo Finance API (quotes cached for 30s in the Supabase table cached_prices to mitigate API rate limits).
• Vision Brokerage Statement Importer: Accepts screenshots or PDF statement photos at POST /api/portfolio/import. The server executes a vision fallback sequence to read statement layouts, returning structural JSON mapping tickers, purchase cost bases, and share counts.
• Collision Check: If an imported or added ticker already exists in the portfolio table, the system skips inserting it and delivers a notification: "The stock was not added because it is already in the portfolio. You can edit the stock directly in the portfolio."
• Multi-Currency Normalization: Tracks international equities in their native purchase currencies (USD, EUR, NIS) and utilizes a highly-available CDN exchange rate API (fawazahmed0/exchange-api) to dynamically normalize all Total Value, Cost Basis, and Net Return calculations into USD on the fly. This ensures accurate global portfolio math without losing original trade cost basis data.

Analyst Consensus Algorithm ("Platform-as-a-Voter" System)

To prevent severe double-counting of Wall Street analysts across different data providers (e.g., if Finnhub and FMP both report the exact same 61 analysts), the backend engine uses a weighted hybrid counting architecture:

• The Wall Street Core (FMP): Serves as the absolute "ground truth" for human Wall Street Analyst counts. If FMP reports that 61 individual analysts rate a stock as "Buy", the system literally increments the Buy counter by 61.
• Platform-as-a-Voter Tie-Breakers: For all other integrated API sources, the system does not pull their raw numbers. Instead, it measures their master consensus and treats the entire platform as a single algorithmic voter (+1 vote).
• TradingView: +1 Vote based on their Recommend.All technical momentum oscillator aggregation.
• Alpha Vantage: +1 Vote based on AI-driven News Sentiment analysis.
• Finnhub & Yahoo Finance: +1 Vote each based on their respective internal consensus keys.

Target Price Calculation ("Average of Averages")

Unlike momentum-based Technical Analysis engines (like TradingView), mathematical algorithms cannot predict a 12-month corporate dollar-value target. Therefore, the system enforces a strict Average of Averages methodology across four massive institutional databases to compute the final Target Price.

• The Four Pillars: The backend simultaneously polls Finnhub, Financial Modeling Prep (FMP), Alpha Vantage, and Yahoo Finance to retrieve their respective Mean Target Prices (which they internally calculate from Wall Street institutional analysts).
• Cross-Referenced Smoothing: By taking the final average of these four major averages, the architecture instantly neutralizes outliers. If one source has stale data, the other three active databases seamlessly pull the final math back to the true market consensus.
• Technical Exclusion: TradingView's signal API is intentionally omitted from this specific calculation because it measures technical momentum (e.g., RSI/MACD), not forward-looking financial forecasting.

🔎 Market Screener

The Market Screener is a proactive discovery tool that directly interfaces with TradingView's backend scanner API to filter thousands of US equities in real-time.

Technical Filters

• Signal: The master consensus signal aggregating over 20 Moving Averages and Oscillators. We intercept TradingView's Recommend.All scale (-1 to 1) to classify assets into Strong Buy, Buy, Sell, and Strong Sell.
• RSI (14): The 14-day Relative Strength Index. We scan for mathematically Oversold (< 30) or Overbought (> 70) momentum conditions.
• MACD: Moving Average Convergence Divergence. We intercept the MACD.macd and MACD.signal columns to detect Bullish or Bearish momentum crossovers.
• Sector: Broad categorization filtering (e.g. Finance, Technology Services).

Results Table Metrics

• Ticker: The official market symbol.
• Price: Real-time current USD trading price.
• Change: The percentage price movement since the previous day's market close.
• Market Cap: The total valuation of the company's outstanding shares.
• Signal: The simplified master technical rating (Buy/Sell/Hold).
• Sector: The industrial classification of the company.
• Actions: Instantly invoke the AI Assistant for deep due diligence (Analyze AI) or query the official SEC EDGAR database for Form 4 executive filings (🕵️‍♂️ Insiders).

📊 Junior Analyst Research Desk

The Junior Analyst Research Desk functions as an interactive financial analyst, compiling company overview profiles, valuation multiples, news, and sentiment into an active research report.

Workflow & Portfolio-Aware Dialogue

1. Data Gathering: Fetches key metrics (Alpha Vantage OVERVIEW), headlines (Marketaux), news sentiment indicators (Alpha Vantage NEWS_SENTIMENT), and quotes (Yahoo Finance /api/price).
2. Report Archiving: Compiles a complete JSON snapshot of these profiles, ratios, and news items, saving the history log in the research_reports table under tool_type = 'junior_analyst'.
3. Contextual AI Interrogation: Launches a localized chatbot. The chatbot uses a custom system prompt that digests the corporate profile, ratios, news highlights, and **CRITICAL USER PORTFOLIO CONTEXT** (current shares held in the portfolio table, purchase cost basis, ROI). This lets the user ask tailored questions like: "Should I sell my shares at my current cost basis given these news catalysts?"

📜 Sold History Archive

The Sold History Archive keeps a persistent record of all closed equity positions, letting you track realized performance metrics and opportunity costs.

Gains Tracking & Opportunity Cost Analysis

• Ledger Tracking: Reads, inserts, and removes historical transactions from the sold_history table in Supabase via GET /api/sold, POST /api/sold, and DELETE /api/sold.
• Realized Returns Calculations: Summarizes the exact dollar gain/loss and percentage return based on historic purchase price and sale price.
• Opportunity Cost Checker: Fetches live stock quotes from Yahoo Finance API for every sold symbol, displaying current price directly next to the price you sold it at. This helps you evaluate if you exited at the peak or left profit on the table.

🔔 Alerts & Reminders Hub

The Alerts & Reminders Hub lets you set specific price targets and triggers, notifying you when market moves cross your thresholds.

Alert Execution & Dispatching

1. Trigger Settings: Create a reminder by specifying ticker, condition (Price Goes Above or Price Goes Below), and a target value.
2. Database Sync: Saves and manages alerts in the reminders table in Supabase via GET /api/reminders, POST /api/reminders, and DELETE /api/reminders.
3. Live Tracking: The system continuously compares active triggers against Yahoo Finance live prices.
4. Trigger Event: When a stock breaches your threshold, the system flags the reminder, updates the alert's active status, and triggers browser notifications.
5. SMTP Email Dispatching: SMTP dispatches require setting up your Gmail credentials in the Settings panel first. Test emails are sent via nodemailer, and actual triggers print log notifications.

📜 Chat History Archive

The Chat History Archive manages StockPal's dialogue database, letting you browse previous analyses and resume threads.

Memory & Continuity Pipeline

• Thread Fetching: Pulls historical conversations from the history table in Supabase via GET /api/history.
• Auto-titling: When a new chat begins, the system prompts the primary LLM with your opening question to generate a short, descriptive title (e.g. "NVDA Growth Outlook") for the sidebar list.
• Thread Selection: The left panel shows saved logs grouped chronologically. Clicking an item retrieves full dialogue details.
• Continuity: Clicking the "Continue Chat" button sets the thread's active ID in the main chat room, loading previous context back into the conversation view to let you ask follow-up questions.

⚙️ Settings Panel

The Settings Panel allows users to configure the application's email notification credentials. It is used to test alert integrations.

Email Notification Alert Credentials

This panel is dedicated exclusively to managing your alert email dispatch settings:

• SENDER GMAIL ADDRESS (EMAIL_USER): Configures the Gmail address used to dispatch notifications.
• GMAIL APP PASSWORD (EMAIL_PASS): Stores the secure 16-character Google App Password (not the raw account password) to authenticate with Gmail SMTP servers.
• RECIPIENT EMAIL ADDRESS (EMAIL_TO): Sets the target inbox to receive market price alerts.
• Test Email Alert Dispatcher: Sends a live connection test email using Nodemailer SMTP, showing detailed errors in case of connection failure.

📑 Due Diligence Report

The Due Diligence Report compiles comprehensive fundamental analysis and recent news cycles into a structured markdown research briefing on any ticker.

Data Compilation & Report Synthesis

1. Metrics Gathering: Pulls company details (Alpha Vantage OVERVIEW), recent stories (Marketaux), and news sentiment score metrics (Alpha Vantage NEWS_SENTIMENT).
2. AI Context Preparation: Packages sector, industry, multiples (P/E, PEG, Price/Book), returns (ROE, margins), Wall Street consensus targets, 52-week ranges, and news/sentiment lists into a prompt.
3. LLM Report Writing: Prompts the fallback AI list to generate a structured briefing detailing: 1. Executive Summary (TL;DR), 2. Valuation & Fundamentals, 3. Recent Catalysts & News, 4. Bull vs Bear Case, and 5. Final Verdict (BUY/HOLD/SELL signal, price target, and timeline).
4. Database Archiving: Saves reports in the research_reports table in Supabase under tool_type = 'due_diligence', allowing instant lookups from history.

🤼 Peer Comparison Battle

The Peer Comparison Battle evaluates two competing companies side-by-side (e.g. AMD vs NVDA) to determine the stronger investment.

Side-by-Side Analysis Workflow

• Parallel Fetching: Pulls company details (P/E, PEG, Price/Book, ROE, margins, dividend yields) for both tickers from Alpha Vantage.
• UI Comparison Grid: Renders ratios side-by-side, dynamically coloring the stronger metric in green to highlight efficiency leaders.
• LLM Battle Summary: Prompts the LLM chain to analyze both profiles and draft a side-by-side battle report, declaring category winners (Valuation, Growth, and Efficiency) and a final investment verdict.
• Report Caching: Saves the report in the research_reports table in Supabase under tool_type = 'peer_compare' and ticker formatted as SYMBOL1_vs_SYMBOL2.

🚦 Sentiment Gauge

The Sentiment Gauge scans current financial news articles to score the overall market sentiment for a stock and interpret market momentum.

News Analysis & Sentiment Scoring

1. News Retrieval: Fetches articles matching the ticker from Alpha Vantage NEWS_SENTIMENT (via /api/research/sentiment/${ticker}).
2. Score Aggregation: Extracts sentiment scores for each headline (scaled from -1.0 to 1.0) and computes the average score.
3. Meter Visualization: Maps the average score to a 0-100 gauge (Bearish, Neutral, Bullish) in the UI.
4. LLM Narrative Synthesis: Prompts the LLM with the score and top headlines to explain if the current market mood represents an investable trend or a speculative trap.
5. Database Sync: Saves the report in the research_reports table in Supabase (tool_type = 'sentiment').

🔮 Earnings Summarizer

The Earnings Summarizer parses earnings releases and guidance figures, identifying quarterly beats/misses and annual profitability trends.

Summarization Workflow

• EPS Acquisition: Fetches quarterly reported and estimated EPS numbers, along with annual totals, from Alpha Vantage EARNINGS (via /api/research/earnings/${ticker}).
• Earnings Trends: Summarizes EPS performance metrics from the most recent quarters.
• LLM EPS Analysis: Feeds EPS figures into the LLM to write a trajectory summary, identifying if the corporation is a "consistent beater" and explaining the growth outlook.
• Database Sync: Saves reports in the research_reports table in Supabase under tool_type = 'earnings'.

🕵️‍♂️ Insider Shadow

The Insider Shadow monitors corporate insider transactions (Form 4), letting you trace executive trades directly from official SEC filings.

SEC EDGAR Insider Tracking

1. CIK Retrieval: Backend fetches the stock's SEC Central Index Key (CIK) from Alpha Vantage's overview endpoint.
2. SEC Submission Fetch: Pads CIK to 10 digits and queries the official SEC EDGAR Submissions API (submissions/CIK[padded].json) using a custom user-agent header.
3. Form 4 Extraction: Filters filings to isolate the last 10 Form 4 (Beneficial Ownership Changes) transactions.
4. Link Generation: Displays direct links to the official filings on SEC archives (https://www.sec.gov/Archives/edgar/data/...).
5. LLM Narrative Audit: Feeds transaction frequencies and details to the LLM to write a summary analysis, checking for cluster trades.
6. Database Sync: Saves reports in the research_reports table in Supabase under tool_type = 'insider'.

🤖 Proactive Agent

The Proactive Agent acts as a background monitor, checking your holdings and watchlist items against market updates.

Autonomous Portfolio Analysis

• Holdings Scan: Reads all active assets from the portfolio table (including current price and ROI).
• Sentiment Evaluation: Fetches news sentiment indicators (Alpha Vantage NEWS_SENTIMENT) for the top 5 assets.
• LLM Risk-Reward Check: The LLM acts as an autonomous Portfolio Manager, scanning the assets to identify the single biggest risk and opportunity, generating a "Daily Briefing" markdown report.
• Database Sync: Saves reports in the research_reports table in Supabase under tool_type = 'proactive' and ticker PORTFOLIO.

⚡ Watchlist Trades and Analysis

The Watchlist Trades section is a powerful quantitative screener tailored for active swing traders. It scans your custom watchlist of US and IL stocks to evaluate technical momentum and automatically detect trade entry/exit opportunities.

Algorithmic Logic

The underlying engine performs real-time technical analysis on daily chart data. It requires three conditions to simultaneously align to trigger a BUY signal:

• Trend (EMA 200): The current price must be above the 200-day Exponential Moving Average (long-term uptrend).
• MACD Crossover: The MACD line must cross UP over its signal line (bullish momentum shift).
• RSI (Relative Strength Index): The RSI must be actively rising AND above the 50 baseline.

Conversely, a SELL signal triggers when the Trend is a downturn, MACD crosses DOWN, and RSI is actively falling below 50.

Features Include

• Automated Scan Engine: Click "Run Scan Now" to fetch live data for all tickers, parse technicals, and evaluate conditions.
• Ticker Details Side Sheet: Detailed breakdown for individual stocks showing a "Checklist Summary" of the current signals.
• Live TradingView Charts: Seamlessly embeds a TradingView widget to let you visually confirm the automated signals.

📦 Platform & Version Info