Files

T

saikiranvella e953822bab phase-10.5: screener enhancements

2026-06-11 19:18:19 -04:00

20 KiB

Raw Blame History

Market Screener

A personal stock screener and portfolio tracker. Scores stocks, ETFs, and bonds under two lenses — Market-Adjusted (what's acceptable in today's market) and Fundamental (strict Graham value-investing) — then compares them to produce an actionable signal. Comes with a live SvelteKit dashboard.

Developer Setup
Environment Variables
Commands
Running Tests
Project Structure
User Guide
API Testing with Bruno

Developer Setup

Prerequisites

Node.js 20+ (v22 recommended)
npm 10+

Check your versions:

node --version   # Should output v20.x.x or higher
npm --version    # Should output 10.x.x or higher

Not on Node 20+? See NODE_VERSION_FIX.md for upgrade instructions.

Install

# Install server dependencies
npm install

# Install UI dependencies (first time only)
npm run ui:install

Start

npm run dev

This starts both the API server on port 3000 and the SvelteKit UI on port 5173 concurrently. Open http://localhost:5173.

To run the API server alone:

npm run server

Environment Variables

Create a .env file in the project root. None are required to run the app — it works with Yahoo Finance data out of the box. Optional keys unlock additional features.

`ANTHROPIC_API_KEY` — LLM news analysis (optional)

Powers the Analyze button on each screener section. Without this key the button is disabled.

Go to console.anthropic.com
Create an API key under API Keys
Add to .env:

ANTHROPIC_API_KEY=sk-ant-...

`SIMPLEFIN_SETUP_TOKEN` — Live bank/brokerage balances (optional)

Powers the personal finance section of the Portfolio page (net worth, account balances, spending breakdown).

Go to beta-bridge.simplefin.org and create a Setup Token
Add to .env:

SIMPLEFIN_SETUP_TOKEN=aHR0cHM6Ly...

On first request the token is claimed automatically and the resulting Access URL is saved back to .env as SIMPLEFIN_ACCESS_URL. Subsequent restarts use the Access URL directly.

`API_KEY` — Bearer token auth (optional)

When set, every API route requires Authorization: Bearer <key>. Useful when the server is exposed to a network. /health and OPTIONS preflight are exempt.

API_KEY=your-secret-key

`CLIENT_ORIGIN` — CORS allowed origin (optional)

Defaults to http://localhost:5173. Change if the UI is served from a different origin.

CLIENT_ORIGIN=https://yourdomain.com

`EDGAR_USER_AGENT` — SEC filings poller (recommended)

The news pipeline polls SEC EDGAR for 8-K / SC 13D / S-4 / DEFM14A filings. The SEC requires a descriptive User-Agent with contact info:

EDGAR_USER_AGENT=market-screener/1.0 you@example.com

`DISCORD_WEBHOOK_URL` — Daily digest alerts (optional)

The daily change digest (npm run digest:daily) posts signal flips + their news catalysts to Discord. Create: channel → Settings → Integrations → Webhooks → New Webhook → copy URL. Paste it RAW (no quotes, no escaping). Forum channels are supported (each digest becomes a dated post). Test with npm run discord:test.

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

`NEWS_PRWIRE_FEEDS` — Override press-release RSS feeds (optional)

Comma-separated RSS URLs. Defaults to GlobeNewswire + PR Newswire. Only needed if a default feed goes stale or you want to add one.

`NEWS_POLL` — Disable in-server news polling (optional)

Set NEWS_POLL=off if you prefer running npm run news:poll from cron instead of polling inside the server (EDGAR 10 min, PR-wire 15 min).

Complete `.env` example

ANTHROPIC_API_KEY=sk-ant-...
SIMPLEFIN_SETUP_TOKEN=aHR0cHM6Ly...
API_KEY=optional-secret
CLIENT_ORIGIN=http://localhost:5173
EDGAR_USER_AGENT=market-screener/1.0 you@example.com
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

Commands

