# nickr145/news-edge architecture

> Architecture diagram of the GitHub repository nickr145/news-edge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nickr145/news-edge
- Repository: https://github.com/nickr145/news-edge

## Overview

NewsEdge turns public market news into watchlist sentiment, event-aware relevance and grouping, risk metrics, and a horizon-based direction heuristic. The web and iOS clients implement that workflow independently on-device: search or choose a ticker, fetch and retain news and price history, compute analytics, then present charts, risk, predictions, and a news feed. The web routes source requests through an allow-listed proxy; iOS calls sources directly and can score sentiment with Core ML FinBERT. The widget is a separate iOS presentation path. Some iOS screens and widget implementation details are unsampled, so their links follow README documentation.

Main entry points: [`frontend/src/lib/local/client.js`](https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/client.js) (Local API), [`ios/NewsEdge/NewsEdge/Networking/APIClient.swift`](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/APIClient.swift) (On-device API), [`ios/NewsEdge/NewsEdge/Networking/YahooClient.swift`](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/YahooClient.swift) (Yahoo client), [`ios/NewsEdge/NewsEdge/Stores/NewsStore.swift`](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Stores/NewsStore.swift) (News accrual)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_search["Ticker search<br/>[TickerSearch.jsx]"]
  node_watchlist[("Web watchlist<br/>[useWatchlist.js]")]
  node_ticker_page["Ticker detail<br/>[TickerPage.jsx]"]
  node_web_views["Analysis panels"]
end

subgraph group_webdata["Web data and analytics"]
  node_web_api["Local API<br/>[client.js]"]
  node_web_sources["Source adapters<br/>[sources.js]"]
  node_web_news["News quality<br/>[news.js]"]
  node_web_analytics["Sentiment analytics<br/>[analytics.js]"]
  node_web_store[("Browser article cache<br/>[client.js]")]
  node_proxy["Vercel proxy<br/>[proxy.mjs]"]
end

subgraph group_ios["iOS client"]
  node_ios_search["Search and watchlist<br/>[SearchScreen.swift]"]
  node_ios_detail["Ticker detail<br/>[TickerScreen.swift]"]
  node_ios_views["Ticker analysis views"]
end

subgraph group_iosdata["iOS data and analytics"]
  node_api_client["On-device API<br/>[APIClient.swift]"]
  node_news_store[("News accrual<br/>[NewsStore.swift]")]
  node_events["Event relevance<br/>[NewsEvents.swift]"]
  node_ios_analytics["Local analytics<br/>[Analytics.swift]"]
  node_finbert["FinBERT scorer"]
  node_model_store[("Model store")]
  node_yahoo_client["Yahoo client<br/>[YahooClient.swift]"]
  node_google_client["Google News client"]
end

subgraph group_widget["iOS widget"]
  node_widget_view["Watchlist widget"]
  node_widget_client["Widget sentiment client"]
end

node_web_user(("Web user"))
node_yahoo{{"Yahoo Finance"}}
node_google_news{{"Google News RSS"}}
node_web_user2(("Web reader"))
node_ios_user(("iOS user"))
node_nasdaq{{"Nasdaq quotes"}}
node_widget_reader(("Widget reader"))

node_web_user -->|"searches"| node_search
node_search -->|"opens ticker"| node_ticker_page
node_web_user -->|"curates"| node_watchlist
node_watchlist -->|"selects ticker"| node_ticker_page
node_ticker_page -->|"requests data"| node_web_api
node_web_api -->|"fetches sources"| node_web_sources
node_web_api -->|"groups news"| node_web_news
node_web_api -->|"computes metrics"| node_web_analytics
node_web_api -->|"reads and writes"| node_web_store
node_web_sources -->|"requests proxy"| node_proxy
node_proxy -->|"forwards requests"| node_yahoo
node_web_sources -->|"fetches RSS"| node_google_news
node_web_api -->|"returns analysis"| node_web_views
node_web_views -->|"presents results"| node_web_user2
node_ios_user -->|"searches"| node_ios_search
node_ios_search -.->|"opens ticker"| node_ios_detail
node_ios_detail -.->|"requests analysis"| node_api_client
node_api_client -->|"loads articles"| node_news_store
node_news_store -->|"fetches headlines"| node_yahoo_client
node_news_store -->|"backfills history"| node_google_client
node_news_store -->|"scores headlines"| node_finbert
node_api_client -->|"filters events"| node_events
node_api_client -->|"computes metrics"| node_ios_analytics
node_api_client -->|"loads price bars"| node_yahoo_client
node_yahoo_client -->|"fetches market data"| node_yahoo
node_yahoo_client -->|"falls back"| node_nasdaq
node_google_client -->|"fetches RSS"| node_google_news
node_model_store -->|"provides model"| node_finbert
node_api_client -.->|"supplies results"| node_ios_views
node_ios_views -->|"presents results"| node_ios_user
node_widget_reader -->|"views sentiment"| node_widget_view
node_widget_view -.->|"loads watchlist data"| node_widget_client
node_widget_client -.->|"fetches news"| node_yahoo_client
node_widget_client -->|"computes EWMA"| node_ios_analytics

