Skip to content

Dashboard — Spec

Stack

React 19 + TypeScript SPA (Vite, port 5173) backed by FastAPI (port 8000).
Libraries: TanStack Query v5, TanStack Table, Recharts, shadcn/ui, lucide-react, date-fns, Tailwind v4.

Pages

9 pages accessible via top navigation bar:

Route Page Description
/ Overview KPI metrics, trending alerts, sector breakdown, prediction alerts, simulation compare
/stock Stock Detail Price chart, technicals, predictions, Buffett analysis, 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
/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=

Price Chart (Stock Detail)

  • Area/line chart — green when close ≥ period open; red otherwise
  • 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