Command	Description
`npm run dev`	Start API (port 3000) + UI (port 5173) together
`npm run server`	Start API server only
`npm run ui:install`	Install UI dependencies (first time / after `git pull`)
`npm test`	Run all unit + integration tests
`npm run test:watch`	Watch mode — re-run on file changes
`npm run typecheck`	TypeScript type check without emitting
`npm run format`	Format all source files with Prettier
`npm run format:check`	Check formatting without writing (used in CI)
`npm run lint`	Run ESLint on all TypeScript files
`npm run lint:fix`	Auto-fix ESLint issues
`npm run screen:daily`	Screen watchlist + holdings, write signal snapshots (cron at market close)
`npm run news:poll`	One-shot news poll: EDGAR + PR wires → news DB (cron alternative)
`npm run digest:daily`	Daily change digest: signal flips + catalysts → terminal/Discord (run after screen:daily)
`npm run discord:test`	Send a fake digest to verify the Discord webhook

Recommended cron (weekdays, market close):

30 16 * * 1-5  cd /path/to/market_screener && npm run screen:daily && npm run digest:daily

Running Tests

npm test

Uses Node's built-in node:test runner — no external framework. 114 test cases across 9 files cover:

Test File	Tests	Coverage
`app.test.ts`	9	App bootstrap, CORS, health endpoints
`screener-controller.test.ts`	10	`/api/screen` endpoints
`screener-engine.test.ts`	11	Screening orchestration logic
`stock-scorer.test.ts`	13	Stock valuation gates
`etf-scorer.test.ts`	17	ETF fund gates
`bond-scorer.test.ts`	16	Bond credit analysis
`portfolio-advisor.test.ts`	12	Portfolio advice logic
`portfolio-controller.test.ts`	12	Portfolio endpoints
`calls-controller.test.ts`	14	Market calls endpoints

Pre-Commit & Pre-Push Hooks

On git commit, the pre-commit hook automatically:

Formats all files with Prettier
Lints & fixes staged files with ESLint
Runs tests to catch errors early

On git push, the pre-push hook runs tests again for safety.

Project Structure

Phase 9: Domain-Driven Architecture (completed)

bin/
  server.ts              API server entry point

server/
  app.ts                 Fastify app factory — wires DI, rate limiting, auth hook
  domains/               Domain-driven structure (shared, screener, portfolio, calls, finance)
    shared/              Infrastructure & cross-domain utilities
      adapters/          YahooFinanceClient, AnthropicClient, SimpleFINClient
      services/          BenchmarkProvider, CatalystAnalyst, LLMAnalyst
      entities/          Asset, Stock, Etf, Bond
      persistence/       MarketCallRepository, PortfolioRepository
      config/            ScoringConfig (gates/weights), constants
      scoring/           MarketRegime, scoring overrides
      types/             TypeScript interfaces (one file per domain)
    screener/            Stock/ETF/Bond filtering & scoring
      ScreenerEngine.ts  Orchestrates: fetch → score × 2 (fundamental + inflated)
      scorers/           StockScorer, EtfScorer, BondScorer
      transform/         DataMapper, RuleMerger
    portfolio/           Holdings management & investment advice
      PortfolioAdvisor.ts  Cross-references holdings with screener signals
    calls/               Market call tracking & earnings calendar
      CalendarService.ts  Earnings calendar logic
    finance/             Portfolio metrics & reporting

ui/
  src/
    routes/              SvelteKit pages: /, /portfolio, /calls, /safe-buys
    lib/
      components/        Shared UI components organized by domain
      stores/            Svelte 5 reactive stores
      api/               Fetch wrappers for each API domain
    styles/              Global SCSS design tokens and partials

tests/                   Unit + integration tests (9 files, 114 test cases)
                         Controllers, services, scorers fully covered

portfolio.json           Your holdings (gitignored — create manually or via the UI)
market-calls.json        Persisted market thesis calls (gitignored)
.benchmark-cache.json    Benchmark data cache — survives server restart (gitignored)

See CLAUDE.md for detailed architecture and PHASES.md for the complete roadmap.

User Guide

Screener tab

The main view. On load it automatically fetches today's financial news, extracts the most-mentioned tickers, and screens them.

Market context strip

The row of chips at the top shows live benchmark data fetched from Yahoo Finance:

