# mihai918/breaking_news architecture

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

- Interactive diagram: https://gitdiagram.com/mihai918/breaking_news
- Repository: https://github.com/mihai918/breaking_news

## Overview

This repository implements an automated breaking-news monitor that filters regional and global RSS items and delivers urgent alerts to Telegram. Its main flow is feed retrieval, recency/source checks, urgency scoring and deduplication, then alert formatting and delivery through the authenticated Telegram API; a separate authenticated MCP endpoint also offers health and send tools. The UI remains the unmodified Next.js starter page. The monitor implementation is sampled; the scheduled workflow details and protected-resource route implementation were not, so their behavior is not expanded here.

Main entry points: [`scripts/monitor-news.mjs`](https://github.com/mihai918/breaking_news/blob/main/scripts/monitor-news.mjs) (Feed monitor), [`app/api/mcp/route.ts`](https://github.com/mihai918/breaking_news/blob/main/app/api/mcp/route.ts) (MCP tools), [`app/api/telegram/route.ts`](https://github.com/mihai918/breaking_news/blob/main/app/api/telegram/route.ts) (Alert endpoint), [`.github/workflows/breaking-news-monitor.yml`](https://github.com/mihai918/breaking_news/blob/main/.github/workflows/breaking-news-monitor.yml) (Scheduled workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitor["News monitoring"]
  node_monitor["Feed monitor<br/>[monitor-news.mjs]"]
  node_state[("Sent-item state")]
end

subgraph group_delivery["Telegram delivery"]
  node_telegram_api["Alert endpoint<br/>[route.ts]"]
end

subgraph group_mcp["MCP access"]
  node_mcp_endpoint["MCP tools<br/>[route.ts]"]
  node_resource_metadata["OAuth metadata route<br/>[route.ts]"]
end

node_scheduler(("Scheduled workflow"))
node_feed_sources["RSS feeds"]
node_telegram["Telegram Bot API"]
node_mcp_client(("MCP client"))
node_auth0["Auth0 JWKS"]

node_scheduler -->|"runs"| node_monitor
node_monitor -->|"fetches feeds"| node_feed_sources
node_monitor -->|"reads and writes"| node_state
node_monitor -->|"posts alert"| node_telegram_api
node_telegram_api -->|"sends message"| node_telegram
node_mcp_client -->|"calls tools"| node_mcp_endpoint
node_mcp_endpoint -->|"verifies JWT"| node_auth0
node_mcp_endpoint -.->|"sets metadata path"| node_resource_metadata
node_mcp_endpoint -->|"sends message"| node_telegram

click node_scheduler "https://github.com/mihai918/breaking_news/blob/main/.github/workflows/breaking-news-monitor.yml"
click node_monitor "https://github.com/mihai918/breaking_news/blob/main/scripts/monitor-news.mjs"
click node_state "https://github.com/mihai918/breaking_news/blob/main/data/breaking-news-state.json"
click node_telegram_api "https://github.com/mihai918/breaking_news/blob/main/app/api/telegram/route.ts"
click node_mcp_endpoint "https://github.com/mihai918/breaking_news/blob/main/app/api/mcp/route.ts"
click node_resource_metadata "https://github.com/mihai918/breaking_news/blob/main/app/.well-known/oauth-protected-resource/route.ts"

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_monitor,node_state,node_mcp_client toneBlue
class node_telegram_api toneAmber
class node_mcp_endpoint,node_resource_metadata,node_telegram toneMint
class node_scheduler toneTeal
class node_feed_sources,node_auth0 toneIndigo
```

## Components

### News monitoring

- [Feed monitor](https://github.com/mihai918/breaking_news/blob/main/scripts/monitor-news.mjs): `scripts/monitor-news.mjs`
- [Sent-item state](https://github.com/mihai918/breaking_news/blob/main/data/breaking-news-state.json): `data/breaking-news-state.json`

### Telegram delivery

- [Alert endpoint](https://github.com/mihai918/breaking_news/blob/main/app/api/telegram/route.ts): `app/api/telegram/route.ts`

### MCP access

- [MCP tools](https://github.com/mihai918/breaking_news/blob/main/app/api/mcp/route.ts): `app/api/mcp/route.ts`
- [OAuth metadata route](https://github.com/mihai918/breaking_news/blob/main/app/.well-known/oauth-protected-resource/route.ts): `app/.well-known/oauth-protected-resource/route.ts`

### Other components

- [Scheduled workflow](https://github.com/mihai918/breaking_news/blob/main/.github/workflows/breaking-news-monitor.yml): `.github/workflows/breaking-news-monitor.yml`
- **RSS feeds**
- **Telegram Bot API**
- **MCP client**
- **Auth0 JWKS**

## Connections

- Scheduled workflow → Feed monitor: runs
- Feed monitor → RSS feeds: fetches feeds
- Feed monitor → Sent-item state: reads and writes
- Feed monitor → Alert endpoint: posts alert
- Alert endpoint → Telegram Bot API: sends message
- MCP client → MCP tools: calls tools
- MCP tools → Auth0 JWKS: verifies JWT
- MCP tools → OAuth metadata route: sets metadata path
- MCP tools → Telegram Bot API: sends message