click node_search "https://github.com/nickr145/news-edge/blob/main/frontend/src/components/TickerSearch.jsx"
click node_watchlist "https://github.com/nickr145/news-edge/blob/main/frontend/src/hooks/useWatchlist.js"
click node_ticker_page "https://github.com/nickr145/news-edge/blob/main/frontend/src/pages/TickerPage.jsx"
click node_web_views "https://github.com/nickr145/news-edge/tree/main/frontend/src/components"
click node_web_api "https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/client.js"
click node_web_sources "https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/sources.js"
click node_web_news "https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/news.js"
click node_web_analytics "https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/analytics.js"
click node_web_store "https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/client.js"
click node_proxy "https://github.com/nickr145/news-edge/blob/main/api/proxy.mjs"
click node_ios_search "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Screens/SearchScreen.swift"
click node_ios_detail "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Screens/TickerScreen.swift"
click node_api_client "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/APIClient.swift"
click node_news_store "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Stores/NewsStore.swift"
click node_events "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Services/NewsEvents.swift"
click node_ios_analytics "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/Shared/Analytics.swift"
click node_finbert "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/Shared/FinBERTScorer.swift"
click node_model_store "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Services/FinBERTModelStore.swift"
click node_yahoo_client "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/YahooClient.swift"
click node_google_client "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/GoogleNewsClient.swift"
click node_ios_views "https://github.com/nickr145/news-edge/tree/main/ios/NewsEdge/NewsEdge/Views"
click node_widget_view "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdgeWidget/WatchlistSentimentWidget.swift"
click node_widget_client "https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdgeWidget/WidgetSentimentClient.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_search,node_watchlist,node_ticker_page,node_web_views,node_web_user,node_ios_user toneBlue
class node_web_api,node_web_sources,node_web_news,node_web_analytics,node_web_store,node_proxy toneAmber
class node_ios_search,node_ios_detail,node_ios_views toneMint
class node_api_client,node_news_store,node_events,node_ios_analytics,node_finbert,node_model_store,node_yahoo_client,node_google_client toneRose
class node_widget_view,node_widget_client,node_yahoo,node_google_news,node_web_user2,node_nasdaq,node_widget_reader toneIndigo
```

## Components

### Web client

- [Ticker search](https://github.com/nickr145/news-edge/blob/main/frontend/src/components/TickerSearch.jsx): `frontend/src/components/TickerSearch.jsx`
- [Web watchlist](https://github.com/nickr145/news-edge/blob/main/frontend/src/hooks/useWatchlist.js): `frontend/src/hooks/useWatchlist.js`
- [Ticker detail](https://github.com/nickr145/news-edge/blob/main/frontend/src/pages/TickerPage.jsx): `frontend/src/pages/TickerPage.jsx`
- [Analysis panels](https://github.com/nickr145/news-edge/tree/main/frontend/src/components): `frontend/src/components`

### Web data and analytics

- [Local API](https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/client.js): `frontend/src/lib/local/client.js`
- [Source adapters](https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/sources.js): `frontend/src/lib/local/sources.js`
- [News quality](https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/news.js): `frontend/src/lib/local/news.js`
- [Sentiment analytics](https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/analytics.js): `frontend/src/lib/local/analytics.js`
- [Browser article cache](https://github.com/nickr145/news-edge/blob/main/frontend/src/lib/local/client.js): `frontend/src/lib/local/client.js`
- [Vercel proxy](https://github.com/nickr145/news-edge/blob/main/api/proxy.mjs): `api/proxy.mjs`

### iOS client

- [Search and watchlist](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Screens/SearchScreen.swift): `ios/NewsEdge/NewsEdge/Screens/SearchScreen.swift`
- [Ticker detail](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Screens/TickerScreen.swift): `ios/NewsEdge/NewsEdge/Screens/TickerScreen.swift`
- [Ticker analysis views](https://github.com/nickr145/news-edge/tree/main/ios/NewsEdge/NewsEdge/Views): `ios/NewsEdge/NewsEdge/Views`

### iOS data and analytics

- [On-device API](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/APIClient.swift): `ios/NewsEdge/NewsEdge/Networking/APIClient.swift`
- [News accrual](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Stores/NewsStore.swift): `ios/NewsEdge/NewsEdge/Stores/NewsStore.swift`
- [Event relevance](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Services/NewsEvents.swift): `ios/NewsEdge/NewsEdge/Services/NewsEvents.swift`
- [Local analytics](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/Shared/Analytics.swift): `ios/NewsEdge/Shared/Analytics.swift`
- [FinBERT scorer](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/Shared/FinBERTScorer.swift): `ios/NewsEdge/Shared/FinBERTScorer.swift`
- [Model store](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Services/FinBERTModelStore.swift): `ios/NewsEdge/NewsEdge/Services/FinBERTModelStore.swift`
- [Yahoo client](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/YahooClient.swift): `ios/NewsEdge/NewsEdge/Networking/YahooClient.swift`
- [Google News client](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdge/Networking/GoogleNewsClient.swift): `ios/NewsEdge/NewsEdge/Networking/GoogleNewsClient.swift`

### iOS widget

- [Watchlist widget](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdgeWidget/WatchlistSentimentWidget.swift): `ios/NewsEdge/NewsEdgeWidget/WatchlistSentimentWidget.swift`
- [Widget sentiment client](https://github.com/nickr145/news-edge/blob/main/ios/NewsEdge/NewsEdgeWidget/WidgetSentimentClient.swift): `ios/NewsEdge/NewsEdgeWidget/WidgetSentimentClient.swift`

### Other components

- **Web user**
- **Yahoo Finance**
- **Google News RSS**
- **Web reader**
- **iOS user**
- **Nasdaq quotes**
- **Widget reader**

## Connections

- Web user → Ticker search: searches (evidence: `frontend/src/components/TickerSearch.jsx`)
- Ticker search → Ticker detail: opens ticker (evidence: `frontend/src/components/TickerSearch.jsx`)
- Web user → Web watchlist: curates
- Web watchlist → Ticker detail: selects ticker (evidence: `frontend/src/pages/TickerPage.jsx`)
- Ticker detail → Local API: requests data (evidence: `frontend/src/pages/TickerPage.jsx`)
- Local API → Source adapters: fetches sources (evidence: `frontend/src/lib/local/client.js`)
- Local API → News quality: groups news (evidence: `frontend/src/lib/local/client.js`)
- Local API → Sentiment analytics: computes metrics (evidence: `frontend/src/lib/local/client.js`)
- Local API → Browser article cache: reads and writes (evidence: `frontend/src/lib/local/client.js`)
- Source adapters → Vercel proxy: requests proxy
- Vercel proxy → Yahoo Finance: forwards requests
- Source adapters → Google News RSS: fetches RSS
- Local API → Analysis panels: returns analysis
- Analysis panels → Web reader: presents results
- iOS user → Search and watchlist: searches
- Search and watchlist → Ticker detail: opens ticker
- Ticker detail → On-device API: requests analysis
- On-device API → News accrual: loads articles (evidence: `ios/NewsEdge/NewsEdge/Networking/APIClient.swift`)
- News accrual → Yahoo client: fetches headlines (evidence: `ios/NewsEdge/NewsEdge/Stores/NewsStore.swift`)
- News accrual → Google News client: backfills history (evidence: `ios/NewsEdge/NewsEdge/Stores/NewsStore.swift`)
- News accrual → FinBERT scorer: scores headlines (evidence: `ios/NewsEdge/NewsEdge/Stores/NewsStore.swift`)
- On-device API → Event relevance: filters events (evidence: `ios/NewsEdge/NewsEdge/Networking/APIClient.swift`)
- On-device API → Local analytics: computes metrics (evidence: `ios/NewsEdge/NewsEdge/Networking/APIClient.swift`)
- On-device API → Yahoo client: loads price bars (evidence: `ios/NewsEdge/NewsEdge/Networking/APIClient.swift`)
- Yahoo client → Yahoo Finance: fetches market data
- Yahoo client → Nasdaq quotes: falls back
- Google News client → Google News RSS: fetches RSS
- Model store → FinBERT scorer: provides model (evidence: `ios/NewsEdge/NewsEdge/Services/FinBERTModelStore.swift`)
- On-device API → Ticker analysis views: supplies results
- Ticker analysis views → iOS user: presents results
- Widget reader → Watchlist widget: views sentiment
- Watchlist widget → Widget sentiment client: loads watchlist data
- Widget sentiment client → Yahoo client: fetches news
- Widget sentiment client → Local analytics: computes EWMA (evidence: `ios/NewsEdge/NewsEdgeWidget/WidgetSentimentClient.swift`)