Chip	Meaning
10Y	10-year Treasury yield — the risk-free rate
VIX	Volatility index — market fear gauge
S&P	S&P 500 index price
S&P P/E	Trailing P/E of the S&P 500 (via SPY)
Tech P/E	Trailing P/E of the tech sector (via XLK)
REIT Yld	REIT dividend yield (via XLRE)
IG Sprd	Investment-grade bond spread above risk-free (LQD − TNX)
Rates	Rate regime: LOW / NORMAL / HIGH (based on 10Y yield)
Vol	Volatility regime: LOW / NORMAL / HIGH (based on VIX)

The rate regime affects how strict the Market-Adjusted gates are — in a HIGH rate environment the P/E multiplier compresses and bond spreads tighten.

Signal Summary table

Quick overview of all screened tickers with their signal, market-adjusted verdict, fundamental verdict, market cap tier, and growth style.

Per-asset detail tables

Expand each section (STOCK / ETF / BOND) for full metrics: P/E, PEG, ROE, margins, FCF yield, D/E, analyst consensus, DCF intrinsic value, 52-week movement, and more.

Analyze button

Runs an Anthropic LLM over the latest Yahoo Finance news for assets in that section. Returns a sentiment summary, affected industries, and related tickers to watch. Requires ANTHROPIC_API_KEY.

Search tickers

Click Search tickers to screen any custom list — type tickers comma or space separated and press Enter or click Screen.

Signals explained

Signal	What it means
✅ Strong Buy	Passes both Market-Adjusted AND Fundamental gates — genuine value at current prices
⚡ Momentum	Passes Market-Adjusted, holds fundamentally — good in the current market but not a bargain
⚠️ Speculation	Passes Market-Adjusted, fails Fundamental — priced for perfection, high risk
🔄 Neutral	Borderline in one or both lenses — hold, no clear edge
❌ Avoid	Fails both lenses

How scoring works

Every asset is scored twice:

Market-Adjusted gates move with the market. The stock P/E gate = SPY trailing P/E × 1.5 (compresses to × 1.2 in a HIGH rate regime). Tech P/E = XLK P/E × 1.3. This reflects what the market is currently willing to pay.

Fundamental gates are fixed Graham/value-investing standards that never change:

Gate	Threshold	Rationale
Stock P/E	< 15×	Graham's actual rule
Stock PEG	< 1.0	Lynch: PEG > 1.0 = paying full price
D/E ratio	< 1.5×	Distress typically starts above 2×
Quick ratio	> 0.8	Below 0.8 = real liquidity stress

Sector overrides apply in both modes — e.g. tech stocks allow P/E up to 35× and D/E up to 2.0, REITs are scored on yield rather than P/E.

Portfolio tab

Track your holdings and get hold/sell/add advice cross-referenced with screener signals.

Adding holdings — click + Add Holding and fill in ticker, shares, cost basis, asset type, and source broker. Holdings are saved to portfolio.json on disk.

Inline editing — click the ✎ pencil icon on any row to edit shares, cost basis, type, or source directly in the table.

Advice column — each holding is screened live and the signal is combined with your gain/loss position:

Situation	Advice
✅ Strong Buy signal	Hold & Add
⚡ Momentum + > 30% gain	Consider partial profit-taking
⚠️ Speculation + > 20% gain	Reduce position
❌ Avoid signal + in profit	Sell (Take Profits)
❌ Avoid signal + at a loss	Sell (Cut Loss)
Crypto	Hold / Review position (no fundamental scoring)

Personal finance section (requires SimpleFIN) — when configured, the page also shows net worth, total assets vs liabilities, cash vs investments ratio, monthly income/spend, account balances, and a spending breakdown by category for the last 30 days.

Market Calls tab

Record and track quarterly investment theses from the day you make the call.

Creating a call — click ＋ New Call and fill in:

Title — e.g. "Q3 2025 — Rate pivot & tech rotation"
Quarter — the quarter this thesis applies to
Thesis — the macro reasoning behind the call (min 10 characters)
Tickers — the assets you're watching for this thesis

When saved, the current price and signal for each ticker are snapshotted automatically.

Viewing performance — click any call card to see the current price and signal for each ticker alongside the original snapshot, so you can measure how the thesis played out.

Calendar — shows upcoming earnings dates, ex-dividend dates, and dividend payment dates for all tickers across your active calls.

Safe Buys tab

A filtered view showing only tickers with a ✅ Strong Buy signal across both lenses. A quick watchlist of assets passing the strictest criteria in the current market.

API rate limits

