Signal Scanner — Technical Stock Screener

A stock-screening dashboard that scans for meaningful technical signals, scores setups 0–100, tracks signal lifecycle (forming → confirmed → extended → failed), and explains the evidence behind every rank.

Status: All 10 phases complete. Runs on real market data by default (keyless Yahoo Finance), with an optional Polygon key and a labeled simulated fallback. The active source is always shown in the header badge. Nothing here is investment advice.

Running

npm install
npm run dev        # http://localhost:3000
npm test           # unit tests (Vitest)
npm run lint       # ESLint
npm run typecheck  # TypeScript
npm run build      # production build

Append ?error=1 to the URL to exercise the error state.

Market data

Out of the box the app uses Yahoo Finance (keyless, no per-minute cap, years of history) — no setup required. Optionally add a Polygon key in .env.local to use it as the primary source; when Polygon's free 5 req/min budget is spent, the scan automatically falls back to Yahoo:

POLYGON_API_KEY=...        # optional — primary source, Yahoo covers the overflow
UNIVERSE_LIMIT=40          # how many universe tickers to scan
DATA_CACHE_SECONDS=1800    # snapshot refresh cadence
# MARKET_DATA_PROVIDER=yahoo|mock   DISABLE_YAHOO=1   LIVE_TICKERS=AAPL,MSFT,...

Keys stay server-side (Next.js API routes). Requests are batched, rate-limited per provider, retried with backoff, circuit-broken, and cached with a TTL. If every live source is unreachable the app degrades to labeled simulated data — never invented values. The header badge shows the active source (e.g. Live · Polygon + Yahoo Finance or Simulated data).

Any ticker, on demand. The screener scans the full curated universe (~126 names), but you're not limited to it — type any symbol in the search bar and, in live mode, "Look up <TICKER>" fetches and analyzes it standalone (chart, signals, levels, multi-timeframe — the full detail page).

What's built (Phase 1)

• Market overview cards — indexes with sparklines, market breadth, active-signal counts
• Ranked screener table — 15 sortable columns (price, change, signal, status, score, trend, RVol, RSI, key levels, sector, age, updated)
• Search — ticker or company name
• Filters — score, signal category/status, direction, trend, price, market cap, volume, relative volume, RSI range, ATR volatility range, sector
• Presets — 8 built-ins (Strong Breakouts, Pullbacks in Uptrends, Oversold Reversals, RS Leaders, Volatility Squeezes, Bearish Breakdowns, Failed Breakouts, High-Volume Movers) + save/delete custom presets (persisted)
• Watchlist — star stocks, watchlist tab, persisted in localStorage
• Stock detail panel — summary, component-score breakdown, bullish/bearish evidence, invalidation level, honest verdict
• States — loading skeletons, empty state, error state with retry, refresh

Roadmap

Phase	Scope
1 ✅	Dashboard + screener UI on labeled mock data
2 ✅	Deterministic indicator engine (SMA/EMA/RSI/MACD/ATR/BB/KC/Stoch/ROC/VWAP/RVol/OBV/rolling+pivot/gaps) + 34 tests
3 ✅	Signal detection engine — ~45 context-aware detectors with evidence + warnings, replayable bar-by-bar; mock data now runs real detection on synthetic OHLCV
4 ✅	Weighted scoring engine — deterministic, direction-aware components + named, UI-visible bonuses/penalties
5 ✅	Signal lifecycle — bar-by-bar instance tracking (Forming→…→Failed) with trigger times, distance from trigger, and end reasons
6 ✅	Stock detail page — lightweight-charts candlesticks, 1H/4H/D/W timeframes, MA/BB/VWAP overlays, S/R + trigger lines, lifecycle markers, RS panel, signal history
7 ✅	Multi-timeframe analysis — W/D/4H/1H bias + timing notes, weighted alignment, conflict detection feeding the score
8 ✅	Real market data — Polygon/Tiingo behind a provider interface, server-side API routes, rate limiting, retries, TTL caching, mock fallback
9 ✅	Alerts (11 condition types, rising-edge de-dup, notification bell) + enriched watchlist (notes, tags, saved levels, preferred signals)
10 ✅	Historical signal analytics — bar-by-bar backtest, direction-adjusted forward returns, win/failure rates, breakdowns by signal type / score / sector / market condition; no look-ahead

Architecture notes

• src/lib/types.ts — domain types shared by mock and (future) real engines
• src/lib/engine/ — deterministic indicator engine (aligned outputs, NaN warm-up, no look-ahead; see SKILLS.md for formulas)
• src/lib/mock/ — deterministic seeded mock generator (archetype-shaped price series; indicators computed from the series so stats/evidence agree)
• src/lib/data/source.ts — async data-source interface the Phase 8 provider layer will implement
• src/lib/screener.ts — pure filter/sort logic (unit-tested)
• src/components/screener/ — dashboard UI (Next.js App Router, Tailwind v4, shadcn/ui)

See SKILLS.md for verified decisions and lessons learned.