Technical and fundamental scans, market breadth, group rankings, theme discovery and AI-assisted research
Scan and track US, Hong Kong, India, Japan, Korea, Taiwan, mainland China A-shares, Germany, Canada, Singapore, Malaysia, and Australia markets.
Daily Snapshot → Scans → Stock chart and details → Breadth → Group Rankings
Read-only daily snapshot running on GitHub Pages: xang1234.github.io/stock-screener
Updated daily after market close.
See the Static Site Guide for exactly what works in static mode.
- 12-market coverage - exchange calendars, independent data and scans.
- Multiple screening methodologies - Minervini, CANSLIM, IPO, Volume Breakthrough, etc. with composite scoring.
- Market Health and Exposure - Market-regime overlay for position sizing and risk posture.
- Market Breadth - StockBee-style daily movers and trend windows, advance/decline and new-high/new-low health bars, T2108, a benchmark overlay, and a significance heatmap built from one shared calculation layer.
- Industry groups with Relative Rotation Graph - groups ranked by relative strength with movers (1W/1M/3M/6M) and constituent analysis, plus RRG charts plotting RS-Ratio vs RS-Momentum through (Leading → Weakening → Lagging → Improving). The Matrix tab adds Grid and Clusters layouts colored by 1-day, 1-week, 1-month change, or Stock RS.
- Watchlists and Themes - RS and price sparklines, multi-period change bars, drag-and-drop folders, and full-screen chart navigation.
- Theme discovery - AI theme identification from RSS, Twitter/X, and news feeds; tracks trending vs. emerging themes and alerts on momentum shifts.
- AI research chatbot - LLM powered chatbot with optional web search and persistent conversation history.
- Operations - startup data bootstrap, runtime status, and Operations console for queues/jobs/telemetry.
- Options Command Center - opt-in US-only options context for the current top Candidates and Leaders, with focused gamma, volatility, skew, and activity views plus ticker history.
- Backtest - Backtest page that validates published scan picks and theme alerts against price history.
Market Health and Exposure
Scan results table
Group RS: industry rankings, relative-strength statistics, and changes in group rank
RRG: sector rotation with direction-arrowed weekly tails; full 197-group scope available from the same view
Matrix Grid: sector and IBD industry rows, market-cap columns, and individual stock tiles
Matrix Clusters: market-cap-sized bubbles with green centers and red perimeters. Both layouts support 1-day, 1-week, 1-month change, and Stock RS in the live app and static site. See the Group Matrix Guide.
Market Breadth combines advance/decline and new-high/new-low health bars with an SPY overlay and a color-coded history table for primary, secondary, and context indicators.
Options Command Center: switch between Gamma, Volatility, Skew, and Activity views without scanning an entire option universe. See the Options Command Center Guide.
Typical flow: sign in → bootstrap markets → review the Daily dashboard → run a Scan → drill into a stock → monitor Operations → validate outcomes on Backtest. For the full page-by-page tour, see the Live App Guide.
Deploys tagged GHCR images instead of building locally:
cp .env.docker.example .env.docker
# Edit .env.docker:
# BACKEND_IMAGE=ghcr.io/<owner>/stockscreenclaude-backend
# FRONTEND_IMAGE=ghcr.io/<owner>/stockscreenclaude-frontend
# APP_IMAGE_TAG=v1.3.0
# SERVER_AUTH_PASSWORD=choose-a-long-random-password
# GROQ_API_KEY=...
ENABLED_MARKETS=US,HK,CN scripts/docker-compose-enabled-markets.sh --env-file .env.docker -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.release.yml pull
ENABLED_MARKETS=US,HK,CN scripts/docker-compose-enabled-markets.sh --env-file .env.docker -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.release.yml up -d --no-build
# Open http://localhostOn first launch the app opens to a first-run bootstrap screen — no pre-seeded database needed. Pick one primary market for startup defaults and optionally enable more to hydrate in the background, then start. Enabling many markets at once noticeably slows the first run, so start with one and add the rest after the workspace is ready.
- Homelab / VPS / local-dev compose / GHCR options: Docker Deployment
- Building from source: Development Guide
- Bootstrap stages, stale/failure handling, re-runs: Operations Guide
Scanning and all core features work with no API keys. The AI chatbot requires at least one LLM provider key.
| Provider | Env Var | Free Tier | Notes |
|---|---|---|---|
| Groq | GROQ_API_KEY |
Yes | Default for chatbot and research |
| Gemini | GEMINI_API_KEY |
Yes | Extraction fallback |
| Minimax | MINIMAX_API_KEY |
No | Primary theme-extraction provider |
| Z.AI | ZAI_API_KEY |
No | Optional alternate provider |
Optional web-search keys (TAVILY_API_KEY, SERPER_API_KEY) enable the chatbot's research mode. Full reference: Environment Variables.
| Route | Page | Description |
|---|---|---|
/ |
Daily | Dashboard: Daily Snapshot, Key Markets, Themes, Watchlists, Stockbee MM |
/scan |
Bulk Scanner | Multi-market scanning with 80+ filters, per-market badges, CSV export |
/breadth |
Market Breadth | StockBee-style breadth indicators and trends |
/groups |
Group Rankings | IBD industry group rankings, movers, RRG, and stock Matrix (Grid/Clusters) |
/validation |
Backtest | Deterministic validation of scan picks and theme alerts |
/themes |
Themes | Feature-gated AI theme discovery, review queues, pipeline controls |
/chatbot |
Assistant | Feature-gated AI research assistant with web search and watchlist actions |
/stocks/:ticker |
Stock Detail | Charts, fundamentals, themes, watchlist actions, validation history |
/operations |
Operations | Runtime activity, queue/job inventory, telemetry alerts, safe job controls |
/options |
Options Command Center | Feature-gated US Candidate/Leader options analytics; also available read-only when advertised by the static snapshot |
/options/:symbol |
Options Detail | Strike structure, model-estimate GEX, IV smile, and discontinuous observed history for one current symbol |
Backend: FastAPI, SQLAlchemy, Alembic, Celery, Redis, PostgreSQL Frontend: React 18, Vite, Material-UI, TanStack Query / Table, Recharts Data: yfinance, Finviz, Alpha Vantage, SEC EDGAR, official X API (optional)
| Guide | Audience |
|---|---|
| Live App Guide | Users of the server-backed live application |
| Group Matrix Guide | Grid/Clusters, return periods, stock RS, data coverage, and live/static delivery |
| Operations Guide | Live-app operators and maintainers |
| Static Site Guide | Static demo users and maintainers |
| Options Command Center | Understanding the options cohort, metrics, history, and limitations |
| Docker Deployment | Server, homelab, VPS users |
| Development Guide | Contributors, developers |
| Architecture | Understanding the system design |
| Environment Variables | Configuration reference |
| MCP Integration | AI copilot workflows (12 tools via stdio / Streamable HTTP) |
| Backend API & Architecture | Backend developers |
| Frontend Components | Frontend developers |
| Contributing | Getting started as a contributor |
This software is for educational and research purposes only. It is not financial advice. Always do your own research and consult a licensed financial advisor before making investment decisions.
Released under the Apache License 2.0.