-
Notifications
You must be signed in to change notification settings - Fork 0
Home
StockSense is a full-stack web application for tracking Indian and global equity markets with AI-powered price forecasting, autonomous data agents, and end-to-end portfolio management. It covers NSE/BSE (Indian exchanges) and NASDAQ, and is designed for retail investors and hobbyist quants who want a self-hosted alternative to premium terminal software.
The core value proposition: you get machine-learning price predictions (Prophet + Gradient Boosting ensemble), real-time news sentiment, portfolio P&L with FIFO cost basis, and strategy backtesting — all running locally or on GCP Cloud Run, with no per-seat SaaS fees.
Live and historical OHLCV quotes for NSE, BSE, and NASDAQ symbols via yfinance. Prices are cached (15-minute TTL for quotes, 1-hour for predictions) to avoid hammering the data source. The watchlist lets you pin symbols and see them in one place.
A blended Prophet + GradientBoostingRegressor model trains on 32+ features per symbol — candlestick patterns, technical indicators (RSI, MACD, Bollinger Bands, Ichimoku, and more), news sentiment rolling averages, macro inputs (USD/INR, crude, gold, VIX), and index returns. Predictions include a confidence tier (high/medium/low) based on out-of-sample MAPE.
Polls six RSS feeds every 15 minutes during market hours: Economic Times, Moneycontrol, Business Standard, Google News, Reuters, and Bloomberg. VADER sentiment (with a finance-specific lexicon extension) scores each article. Articles are deduplicated by MD5 hash before storage, and 7-day and 30-day rolling sentiment averages are computed per symbol.
Track holdings with FIFO cost basis. See realized and unrealized P&L broken out by position. The tax report classifies capital gains as short-term or long-term under Indian tax rules and flags tax-loss harvesting opportunities.
Define signal conditions (e.g. RSI crossover, MACD divergence) and run a backtest against historical price data. Review equity curve, drawdown, Sharpe ratio, and trade log.
Filter the universe of tracked symbols by fundamental and technical criteria: P/E ratio, dividend yield, momentum, RSI level, moving average regime.
Side-by-side comparison of up to N symbols: normalized price performance, key metrics, and correlation.
Beta and Value-at-Risk (VaR) calculations for your portfolio.
Upcoming earnings dates for watched symbols.
World Bank macro data (GDP growth, inflation, etc.) surfaced alongside price charts.
Dividends, splits, and bonus shares — with automatic cost-basis adjustment for holdings.
Analyze overlapping holdings across mutual fund schemes.
Price and indicator-based alerts. Triggered alerts are surfaced in the UI.
User management, system status, and manual trigger of background tasks. Accessible to admin-role users only.
These are Claude agent definitions stored in .claude/agents/. They run on schedules and interact with the same database the API uses.
| Agent | Schedule | What it does |
|---|---|---|
| data-fetcher | Every 15 min, 09:15–15:30 IST | Fetches OHLCV quotes for all watched symbols, normalizes, and upserts to the StockPrice table |
| ml-predictor | Weekly or on-demand | Retrains Prophet+GBM models per symbol, saves .joblib to disk and GCS |
| news-analyst | Every 15 min | Polls 6 RSS feeds, runs VADER sentiment, deduplicates by MD5, stores NewsArticle records |
| portfolio-advisor | On-demand | Scores each holding using prediction confidence + sentiment + technical signals, outputs buy/hold/sell/watch recommendation |
- Retail investors who want self-hosted market intelligence without a Bloomberg subscription
- Python/React developers learning how to build a real ML-backed financial application
- Quants who want a starting point to plug in their own signals and backtest ideas
- Teams evaluating GCP Cloud Run + Terraform for deploying ML-dependent Python services
| Page | What it covers |
|---|---|
| Architecture | System diagram, API modules, data flow, middleware, caching, database trade-offs |
| ML Prediction Pipeline | All 32 features, ensemble blending, confidence tiers, serialization, auto-retrain |
| Agent System | The four Claude agents, schedules, outputs, VADER scoring, portfolio advisor |
| Setup and Installation | Prerequisites, three install methods, Alembic, .env, first-run issues |
| Configuration | Every environment variable with type, default, and effect |
| API Reference | All 50+ endpoints grouped by module with params and response shapes |
| Frontend | 18 pages, Zustand stores, TanStack Query setup, charting libraries, axios interceptors |
| Portfolio and Tax | FIFO cost basis, P&L, capital gains classification, tax-loss harvesting, corporate actions |
| Deployment | GCP Cloud Run, Terraform, SQLite-on-Cloud-Run, GitHub Actions CI/CD, rollback |