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 |