/api/screen, /api/screen/catalysts, and /api/analyze are capped at 10 requests per minute per IP. All other routes allow 60 per minute.

API Testing with Bruno

What is Bruno?

Bruno is a lightweight, open-source API client that's Git-friendly and perfect for testing REST APIs. It stores collections as plain text files instead of JSON blobs, making them easy to version control and collaborate on.

Installing Bruno

macOS (via Homebrew)

brew install bruno

macOS (Direct Download)

Visit usebruno.com/downloads
Download the macOS version
Drag Bruno.app to Applications folder

Windows

Visit usebruno.com/downloads
Download the Windows installer (.exe)
Run the installer and follow the prompts
Or via Chocolatey: choco install bruno

Linux (Ubuntu/Debian)

# Add Bruno repository
curl -1sLf 'https://dl.usebruno.com/install.sh' | sudo bash

# Install
sudo apt-get install bruno

Linux (Fedora/RHEL)

curl -1sLf 'https://dl.usebruno.com/install.sh' | sudo bash
sudo dnf install bruno

Installing Bruno CLI (brucli)

For running tests from the command line without the GUI:

macOS

brew install brucli

Windows

choco install bruno-cli

Linux

curl -1sLf 'https://dl.usebruno.com/install.sh' | sudo bash

Importing the API Collection

Method 1: Import via Bruno GUI (Easiest)

Open Bruno
File → Import Collection
Select api_collections/market-screener.postman_collection.json
Choose location where to save the converted collection (e.g., api_collections/market-screener)
Click Import — Bruno automatically converts and structures the collection

Method 2: Import via Bruno CLI

# Navigate to the project root
cd market-screener

# Import the Postman collection
bru import api_collections/market-screener.postman_collection.json -o api_collections/market-screener

# Output: Collection imported to api_collections/market-screener/

Method 3: Convert Postman to Bruno Format (Manual)

If you prefer to manually convert the collection:

# Install conversion dependencies (if needed)
pip install requests

# Run the conversion script
python3 api_collections/convert_postman_to_bruno.py \
  api_collections/market-screener.postman_collection.json \
  api_collections/market-screener

Running Tests

Via Bruno GUI

