# utsapoddar/alpha-digest architecture

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

- Interactive diagram: https://gitdiagram.com/utsapoddar/alpha-digest
- Repository: https://github.com/utsapoddar/alpha-digest
- Video tour (about a minute): https://gitdiagram.com/utsapoddar/alpha-digest/video

## Overview

Alpha Digest’s main workflow loads a tracked-entity watchlist, gathers SEC filings, market data, and news, enriches that evidence, generates structured summaries, then renders and distributes an email and archived web issue. The README documents the major source and delivery capabilities; sampled source confirms the coordinator and several implementations, while some fetcher and configuration wiring is represented only at the documented capability level.

Main entry points: [`main.py`](https://github.com/utsapoddar/alpha-digest/blob/main/main.py) (Pipeline coordinator), [`digest/fetchers/feeds.py`](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/feeds.py) (Configured feeds), [`digest/summarizer.py`](https://github.com/utsapoddar/alpha-digest/blob/main/digest/summarizer.py) (Structured summarizer), [`digest/fetchers/sec_edgar.py`](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/sec_edgar.py) (SEC filings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Run coordination"]
  node_main["Pipeline coordinator<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_watchlist["Entity watchlist<br/>[watchlist.csv]"]
  node_sourceconfig["Source switches<br/>[sources.yaml]"]
  node_runstate[("Run boundary state<br/>[main.py]")]
end

subgraph group_evidence["Evidence collection"]
  node_sec["SEC filings<br/>[sec_edgar.py]"]
  node_crypto["Crypto treasury<br/>[crypto.py]"]
  node_commodities["Commodity moves<br/>[commodities.py]"]
  node_news["Entity news<br/>[news.py]"]
  node_feeds["Configured feeds<br/>[feeds.py]"]
  node_feedconfig["Feed sources<br/>[feeds.csv]"]
end

subgraph group_analysis["Enrichment and analysis"]
  node_enrich["Evidence enrichment<br/>[context.py]"]
  node_summarizer["Structured summarizer<br/>[summarizer.py]"]
end

subgraph group_delivery["Issue delivery"]
  node_renderer["Email and web rendering<br/>[renderer.py]"]
  node_templates["Digest templates"]
  node_notifier["Email delivery<br/>[notifier.py]"]
  node_publisher["Archive publisher<br/>[publisher.py]"]
end

node_schedule(("Weekly schedule"))
node_secservice["SEC EDGAR"]
node_coingecko["CoinGecko"]
node_yahoo["Yahoo Finance"]
node_googlenews["Google News"]
node_rss["RSS providers"]
node_gemini["Gemini models"]
node_nvidia["NVIDIA NIM"]
node_gmail["Gmail SMTP"]
node_pages["GitHub Pages"]

node_schedule -->|"starts run"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"reads switches"| node_sourceconfig
node_main -->|"loads entities"| node_watchlist
node_main -->|"reads and saves"| node_runstate
node_main -->|"calls fetcher"| node_sec
node_main -->|"calls fetcher"| node_crypto
node_main -->|"calls fetcher"| node_commodities
node_main -->|"calls fetcher"| node_news
node_main -->|"calls fetcher"| node_feeds
node_sec -->|"requests filings"| node_secservice
node_crypto -->|"requests treasury data"| node_coingecko
node_commodities -->|"requests price data"| node_yahoo
node_news -->|"fetches headlines"| node_googlenews
node_feeds -->|"reads sources"| node_feedconfig
node_feeds -->|"fetches headlines"| node_rss
node_main -->|"passes evidence"| node_enrich
node_main -->|"submits enriched data"| node_summarizer
node_summarizer -.->|"tries models"| node_gemini
node_summarizer -.->|"falls back"| node_nvidia
node_main -->|"renders summary"| node_renderer
node_renderer -->|"renders with"| node_templates
node_main -->|"sends email edition"| node_notifier
node_notifier -->|"delivers message"| node_gmail
node_main -->|"publishes web edition"| node_publisher
node_publisher -->|"updates archive"| node_pages

click node_main "https://github.com/utsapoddar/alpha-digest/blob/main/main.py"
click node_config "https://github.com/utsapoddar/alpha-digest/blob/main/digest/config.py"
click node_watchlist "https://github.com/utsapoddar/alpha-digest/blob/main/watchlist.csv"
click node_sourceconfig "https://github.com/utsapoddar/alpha-digest/blob/main/config/sources.yaml"
click node_sec "https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/sec_edgar.py"
click node_crypto "https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/crypto.py"
click node_commodities "https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/commodities.py"
click node_news "https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/news.py"
click node_feeds "https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/feeds.py"
click node_feedconfig "https://github.com/utsapoddar/alpha-digest/blob/main/config/feeds.csv"
click node_enrich "https://github.com/utsapoddar/alpha-digest/blob/main/digest/enrichers/context.py"
click node_summarizer "https://github.com/utsapoddar/alpha-digest/blob/main/digest/summarizer.py"
click node_renderer "https://github.com/utsapoddar/alpha-digest/blob/main/digest/renderer.py"
click node_templates "https://github.com/utsapoddar/alpha-digest/tree/main/templates"
click node_notifier "https://github.com/utsapoddar/alpha-digest/blob/main/digest/notifier.py"
click node_publisher "https://github.com/utsapoddar/alpha-digest/blob/main/digest/publisher.py"
click node_runstate "https://github.com/utsapoddar/alpha-digest/blob/main/main.py"

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_main,node_config,node_watchlist,node_sourceconfig,node_runstate toneBlue
class node_sec,node_crypto,node_commodities,node_news,node_feeds,node_feedconfig toneAmber
class node_enrich,node_summarizer toneMint
class node_renderer,node_templates,node_notifier,node_publisher toneRose
class node_schedule,node_secservice,node_coingecko,node_yahoo,node_googlenews,node_rss,node_gemini,node_nvidia,node_gmail,node_pages toneIndigo
```

## Components

### Run coordination

- [Pipeline coordinator](https://github.com/utsapoddar/alpha-digest/blob/main/main.py): `main.py`
- [Runtime configuration](https://github.com/utsapoddar/alpha-digest/blob/main/digest/config.py): `digest/config.py`
- [Entity watchlist](https://github.com/utsapoddar/alpha-digest/blob/main/watchlist.csv): `watchlist.csv`
- [Source switches](https://github.com/utsapoddar/alpha-digest/blob/main/config/sources.yaml): `config/sources.yaml`
- [Run boundary state](https://github.com/utsapoddar/alpha-digest/blob/main/main.py): `main.py`

### Evidence collection

- [SEC filings](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/sec_edgar.py): `digest/fetchers/sec_edgar.py`
- [Crypto treasury](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/crypto.py): `digest/fetchers/crypto.py`
- [Commodity moves](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/commodities.py): `digest/fetchers/commodities.py`
- [Entity news](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/news.py): `digest/fetchers/news.py`
- [Configured feeds](https://github.com/utsapoddar/alpha-digest/blob/main/digest/fetchers/feeds.py): `digest/fetchers/feeds.py`
- [Feed sources](https://github.com/utsapoddar/alpha-digest/blob/main/config/feeds.csv): `config/feeds.csv`

### Enrichment and analysis

- [Evidence enrichment](https://github.com/utsapoddar/alpha-digest/blob/main/digest/enrichers/context.py): `digest/enrichers/context.py`
- [Structured summarizer](https://github.com/utsapoddar/alpha-digest/blob/main/digest/summarizer.py): `digest/summarizer.py`

### Issue delivery

- [Email and web rendering](https://github.com/utsapoddar/alpha-digest/blob/main/digest/renderer.py): `digest/renderer.py`
- [Digest templates](https://github.com/utsapoddar/alpha-digest/tree/main/templates): `templates`
- [Email delivery](https://github.com/utsapoddar/alpha-digest/blob/main/digest/notifier.py): `digest/notifier.py`
- [Archive publisher](https://github.com/utsapoddar/alpha-digest/blob/main/digest/publisher.py): `digest/publisher.py`

### Other components

- **Weekly schedule**
- **SEC EDGAR**
- **CoinGecko**
- **Yahoo Finance**
- **Google News**
- **RSS providers**
- **Gemini models**
- **NVIDIA NIM**
- **Gmail SMTP**
- **GitHub Pages**

## Connections

- Weekly schedule → Pipeline coordinator: starts run
- Pipeline coordinator → Runtime configuration: loads settings
- Pipeline coordinator → Source switches: reads switches
- Pipeline coordinator → Entity watchlist: loads entities
- Pipeline coordinator → Run boundary state: reads and saves
- Pipeline coordinator → SEC filings: calls fetcher
- Pipeline coordinator → Crypto treasury: calls fetcher
- Pipeline coordinator → Commodity moves: calls fetcher
- Pipeline coordinator → Entity news: calls fetcher
- Pipeline coordinator → Configured feeds: calls fetcher
- SEC filings → SEC EDGAR: requests filings
- Crypto treasury → CoinGecko: requests treasury data
- Commodity moves → Yahoo Finance: requests price data
- Entity news → Google News: fetches headlines
- Configured feeds → Feed sources: reads sources
- Configured feeds → RSS providers: fetches headlines
- Pipeline coordinator → Evidence enrichment: passes evidence
- Pipeline coordinator → Structured summarizer: submits enriched data
- Structured summarizer → Gemini models: tries models
- Structured summarizer → NVIDIA NIM: falls back
- Pipeline coordinator → Email and web rendering: renders summary
- Email and web rendering → Digest templates: renders with
- Pipeline coordinator → Email delivery: sends email edition
- Email delivery → Gmail SMTP: delivers message
- Pipeline coordinator → Archive publisher: publishes web edition
- Archive publisher → GitHub Pages: updates archive