Skip to content

Dashboard — Spec

Pages

15 pages accessible via top navigation bar:

Route Page Description
/ Overview KPI metrics, trending alerts, sector breakdown, prediction alerts, simulation compare, AI daily briefing card
/stock Stock Detail Price chart, technicals, predictions, AI debate, Monte Carlo simulation
/predictions Predictions Signal breakdown across all tickers
/news News Feed Article list with sentiment, language filter
/trends Sector Trends Sector heat map and trend chart
/tickers Manage Tickers Admin — add/remove tickers
/portfolio My Portfolio Upload screenshots, view holdings
/backtest Backtest Historical prediction backtest — hit rate by horizon, accuracy by confidence tier, rolling accuracy chart, per-ticker breakdown
/journal Trade Journal Manual trade log — add/edit/delete buy & sell entries, P&L tracking
/political-trades Political Trades Congressional STOCK Act disclosures + SEC EDGAR Form 4 insider trades; filter by trader, ticker, type, and date range; per-trader buy/sell stats bar; "ours" badge on tickers in watchlist
/earnings Earnings Calendar Upcoming and recent earnings events — date, EPS estimate vs actual, surprise %; filter by ticker
/sector-rotation Sector Rotation Sector momentum matrix — rolling sentiment change, volume, and prediction consensus by sector
/correlation Correlation Pairwise Pearson return correlation heatmap for all active tickers in the selected market
/briefings Daily Briefings Scrollable history of AI-generated nightly market briefings; collapsible entries; admin generate-now button
/screener Stock Screener Filter and rank all tracked stocks by ML prediction direction, confidence, sentiment, horizon, and market
/account Account User settings
/chat Chat AI chat panel
  • Horizontal button row at the top of every page; active page is highlighted
  • Sidebar (collapsed by default): identity strip only — username and Sign Out button; open via hamburger icon
  • AI Chat: accessible via "Chat" button in top nav

Per-Page Filters

Inline at the top of each page — not in sidebar: - Market filter (US / KR / All): Overview, Stock Detail, Predictions, News Feed, Sector Trends - Language toggle: switches all UI text between English and Korean

Auto-Generated Summaries

Each page displays a rule-based summary paragraph computed client-side from already-fetched data (no extra API calls):

  • Overview: sector bullish/bearish breakdown, top sector, most active ticker, total articles
  • Stock Detail: momentum, sentiment tone, prediction consensus, recent article count
  • Predictions: signal breakdown (UP/DOWN/NEUTRAL) with %, top bullish/bearish, market tone
  • News Feed: total articles, sentiment breakdown, most mentioned ticker
  • Sector Trends: total sectors tracked, bullish/bearish count, strongest sectors

Market Close Warning Banner

  • Appears when within 2 hours of a market close (US: 4pm ET; KR: 3:30pm KST)
  • Live countdown updated every minute; dismissable per-session
  • Admin users see a Refresh Data button that triggers the full pipeline with a progress spinner
  • Placed between top navbar and main content; amber styling
  • Top of Overview page, above KPI metrics
  • Top 5 tickers ranked by heat score (news volume × sentiment intensity) over last 3 days
  • Each ticker: expandable card with direction icon, article count, up to 3 recent headlines
  • Headlines show colored sentiment dots, timestamps, and clickable links
  • Scoped to active market filter

Prediction Alerts (Overview)

  • Full-width panel below the 3-column KPI grid
  • Shows unseen Alert rows (confidence ≥ 80%) ordered by triggered_at desc, capped at ALERT_FETCH_LIMIT (default 10)
  • Each alert shows ticker, market, direction, horizon, confidence — click to dismiss (optimistic removal, PATCH /predictions/alerts/{id}/seen)
  • Stale time: 2 minutes