Open the imported collection in Bruno
Set the baseUrl variable (default: http://localhost:3000)
Click the Play button to run all tests
View results for each request in the UI

Via Bruno CLI (brucli)

# Navigate to the collection directory
cd api_collections/market-screener

# Run all tests in the collection
bru run

# Run with specific environment
bru run --env local

# Run with output format
bru run --output json > test-results.json

# Run specific test file
bru run "Screener/Screen - Mixed.bru"

Collection Structure

After import, you'll have:

api_collections/market-screener/
├── bruno.json                    # Collection metadata
├── Health/
│   └── Health Check.bru
├── Screener/
│   ├── Screen - Mixed.bru
│   ├── Screen - Tech Stocks.bru
│   ├── Screen - REIT.bru
│   ├── Validation empty tickers.bru
│   ├── Validation 50 plus tickers.bru
│   └── Get Catalysts.bru
├── Market Context/
│   └── Get Market Context.bru
├── Portfolio/
│   ├── Add Holding AAPL.bru
│   ├── Add Holding VOO.bru
│   ├── Add Holding BTC-USD.bru
│   ├── Add Holding Validation.bru
│   ├── Get Portfolio.bru
│   ├── Remove Holding AAPL.bru
│   └── Remove Holding Non-existent.bru
├── Market Calls/
│   ├── List Calls.bru
│   ├── Create Market Call.bru
│   ├── Get Call by ID.bru
│   ├── Get Call Non-existent.bru
│   ├── Get Earnings Calendar.bru
│   ├── Get Calendar Specific Tickers.bru
│   ├── Create Call Validation.bru
│   ├── Delete Call.bru
│   └── Delete Call Already Deleted.bru
└── LLM Analysis/
    ├── Analyze Tickers.bru
    └── Analyze Validation.bru

Configuration

Setting Variables

Variables are stored in bruno.json and can be overridden per request:

Default variables:

baseUrl: http://localhost:3000
callId: (auto-populated by Create Market Call request)

To change variables in the GUI:

Right-click collection → Settings
Click Variables tab
Edit baseUrl or other variables
Click Save

Environment Files

Create a .env.bruno file in the collection directory for local overrides:

baseUrl=http://localhost:3000
apiKey=your-secret-key

Common Workflows

1. Test the full API flow

cd api_collections/market-screener
bru run

2. Test just the Screener endpoints

cd api_collections/market-screener
bru run "Screener"

3. Test and save results

cd api_collections/market-screener
bru run --output json > test-results-$(date +%Y%m%d).json

4. Continuous testing (while developing)

# Terminal 1: Run the API server
npm run dev

# Terminal 2: Watch and run tests every 5 seconds
cd api_collections/market-screener
watch -n 5 'bru run'

Troubleshooting

"You can run only at the root of a collection" error

Make sure you're in the correct directory:

# ❌ Wrong — project root
cd market-screener
bru run

# ✅ Correct — collection root
cd api_collections/market-screener
bru run

Variables not found

Verify variable names in bruno.json:

# Check variables
cat api_collections/market-screener/bruno.json | grep -A 10 "vars"

Tests failing with "undefined" errors

Common causes:

Variable name mismatch (case-sensitive)
Server not running on the expected port
Port conflict (try lsof -i :3000 to check)

Postman vs Bruno

Feature	Postman	Bruno
Download Size	~380MB	~50MB
Collection Format	Single JSON blob	Plain text `.bru` files
Git-Friendly	❌ Binary	✅ Text-based, diffable
API Response	UI-only	CLI + GUI
Cost	Free tier + paid	✅ Completely free
IDE Integration	None	Can edit `.bru` files directly

References

Bruno Docs: docs.usebruno.com
Bruno GitHub: github.com/usebruno/bruno
Postman Collection: api_collections/market-screener.postman_collection.json

20 KiB Raw Blame History Unescape Escape

Market Screener

Table of Contents

Developer Setup

Prerequisites

Install

Start

Environment Variables

ANTHROPIC_API_KEY — LLM news analysis (optional)

SIMPLEFIN_SETUP_TOKEN — Live bank/brokerage balances (optional)

API_KEY — Bearer token auth (optional)

CLIENT_ORIGIN — CORS allowed origin (optional)

EDGAR_USER_AGENT — SEC filings poller (recommended)

DISCORD_WEBHOOK_URL — Daily digest alerts (optional)

NEWS_PRWIRE_FEEDS — Override press-release RSS feeds (optional)

NEWS_POLL — Disable in-server news polling (optional)

Complete .env example

Commands

Running Tests

Pre-Commit & Pre-Push Hooks

Project Structure

User Guide

Screener tab

Market context strip

Signal Summary table

Per-asset detail tables

Analyze button

Search tickers

Signals explained

How scoring works

Portfolio tab

Market Calls tab

Safe Buys tab

API rate limits

API Testing with Bruno

What is Bruno?

Installing Bruno

macOS (via Homebrew)

macOS (Direct Download)

Windows

Linux (Ubuntu/Debian)

Linux (Fedora/RHEL)

Installing Bruno CLI (brucli)

macOS

Windows

Linux

Importing the API Collection

Method 1: Import via Bruno GUI (Easiest)

Method 2: Import via Bruno CLI

Method 3: Convert Postman to Bruno Format (Manual)

Running Tests

Via Bruno GUI

Via Bruno CLI (brucli)

Collection Structure

Configuration

Setting Variables

Environment Files

Common Workflows

1. Test the full API flow

2. Test just the Screener endpoints

3. Test and save results

4. Continuous testing (while developing)

Troubleshooting

"You can run only at the root of a collection" error

Variables not found

Tests failing with "undefined" errors

Postman vs Bruno

References

20 KiB

Raw Blame History

`ANTHROPIC_API_KEY` — LLM news analysis (optional)

`SIMPLEFIN_SETUP_TOKEN` — Live bank/brokerage balances (optional)

`API_KEY` — Bearer token auth (optional)

`CLIENT_ORIGIN` — CORS allowed origin (optional)

`EDGAR_USER_AGENT` — SEC filings poller (recommended)

`DISCORD_WEBHOOK_URL` — Daily digest alerts (optional)

`NEWS_PRWIRE_FEEDS` — Override press-release RSS feeds (optional)

`NEWS_POLL` — Disable in-server news polling (optional)

Complete `.env` example