AITrader/docs/superpowers/specs/2026-05-16-most-active-stocks-table-design.md

y# Design: Most Active Stocks Table

Date: 2026-05-16 Status: Approved

Overview

Replace the current StockViewer on the /stocks page with a table displaying the most active stocks from Alpaca's screener API.

Architecture

Server Route: api/stocks/most-actives

• File: app/routes/api/stocks/most-actives.ts
• Method: GET (loader)
• Function: Proxies request to https://data.alpaca.markets/v1beta1/screener/stocks/most-actives
• Response: Normalized JSON array with fields: symbol, name, price, changePercent, volume
• Auth: Uses server-side ALPACA_API_KEY and ALPACA_SECRET_KEY

Component: MostActiveStocks

• File: app/components/MostActiveStocks.tsx
• Behavior:
  • Fetches from /api/stocks/most-actives on mount
  • Auto-refreshes every 30 seconds via setInterval
  • Cleans up interval on unmount
• States: loading (skeleton rows), success (table), error (red banner with retry button)

Page: stocks.tsx

• Replaces <StockViewer /> with <MostActiveStocks />
• Updates heading and description text to match new content

Data Flow

MostActiveStocks component
  → fetch /api/stocks/most-actives
    → server calls Alpaca screener API
    → returns normalized data
  → renders table
  → setInterval re-fetches every 30s

Table Columns

Column	Source	Format
Symbol	symbol	Clickable link → /analyze/TICKER
Name	name	Plain text
Price	price	$X.XX
Change %	changePercent	+X.XX% / -X.XX% (color-coded green/red)
Volume	volume	Formatted number (e.g., 12.3M)

Error Handling

• API errors: display red banner with error message and retry button
• Network failures: show last data if available, otherwise error state
• Empty response: show "No data available" message

Route Changes

Add to routes.ts:

route("api/stocks/most-actives", "routes/api/stocks/most-actives.ts"),

Files Created/Modified

File	Action	Purpose
app/routes/api/stocks/most-actives.ts	Create	Server proxy to Alpaca
app/components/MostActiveStocks.tsx	Create	Table component with auto-refresh
app/routes/stocks.tsx	Modify	Replace StockViewer with MostActiveStocks
app/routes.ts	Modify	Add new API route