Simulation Compare (Overview)

  • Panel at the bottom of the Overview page
  • Multi-select dropdown: pick up to 15 tickers (grouped by US / KR); "US" and "KR" header buttons select/deselect the entire market group; "Clear" deselects all
  • Controls: horizon pills (1d / 7d / 30d), method pills (Gaussian / Bootstrap / Regime), Run Simulation button with spinner
  • On Run: fires all simulations in parallel via Promise.allSettled; each ticker hits GET /simulation/{ticker}?market=&horizon=&method=
  • Chart: Recharts ComposedChart with one Line per ticker, Y-axis normalized to % return from day 0 (all series start at 0%), ReferenceLine at y=0; lines animate in staggered 150ms apart using Recharts built-in animation
  • Legend row: color swatch, display name + ticker code in "Name (TICKER)" format, market, median return %, probability of gain; error badge for tickers with insufficient data
  • Ticker selector pills and legend labels resolve display names from the tickers list (TICKER_NAMES); falls back to the raw code if the name is unavailable
  • Color palette: 15 distinct colors cycling across selected tickers

Monte Carlo Simulation (Stock Detail)

  • Second tab on Stock Detail page ("Overview" / "Simulation")
  • Three simulation methods selectable via pill toggle: Gaussian (GBM), Bootstrap (5-day block bootstrap), Regime (K-means 3-state Markov switching)
  • Requires ≥ 60 price rows; returns HTTP 400 otherwise
  • Chart: ComposedChart fan chart — Area pair for p5/p95 confidence band + Line for p50 median
  • KPI tiles: probability of gain, median return %, 5th percentile, 95th percentile
  • Each method has an InfoTooltip explaining the model
  • API: GET /simulation/{ticker}?market=&horizon=&method=

ML Prediction Explainability — "Why?" (Stock Detail)

  • Each horizon pill (1d / 7d / 30d) on the ML Prediction card has a "Why?" toggle button
  • On click: calls GET /predictions/{ticker}/explain?horizon= — user-triggered, not eager-loaded
  • Expands inline below the horizon pills: a ranked bar chart of the top 15 SHAP feature contributions for the predicted class
  • Green bars: feature pushed the model toward the predicted direction
  • Red bars: feature pushed against the predicted direction
  • Bar width proportional to |shap| relative to the maximum contribution
  • Right-side value shows the signed SHAP score (e.g. +0.18, -0.05)
  • Clicking the active "Why?" button collapses the panel and clears state; switching tickers clears state
  • API: GET /predictions/{ticker}/explain?horizon=1d — requires auth; returns 503 if model unavailable or shap not installed

Sentiment Trend Chart (Stock Detail)

  • Thin area chart displayed below the ML Predictions card on the Overview tab of Stock Detail
  • Shows the daily average FinBERT sentiment score for the selected ticker over the past 30 days
  • Only rendered when ≥ 2 data points exist (hidden when no sentiment history is available)
  • Y-axis range: −1 to +1; three reference lines: gray solid at 0, green dashed at +0.15, red dashed at −0.15
  • Tooltip color-codes the value: green for bullish (≥ 0.15), red for bearish (≤ −0.15), gray for neutral
  • Data source: GET /sentiment/{ticker}/daily?days=30 — aggregates raw SentimentScore rows by calendar day (UTC); returns [{date, avg_score, count}]
  • Stale time: 10 minutes

Correlation Heatmap (/correlation)

  • Market filter: US or KR toggle; days selector: 14 / 30 / 60 / 90
  • Computes pairwise Pearson correlation of daily log-returns from GET /prices/correlation?market=&days=
  • Backend: single DB query for all active-ticker prices in the window → log-return matrix → pairwise correlation with pairwise-complete observations (pairs with fewer than 5 overlapping days shown as "n/a")
  • Grid: N×N CSS grid with row/column labels (ticker symbols); cells colored by strength tier (strong +/mod +/neutral/mod −/strong −)
  • Hover: status bar at top right shows the two tickers, full display names, and the exact correlation value
  • Stale time: 10 minutes

