73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
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 |
|