# samgozman/fin-thread architecture

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

- Interactive diagram: https://gitdiagram.com/samgozman/fin-thread
- Repository: https://github.com/samgozman/fin-thread

## Overview

FinThread aggregates financial news and autonomously turns it into Telegram posts. Scheduled jobs coordinate the main news workflow—fetching provider articles, filtering and composing them with AI, checking for duplicates, storing results, and publishing—and separately handle calendar reporting, event updates, and news summaries. The README also documents stock detection and multiple AI providers. Evidence is strongest for the sampled news and calendar paths; some capability nodes and integrations are based on README documentation or source-index references rather than inspected implementation.

Main entry points: [`jobs/job.go`](https://github.com/samgozman/fin-thread/blob/main/jobs/job.go) (News job), [`app.go`](https://github.com/samgozman/fin-thread/blob/main/app.go) (Job scheduler), [`jobs/summary.go`](https://github.com/samgozman/fin-thread/blob/main/jobs/summary.go) (Summary job), [`jobs/calendar.go`](https://github.com/samgozman/fin-thread/blob/main/jobs/calendar.go) (Calendar jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Scheduling and jobs"]
  node_scheduler["Job scheduler<br/>[app.go]"]
  node_news_job["News job<br/>[job.go]"]
  node_summary_job["Summary job<br/>[summary.go]"]
  node_calendar_job["Calendar jobs<br/>[calendar.go]"]
end

subgraph group_news["News processing"]
  node_composer["AI filtering and composition<br/>[composer.go]"]
  node_ai_clients["AI clients<br/>[clients.go]"]
  node_publisher["Telegram publishing<br/>[publisher.go]"]
  node_summary["News summarization<br/>[composer.go]"]
end

subgraph group_data["Sources and persistence"]
  node_journalist["News collection<br/>[news.go]"]
  node_stock_screener["Stock detection<br/>[stocks.go]"]
  node_archivist["News and event archive<br/>[News.go]"]
end

subgraph group_calendar["Calendar reporting"]
  node_calendar_scavenger["Calendar retrieval<br/>[ecal.go]"]
end

node_operator(("Channel operator"))
node_rss(("News providers"))
node_postgres[("PostgreSQL")]
node_telegram(("Telegram channel"))
node_calendar_source(("Economic calendar source"))
node_market_data(("Stock data source"))

node_operator -->|"runs service"| node_scheduler
node_scheduler -->|"schedules"| node_news_job
node_scheduler -->|"schedules"| node_calendar_job
node_news_job -->|"fetches articles"| node_journalist
node_rss -->|"provides feeds"| node_journalist
node_news_job -->|"filters and composes"| node_composer
node_composer -->|"requests completions"| node_ai_clients
node_ai_clients -.->|"calls AI services"| node_operator
node_news_job -.->|"uses stock data"| node_stock_screener
node_stock_screener -->|"fetches listings"| node_market_data
node_news_job -->|"reads and writes news"| node_archivist
node_archivist -.->|"persists records"| node_postgres
node_news_job -->|"publishes posts"| node_publisher
node_publisher -->|"sends messages"| node_telegram
node_scheduler -.->|"schedules"| node_summary_job
node_summary_job -.->|"requests summaries"| node_composer
node_summary_job -.->|"retrieves news"| node_archivist
node_summary_job -.->|"publishes summary"| node_publisher
node_calendar_job -->|"fetches events"| node_calendar_scavenger
node_calendar_scavenger -->|"requests events"| node_calendar_source
node_calendar_job -->|"stores and updates"| node_archivist
node_calendar_job -->|"publishes updates"| node_publisher

click node_scheduler "https://github.com/samgozman/fin-thread/blob/main/app.go"
click node_news_job "https://github.com/samgozman/fin-thread/blob/main/jobs/job.go"
click node_summary_job "https://github.com/samgozman/fin-thread/blob/main/jobs/summary.go"
click node_calendar_job "https://github.com/samgozman/fin-thread/blob/main/jobs/calendar.go"
click node_journalist "https://github.com/samgozman/fin-thread/blob/main/journalist/news.go"
click node_composer "https://github.com/samgozman/fin-thread/blob/main/composer/composer.go"
click node_ai_clients "https://github.com/samgozman/fin-thread/blob/main/composer/clients.go"
click node_stock_screener "https://github.com/samgozman/fin-thread/blob/main/scavenger/stocks/stocks.go"
click node_archivist "https://github.com/samgozman/fin-thread/blob/main/archivist/News.go"
click node_publisher "https://github.com/samgozman/fin-thread/blob/main/publisher/publisher.go"
click node_calendar_scavenger "https://github.com/samgozman/fin-thread/blob/main/scavenger/ecal/ecal.go"
click node_summary "https://github.com/samgozman/fin-thread/blob/main/composer/composer.go"

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_scheduler,node_news_job,node_summary_job,node_calendar_job toneBlue
class node_composer,node_ai_clients,node_publisher,node_summary,node_postgres toneAmber
class node_journalist,node_stock_screener,node_archivist toneMint
class node_calendar_scavenger toneRose
class node_operator,node_rss,node_telegram,node_calendar_source,node_market_data toneIndigo
```

## Components

### Scheduling and jobs

- [Job scheduler](https://github.com/samgozman/fin-thread/blob/main/app.go): `app.go`
- [News job](https://github.com/samgozman/fin-thread/blob/main/jobs/job.go): `jobs/job.go`
- [Summary job](https://github.com/samgozman/fin-thread/blob/main/jobs/summary.go): `jobs/summary.go`
- [Calendar jobs](https://github.com/samgozman/fin-thread/blob/main/jobs/calendar.go): `jobs/calendar.go`

### News processing

- [AI filtering and composition](https://github.com/samgozman/fin-thread/blob/main/composer/composer.go): `composer/composer.go`
- [AI clients](https://github.com/samgozman/fin-thread/blob/main/composer/clients.go): `composer/clients.go`
- [Telegram publishing](https://github.com/samgozman/fin-thread/blob/main/publisher/publisher.go): `publisher/publisher.go`
- [News summarization](https://github.com/samgozman/fin-thread/blob/main/composer/composer.go): `composer/composer.go`

### Sources and persistence

- [News collection](https://github.com/samgozman/fin-thread/blob/main/journalist/news.go): `journalist/news.go`
- [Stock detection](https://github.com/samgozman/fin-thread/blob/main/scavenger/stocks/stocks.go): `scavenger/stocks/stocks.go`
- [News and event archive](https://github.com/samgozman/fin-thread/blob/main/archivist/News.go): `archivist/News.go`

### Calendar reporting

- [Calendar retrieval](https://github.com/samgozman/fin-thread/blob/main/scavenger/ecal/ecal.go): `scavenger/ecal/ecal.go`

### Other components

- **Channel operator**
- **News providers**
- **PostgreSQL**
- **Telegram channel**
- **Economic calendar source**
- **Stock data source**

## Connections

- Channel operator → Job scheduler: runs service (evidence: `README.md`)
- Job scheduler → News job: schedules (evidence: `app.go`)
- Job scheduler → Calendar jobs: schedules (evidence: `app.go`)
- News job → News collection: fetches articles (evidence: `jobs/job.go`)
- News providers → News collection: provides feeds (evidence: `README.md`)
- News job → AI filtering and composition: filters and composes (evidence: `jobs/job.go`)
- AI filtering and composition → AI clients: requests completions (evidence: `composer/composer.go`)
- AI clients → Channel operator: calls AI services
- News job → Stock detection: uses stock data
- Stock detection → Stock data source: fetches listings (evidence: `scavenger/stocks/stocks.go`)
- News job → News and event archive: reads and writes news (evidence: `jobs/job.go`)
- News and event archive → PostgreSQL: persists records
- News job → Telegram publishing: publishes posts (evidence: `jobs/job.go`)
- Telegram publishing → Telegram channel: sends messages (evidence: `publisher/publisher.go`)
- Job scheduler → Summary job: schedules
- Summary job → AI filtering and composition: requests summaries
- Summary job → News and event archive: retrieves news
- Summary job → Telegram publishing: publishes summary
- Calendar jobs → Calendar retrieval: fetches events (evidence: `jobs/calendar.go`)
- Calendar retrieval → Economic calendar source: requests events (evidence: `scavenger/ecal/ecal.go`)
- Calendar jobs → News and event archive: stores and updates (evidence: `jobs/calendar.go`)
- Calendar jobs → Telegram publishing: publishes updates (evidence: `jobs/calendar.go`)