Stock Screener (/screener)

  • Filter bar with compact button-group controls: Market (All / US / KR), Horizon (All / 1d / 7d / 30d), Direction (All / Up / Down / Neutral), Min Confidence (0–100% number input), Sort by (Confidence / Sentiment / Ticker)
  • Results table: Ticker (links to Stock Detail), Market, Direction chip (color-coded), Confidence %, Sentiment (7d avg with score count), Predicted (relative time ago)
  • "All" horizon shows one row per ticker per horizon; other horizon selections show only the latest prediction for that horizon
  • Empty-state message when no stocks match the active filters
  • Data source: GET /screener — returns up to 200 results, filters applied server-side, sorted by the selected field
  • Stale time: 2 minutes

Daily Briefings (/briefings)

  • Scrollable list of AI-generated nightly market summaries stored in the daily_summaries table
  • Limit selector: Last 7 / 14 / 30 / 90 entries; newest first
  • Each entry shows date, UTC time, model name, token count, and the briefing text
  • Long entries are truncated to 200 characters with a Read more / Show less toggle
  • Admin-only Generate Now button calls POST /reports/daily-summary/refresh to trigger on-demand generation and invalidates the cache
  • Data source: GET /reports/daily-summary/history?limit= — returns up to 90 entries; limit clamped to [1, 90]
  • Stale time: 5 minutes

AI Bull vs Bear Debate (Stock Detail)

  • Panel on the Overview tab of Stock Detail, between the Sentiment Trend chart and the Price & Sentiment chart
  • User-triggered — a "Generate" button initiates the call; the panel is blank until clicked (avoids LLM cost on every page load); button label changes to "Regenerate" after a result is shown
  • On click: calls GET /api/debate/{ticker}?market= which invokes models/debate.py
  • Backend collects the ticker's latest predictions (all three horizons), sentiment summary (7d and 30d), historical backtest accuracy, and fundamentals, then makes two Claude Haiku calls with a shared cached system prompt
  • Result: green-bordered ▲ Bull Case card and red-bordered ▼ Bear Case card rendered side-by-side
  • Both cases are 3–4 sentences, citing specific numbers (confidence %, sentiment scores, momentum, fundamentals)
  • Debate data is cleared when the user switches to a different ticker
  • Error message shown inline if ANTHROPIC_API_KEY is unset or no predictions exist for the ticker
  • API: GET /api/debate/{ticker}?market=; requires auth; result is not persisted to DB

Price Chart (Stock Detail)

  • Area/line chart — close >= period_open → green; otherwise red
  • Time range selector: 5D / 1M / 6M / YTD / 1Y / 5Y / Max
  • Previous-close dotted reference line with annotation
  • Sentiment overlay on secondary Y-axis (−1 to +1) for the same time range

Bilingual UI

  • Language toggle renders inline on pages with translatable content
  • All labels, buttons, headers, empty states, and summaries are translated (EN ↔ KO)

News Language Filter

  • News Feed page: filter articles by source language (All / English / Korean)
  • Filters NewsArticle.language — independent from UI language toggle

Headline Translation

  • Page-level toggle on News Feed and Stock Detail: "Show titles in: Original / EN / KO"
  • Translations cached in DB (title_en, title_ko) to avoid repeated API calls

Indicator Tooltips

  • ? icon on each metric tile; hovering shows a layman-friendly explanation
  • 9 metrics: RSI, Stochastic %K, MACD Histogram, Bollinger %B, OBV Trend, Volume Ratio, Confidence, Sentiment Avg 7d, Price Momentum 5d

Data Controls (Pipeline Runner)

  • Collapsed accordion on Overview page
  • Run Full Pipeline: Prices → News → Sentiment → Trends → Predictions in sequence
  • Individual step buttons for each stage
  • Live log panel with timestamped output; stop-on-first-failure

Manage Tickers (Admin)

  • Watchlist table with per-row Activate / Deactivate buttons
  • Add form: symbol, market, display name, sector (optional)
  • Validation: KR must be 6-digit numeric; US must be alphabetic; duplicate check
  • Soft delete: active=False — excluded from pipeline but historical data preserved

Constraints

  • FastAPI CORS allows localhost:5173 and localhost:3000; production needs real frontend origin added
  • TanStack Query: staleTime: 60_000, retry: 1
  • All API calls use credentials: "include" for cookie auth