Event Lens

Event Lens is a public research prototype that connects one year of US equity prices with company disclosures, company news, macro context, and measured market response.

Live demo: https://event-lens-stocks.amoshu250.chatgpt.site/

Product brief: Design decisions and approach

Event Lens reports observed associations, not causal conclusions. It is a research demonstration and not investment advice.

What the product does

1. Accepts a US stock ticker or company name, with SEC-based autocomplete.
2. Displays one year of daily prices on an interactive, zoomable chart.
3. Places SEC filings, company news, Federal Reserve events, and unmatched price turns directly on the price series.
4. Lets the user select any event and inspect the original evidence.
5. Calculates the event-aligned stock move, broad-market and sector-relative performance, volume surprise, surrounding price context, and a materiality score.
6. Summarizes what happened and clearly separates association from causation.

Reasoning and approach

A chronological news list does not answer the most useful research question: which events were close to the price moves that deserve attention? Event Lens therefore starts from the price series, identifies significant windows across the full year, and searches for evidence near those windows.

The pipeline is:

ticker
  -> price, benchmark, and company metadata
  -> significant price windows
  -> SEC, company-news, macro, and unmatched-turn candidates
  -> date alignment and market-impact calculation
  -> relevance filtering, deduplication, ranking, and visualization

Product flow

1. Search by company name or exact US ticker. Autocomplete uses the SEC issuer directory.
2. Click a filing, news, macro, or unmatched-turn marker on the one-year price chart.
3. Read the selected event and open its original public source.
4. Review a dedicated impact panel with metric definitions and a plain-language interpretation.
5. Browse news evidence separately from impact analysis; inspect official filings in a secondary disclosure table.

Event selection

• The user can divide the one-year price series into 4, 6, 8, 10, or 12 segments; eight is the balanced default. The strongest move or reversal in each segment becomes a target window.
• Finnhub company news is queried sequentially around the selected number of windows to respect rate limits. Headlines must directly match the ticker, issuer name, or an explicit brand alias.
• The minimum accepted historical coverage scales with the selected number of windows, preventing narrow recent-only results from being presented as annual coverage.
• Results are deduplicated and distributed across price windows before any window receives a second story. The chart shows at most one story per date and two per window. Stories are ranked by event type, proximity to a significant move, observed price response, and volume surprise. The display limit is eight stories for 4-8 windows, ten for 10 windows, and twelve for 12 windows.
• SEC forms such as 8-K, 10-Q, and 10-K provide official company evidence.
• Federal Reserve releases add macro context.
• A reversal detector labels large local turns that do not have a nearby high-confidence catalyst. These remain explicitly unmatched rather than being assigned a speculative cause.

Analysis metrics

• Event close: close on the first trading session on or after the event date.
• T+1 stock return: first aligned close versus the previous session close.
• T+1 and T+3 versus SPY: stock return minus the broad-market ETF over the same window.
• T+1 versus sector ETF: stock return minus the configured sector benchmark.
• Volume surprise: event-session volume divided by the prior 20-session average.
• Pre-event five-day move: context for possible anticipation or pre-existing momentum.
• Post-event five-day move: raw stock movement through five aligned sessions.
• Materiality score: a relative ranking index combining source weight, response size, persistence, and volume; it is not a probability.

Data sources

Layer	Primary source	Resilience and use
Prices and volume	Yahoo Finance chart endpoint	Two Yahoo hosts are attempted; six-hour in-memory cache
Filings and search	SEC EDGAR	Official submissions and issuer directory
Company news	Finnhub Company News	Price-window queries, company-title validation, six-hour fresh cache, 30-day stale cache
News fallbacks	Google News RSS, then Yahoo Finance RSS	Bounded historical fallback, followed by an honestly labeled recent-only fallback
Macro context	Federal Reserve monetary-policy RSS	Official FOMC and monetary-policy releases
Benchmarks	SPY and selected SPDR sector ETFs	Broad-market and sector-relative calculations

Reliability choices

• Provider requests use explicit timeouts and bounded fallback paths.
• Finnhub requests are rate-limited and retried once after a 429 response.
• Historical news is cached for fast repeat analysis and retained as stale coverage during temporary provider outages.
• Cache keys and client versions are changed when response semantics change, preventing stale results from crossing deployments.
• Source labels in the UI reveal whether the result is live, cached, historical fallback, or recent-only fallback.
• Every selected event is aligned to a real trading session before metrics are shown.

Technology

• Next.js 16, React 19, TypeScript, and vinext
• Cloudflare Workers-compatible server output
• Server-side provider orchestration and caching
• Responsive SVG price chart with accessible event markers

Run locally

Requirements: Node.js 22.13 or newer and a Finnhub API key.

npm install
cp .env.example .env.local
npm run dev

Set the following values in .env.local:

FINNHUB_API_KEY=your_key_here
SEC_USER_AGENT=StockEventLens/1.0 your_email@example.com

Never commit .env.local. The repository includes only .env.example.

Validation

npm run lint
npx tsc --noEmit
npm test

The automated suite covers rendering, stale-response prevention, news-provider ordering, caching behavior, historical coverage, ticker relevance, event reconciliation, and character-encoding regressions. The deployed application was also tested with both Quick Pick and non-Quick Pick tickers, including AAPL, KO, IBM, GOOGL, and AMD.

Project structure

app/
  api/                     API routes for analysis and ticker search
  components/              Interactive chart
  lib/                     Data acquisition, event selection, and impact logic
  StockEventDashboardV2.tsx Product UI
tests/                     Regression and resilience tests
docs/                      Product brief

Limitations

• News discovery quality depends on third-party provider coverage and licensing.
• Event proximity and abnormal returns show association, not proof of causation.
• Unclassified tickers use SPY when a sector ETF is not configured.
• The first uncached analysis for a ticker can take approximately 10 to 15 seconds because historical news calls are deliberately rate-limited.
• This prototype uses public endpoints and should receive provider-term, monitoring, and observability review before commercial use.