saikiranvella
171 lines
5.9 KiB
Markdown
171 lines
5.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for working in this repository.
|
|
|
|
## Overview
|
|
|
|
`market-screener-ui` is a SvelteKit 5 single-page application (CSR, no SSR) that serves as the interactive dashboard for the `market_screener` Fastify API.
|
|
|
|
- All data comes from the API at `http://localhost:3000` (proxied through Vite in dev)
|
|
- No SSR — `+layout.js` exports `ssr = false`
|
|
- Svelte 5 runes syntax (`$state`, `$derived`, `$effect`, `$props`)
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm install # install dependencies (SvelteKit, Vite, Svelte 5)
|
|
npm run dev # dev server on port 5173
|
|
npm run build # production build → .svelte-kit/output
|
|
npm run preview # preview production build
|
|
```
|
|
|
|
To run the full stack, use `npm run dev` from the **API repo** (`market_screener/`) instead — it starts both servers together using `concurrently`.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### No SSR
|
|
`src/routes/+layout.js` exports `ssr = false`. All data fetching happens in the browser. This avoids Svelte 5 SSR compatibility issues and makes sense for a live-data dashboard.
|
|
|
|
### API Proxy
|
|
`vite.config.js` proxies `/api/*` → `http://localhost:3000` in dev. In production, configure your reverse proxy (nginx/Caddy) to do the same.
|
|
|
|
### Data Loading
|
|
- **Screener page** (`/`): data loaded client-side on button click via `$lib/api.js`
|
|
- **Portfolio page** (`/portfolio`): data loaded via SvelteKit `+page.js` `load()` function — this fires on navigation and is the correct SvelteKit pattern for CSR page data
|
|
|
|
**Do not use `onMount` for initial data fetching** — use `load()` in `+page.js` instead. `onMount` does not reliably fire in SvelteKit CSR for page-level data.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
app.html ← HTML shell
|
|
app.css ← Global reset + body styles (no :global() in .svelte files)
|
|
routes/
|
|
+layout.js ← exports ssr = false
|
|
+layout.svelte ← nav bar (Screener / Portfolio links)
|
|
+page.svelte ← Screener page
|
|
portfolio/
|
|
+page.js ← load() function — fetches /api/finance/portfolio
|
|
+page.svelte ← Portfolio + SimpleFIN page
|
|
|
|
lib/
|
|
api.js ← All fetch calls to the Fastify API
|
|
SignalBadge.svelte ← Signal pill component (Strong Buy / Avoid / etc.)
|
|
MarketContext.svelte ← Benchmark strip component
|
|
|
|
.claude/
|
|
launch.json ← Preview server config for Claude Code
|
|
|
|
vite.config.js ← Vite config with /api proxy
|
|
svelte.config.js ← SvelteKit config (adapter-auto)
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
### `src/lib/api.js`
|
|
All API calls in one place. If the API base URL changes, change it here only.
|
|
|
|
```js
|
|
screenTickers(tickers) // POST /api/screen
|
|
fetchCatalysts() // GET /api/screen/catalysts
|
|
fetchPortfolio() // GET /api/finance/portfolio
|
|
fetchMarketContext() // GET /api/finance/market-context
|
|
```
|
|
|
|
### `src/routes/+page.svelte` (Screener)
|
|
- Ticker input pre-filled with a default watchlist
|
|
- `screen()` calls API and stores results in `$state`
|
|
- `loadCatalysts()` fetches news tickers then **immediately calls `screen()`** — one click, full results
|
|
- `results` is `null` until first screen — nothing renders below the toolbar
|
|
- `verdictShort()` abbreviates long verdict strings (`"🟢 BUY (High Conviction)"` → `"Strong"`)
|
|
|
|
### `src/routes/portfolio/+page.svelte`
|
|
- Receives `data` from `+page.js` load function via `let { data } = $props()`
|
|
- Shows `data.error` if load failed, `data.advice` for holdings, `data.personalFinance` for SimpleFIN section
|
|
|
|
---
|
|
|
|
## Svelte 5 Patterns Used
|
|
|
|
```svelte
|
|
<!-- Reactive state -->
|
|
let loading = $state(false);
|
|
|
|
<!-- Derived values -->
|
|
const totalGL = $derived(totalValue - totalCost);
|
|
|
|
<!-- Derived with block -->
|
|
const cards = $derived.by(() => { ... return [...] });
|
|
|
|
<!-- Props -->
|
|
let { ctx } = $props();
|
|
let { data } = $props();
|
|
|
|
<!-- Event handlers (no on:click, use onclick) -->
|
|
<button onclick={screen}>Screen</button>
|
|
|
|
<!-- Conditionals in template -->
|
|
{@const mode = getTab(type)}
|
|
```
|
|
|
|
---
|
|
|
|
## API Response Shape
|
|
|
|
The Fastify API serializes asset class instances before sending — `asset.getDisplayMetrics()` is called server-side and included as `asset.displayMetrics`. In the browser, use `r.asset.displayMetrics` directly (not `r.asset.getDisplayMetrics()` which doesn't exist on plain JSON objects).
|
|
|
|
```js
|
|
// Screener response shape
|
|
{
|
|
STOCK: [{ asset: { ticker, type, currentPrice, metrics, displayMetrics }, fundamental, inflated, signal }],
|
|
ETF: [...],
|
|
BOND: [...],
|
|
ERROR: [...],
|
|
marketContext: { sp500Price, riskFreeRate, vixLevel, rateRegime, volatilityRegime, benchmarks }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Styling Conventions
|
|
|
|
- Dark theme throughout: page background `#0f1117`, card sections `#0d1117`/`#111827`
|
|
- All colors are CSS custom values inline (no CSS variables yet — keep consistent with existing palette)
|
|
- Tables: `width: max-content; min-width: 100%` inside a `.table-wrap { overflow-x: auto }` container
|
|
- First column sticky: `position: sticky; left: 0; background: inherit`
|
|
- Verdict pills: `.verdict-pill.green/yellow/red` — colored background tint + text
|
|
- Monospace font for the ticker input field
|
|
- `white-space: nowrap` on `tbody td` — tables scroll horizontally, not wrap
|
|
|
|
**Color palette:**
|
|
```
|
|
page bg: #0f1117
|
|
card bg: #0d1117 / #111827 (header rows)
|
|
border: #1e293b
|
|
muted: #64748b / #475569
|
|
text: #e2e8f0 / #f1f5f9
|
|
green: #4ade80 (bg tint: #14532d33)
|
|
yellow: #facc15 (bg tint: #71350033)
|
|
red: #f87171 (bg tint: #450a0a33)
|
|
blue accent: #2563eb / #3b82f6
|
|
```
|
|
|
|
---
|
|
|
|
## Conventions
|
|
|
|
- Do not use `:global()` in `<style>` blocks — put global styles in `src/app.css`
|
|
- Use `load()` in `+page.js` for page-level data, not `onMount`
|
|
- `$derived` for computed values — do not recalculate in templates
|
|
- Keep `api.js` as the single place for fetch calls
|
|
- If adding a new page: create `+page.js` with a `load()` that fetches the needed API endpoint, receive via `$props()` in the component
|