# andrewmbarros/beatles-bot architecture

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

- Interactive diagram: https://gitdiagram.com/andrewmbarros/beatles-bot
- Repository: https://github.com/andrewmbarros/beatles-bot

## Overview

Beatles Bot monitors Beatles-related news and social sources, filters and deduplicates items, then sends immediate alerts or periodic digests to Telegram. The main runtime is concentrated in one Python file: its CLI configures dry-run or Telegram delivery, while the documented deployment options run it continuously or on a schedule. The README also documents source-health alerts and persistent history. Several internal call paths are only partially excerpted, so uncertain links are omitted rather than inferred.

Main entry points: [`beatles_news.py`](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py) (Run coordinator), [`seen.json`](https://github.com/andrewmbarros/beatles-bot/blob/main/seen.json) (Seen history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Source collection"]
  node_source_catalog["46-source catalog<br/>[beatles_news.py]"]
  node_feed_collection["News and feed sources<br/>[beatles_news.py]"]
  node_social_collection["Social and forum sources<br/>[beatles_news.py]"]
  node_fetching["Due-source fetching<br/>[beatles_news.py]"]
end

subgraph group_processing["Item processing"]
  node_feed_parsing["Feed parsing<br/>[beatles_news.py]"]
  node_bluesky_parsing["Bluesky parsing<br/>[beatles_news.py]"]
  node_filtering["Filtering and labeling<br/>[beatles_news.py]"]
  node_dedup["Deduplication<br/>[beatles_news.py]"]
  node_digest["Digest assembly<br/>[beatles_news.py]"]
  node_health["Source health alerts<br/>[beatles_news.py]"]
end

subgraph group_delivery["Delivery and state"]
  node_telegram["Telegram delivery<br/>[beatles_news.py]"]
  node_history[("Seen history<br/>[seen.json]")]
end

subgraph group_runtime["Runtime"]
  node_cli["CLI modes<br/>[beatles_news.py]"]
  node_run["Run coordinator<br/>[beatles_news.py]"]
end

node_operator(("Operator"))
node_scheduler(("Deployment scheduler"))
node_telegram_api(("Telegram Bot API"))

node_operator -->|"selects mode"| node_cli
node_cli -->|"builds sources"| node_source_catalog
node_scheduler -->|"starts runs"| node_cli
node_source_catalog -->|"includes feeds"| node_feed_collection
node_source_catalog -->|"includes social"| node_social_collection
node_run -->|"fetches due"| node_fetching
node_feed_collection -.->|"provides sources"| node_fetching
node_social_collection -.->|"provides sources"| node_fetching
node_fetching -.->|"parses feeds"| node_feed_parsing
node_fetching -.->|"parses posts"| node_bluesky_parsing
node_feed_parsing -->|"filters items"| node_filtering
node_bluesky_parsing -->|"filters items"| node_filtering
node_run -->|"checks failures"| node_health
node_run -->|"checks history"| node_dedup
node_dedup -->|"records items"| node_history
node_run -->|"assembles digest"| node_digest
node_run -->|"sends alerts"| node_telegram
node_health -->|"sends outage alert"| node_telegram
node_digest -->|"sends summary"| node_telegram
node_telegram -->|"calls API"| node_telegram_api
node_cli -.->|"runs cycle"| node_run

click node_cli "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_source_catalog "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_feed_collection "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_social_collection "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_fetching "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_feed_parsing "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_bluesky_parsing "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_filtering "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_dedup "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_digest "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_health "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_run "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_telegram "https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py"
click node_history "https://github.com/andrewmbarros/beatles-bot/blob/main/seen.json"

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_source_catalog,node_feed_collection,node_social_collection,node_fetching toneBlue
class node_feed_parsing,node_bluesky_parsing,node_filtering,node_dedup,node_digest,node_health toneAmber
class node_telegram,node_history,node_telegram_api toneMint
class node_cli,node_run,node_scheduler toneRose
class node_operator toneIndigo
```

## Components

### Source collection

- [46-source catalog](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [News and feed sources](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Social and forum sources](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Due-source fetching](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`

### Item processing

- [Feed parsing](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Bluesky parsing](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Filtering and labeling](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Deduplication](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Digest assembly](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Source health alerts](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`

### Delivery and state

- [Telegram delivery](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Seen history](https://github.com/andrewmbarros/beatles-bot/blob/main/seen.json): `seen.json`

### Runtime

- [CLI modes](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`
- [Run coordinator](https://github.com/andrewmbarros/beatles-bot/blob/main/beatles_news.py): `beatles_news.py`

### Other components

- **Operator**
- **Deployment scheduler**
- **Telegram Bot API**

## Connections

- Operator → CLI modes: selects mode (evidence: `README.md`)
- CLI modes → 46-source catalog: builds sources (evidence: `beatles_news.py`)
- Deployment scheduler → CLI modes: starts runs (evidence: `README.md`)
- 46-source catalog → News and feed sources: includes feeds (evidence: `README.md`)
- 46-source catalog → Social and forum sources: includes social (evidence: `README.md`)
- Run coordinator → Due-source fetching: fetches due (evidence: `beatles_news.py`)
- News and feed sources → Due-source fetching: provides sources (evidence: `beatles_news.py`)
- Social and forum sources → Due-source fetching: provides sources (evidence: `beatles_news.py`)
- Due-source fetching → Feed parsing: parses feeds (evidence: `beatles_news.py`)
- Due-source fetching → Bluesky parsing: parses posts (evidence: `beatles_news.py`)
- Feed parsing → Filtering and labeling: filters items (evidence: `beatles_news.py`)
- Bluesky parsing → Filtering and labeling: filters items (evidence: `beatles_news.py`)
- Run coordinator → Source health alerts: checks failures (evidence: `beatles_news.py`)
- Run coordinator → Deduplication: checks history (evidence: `beatles_news.py`)
- Deduplication → Seen history: records items (evidence: `README.md`)
- Run coordinator → Digest assembly: assembles digest (evidence: `beatles_news.py`)
- Run coordinator → Telegram delivery: sends alerts (evidence: `README.md`)
- Source health alerts → Telegram delivery: sends outage alert (evidence: `README.md`)
- Digest assembly → Telegram delivery: sends summary (evidence: `README.md`)
- Telegram delivery → Telegram Bot API: calls API (evidence: `beatles_news.py`)
- CLI modes → Run coordinator: runs cycle (evidence: `beatles_news.py`)
