# sunaiworld/siddegowda-portfolio architecture

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

- Interactive diagram: https://gitdiagram.com/sunaiworld/siddegowda-portfolio
- Repository: https://github.com/sunaiworld/siddegowda-portfolio

## Overview

This repository is a stock-portfolio auto-updater: the documented product is a portfolio updater, and the sampled runtime shows a daily pipeline that builds portfolio results and writes them to Google Sheets. The tree also exposes mutual-fund, dividend, screening, snapshot, and morning-brief capabilities. Arrows are limited to relationships visible in excerpts or SOURCE INDEX references; unsampled feature internals are represented without speculative call chains.

Main entry points: [`src/main.py`](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/main.py) (Daily update), [`src/portfolio_builder.py`](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/portfolio_builder.py) (Portfolio builder), [`telegram_bot.py`](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/telegram_bot.py) (Telegram bot), [`src/news_engine/classifier.py`](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/classifier.py) (News classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Portfolio pipeline"]
  node_main["Daily update<br/>[main.py]"]
  node_trades["Trade imports"]
  node_portfolio["Portfolio builder"]
  node_mutual_funds["Mutual fund pipeline"]
end

subgraph group_analysis["Investment analysis"]
  node_prices["Market data<br/>[data_fetcher.py]"]
  node_scoring["Scoring engine<br/>[score_engine.py]"]
  node_analytics["Portfolio analytics"]
  node_fundamentals[("Fundamental cache<br/>[fund_cache.py]")]
  node_news_source["Google News RSS<br/>[google_news_rss.py]"]
  node_news_classifier["News classifier<br/>[classifier.py]"]
  node_news_cache[("News cache<br/>[news_cache.py]")]
  node_dividends["Dividend pipeline"]
  node_future_buys["Future buy builder"]
  node_growth["Growth screener"]
end

subgraph group_reporting["Sheets and reporting"]
  node_snapshots["Monthly snapshots"]
  node_brief["Morning brief"]
  node_github_data["Portfolio sheet data"]
  node_sheet_writer["Sheet writer<br/>[sheet_writer.py]"]
  node_formatter["Sheet formatter<br/>[sheet_formatter.py]"]
end

subgraph group_engagement["Bot and alerts"]
  node_bot["Telegram bot<br/>[telegram_bot.py]"]
  node_handlers["Bot handlers<br/>[handlers.py]"]
  node_sheet_state["Cached sheet state<br/>[sheets_state.py]"]
end

node_operator(("Operator / schedule"))
node_sheets[("Google Sheets")]
node_telegram(("Telegram service"))

node_operator -.->|"starts"| node_main
node_main -->|"builds holdings"| node_portfolio
node_portfolio -.->|"loads trades"| node_trades
node_main -->|"fetches prices"| node_prices
node_main -->|"scores stocks"| node_scoring
node_main -->|"computes dashboard"| node_analytics
node_portfolio -->|"uses analytics"| node_analytics
node_portfolio -->|"uses cache"| node_fundamentals
node_main -->|"fetches headlines"| node_news_source
node_main -->|"classifies news"| node_news_classifier
node_news_classifier -.->|"stores digest"| node_news_cache
node_main -->|"builds fund data"| node_mutual_funds
node_main -->|"builds dividends"| node_dividends
node_main -->|"builds buy ideas"| node_future_buys
node_main -->|"builds screener"| node_growth
node_operator -.->|"runs snapshot"| node_snapshots
node_operator -.->|"runs briefing"| node_brief
node_main -->|"builds sheet data"| node_github_data
node_main -->|"writes results"| node_sheet_writer
node_main -->|"formats sheets"| node_formatter
node_sheet_writer -.->|"writes cells"| node_sheets
node_formatter -.->|"formats cells"| node_sheets
node_telegram -->|"sends commands"| node_bot
node_bot -->|"dispatches commands"| node_handlers
node_handlers -->|"reads cached rows"| node_sheet_state
node_sheet_state -->|"reads state and data"| node_sheets
node_bot -->|"runs refresh"| node_main

click node_main "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/main.py"
click node_trades "https://github.com/sunaiworld/siddegowda-portfolio/tree/main/data/imports"
click node_portfolio "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/portfolio_builder.py"
click node_prices "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/data_fetcher.py"
click node_scoring "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/score_engine.py"
click node_analytics "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/portfolio_analytics.py"
click node_fundamentals "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/fund_cache.py"
click node_news_source "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/sources/google_news_rss.py"
click node_news_classifier "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/classifier.py"
click node_news_cache "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/news_cache.py"
click node_mutual_funds "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/mutual_fund_builder.py"
click node_dividends "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/dividend_builder.py"
click node_future_buys "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/future_buy_builder.py"
click node_growth "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/growth_screener_builder.py"
click node_snapshots "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/monthly_snapshot.py"
click node_brief "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/morning_brief_builder.py"
click node_github_data "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/github_data_builder.py"
click node_sheet_writer "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/sheet_writer.py"
click node_formatter "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/sheet_formatter.py"
click node_bot "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/telegram_bot.py"
click node_handlers "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/handlers.py"
click node_sheet_state "https://github.com/sunaiworld/siddegowda-portfolio/blob/main/services/sheets_state.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_trades,node_portfolio,node_mutual_funds toneBlue
class node_prices,node_scoring,node_analytics,node_fundamentals,node_news_source,node_news_classifier,node_news_cache,node_dividends,node_future_buys,node_growth,node_sheets toneAmber
class node_snapshots,node_brief,node_github_data,node_sheet_writer,node_formatter toneMint
class node_bot,node_handlers,node_sheet_state toneRose
class node_operator,node_telegram toneIndigo
```

## Components

### Portfolio pipeline

- [Daily update](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/main.py): `src/main.py`
- [Trade imports](https://github.com/sunaiworld/siddegowda-portfolio/tree/main/data/imports): `data/imports`
- [Portfolio builder](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/portfolio_builder.py): `src/portfolio_builder.py`
- [Mutual fund pipeline](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/mutual_fund_builder.py): `src/mutual_fund_builder.py`

### Investment analysis

- [Market data](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/data_fetcher.py): `src/data_fetcher.py`
- [Scoring engine](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/score_engine.py): `src/score_engine.py`
- [Portfolio analytics](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/portfolio_analytics.py): `src/portfolio_analytics.py`
- [Fundamental cache](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/fund_cache.py): `src/fund_cache.py`
- [Google News RSS](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/sources/google_news_rss.py): `src/news_engine/sources/google_news_rss.py`
- [News classifier](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/classifier.py): `src/news_engine/classifier.py`
- [News cache](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/news_engine/news_cache.py): `src/news_engine/news_cache.py`
- [Dividend pipeline](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/dividend_builder.py): `src/dividend_builder.py`
- [Future buy builder](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/future_buy_builder.py): `src/future_buy_builder.py`
- [Growth screener](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/growth_screener_builder.py): `src/growth_screener_builder.py`

### Sheets and reporting

- [Monthly snapshots](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/monthly_snapshot.py): `src/monthly_snapshot.py`
- [Morning brief](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/morning_brief_builder.py): `src/morning_brief_builder.py`
- [Portfolio sheet data](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/github_data_builder.py): `src/github_data_builder.py`
- [Sheet writer](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/sheet_writer.py): `src/sheet_writer.py`
- [Sheet formatter](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/src/sheet_formatter.py): `src/sheet_formatter.py`

### Bot and alerts

- [Telegram bot](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/telegram_bot.py): `telegram_bot.py`
- [Bot handlers](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/handlers.py): `handlers.py`
- [Cached sheet state](https://github.com/sunaiworld/siddegowda-portfolio/blob/main/services/sheets_state.py): `services/sheets_state.py`

### Other components

- **Operator / schedule**
- **Google Sheets**
- **Telegram service**

## Connections

- Operator / schedule → Daily update: starts
- Daily update → Portfolio builder: builds holdings (evidence: `src/main.py`)
- Portfolio builder → Trade imports: loads trades
- Daily update → Market data: fetches prices (evidence: `src/main.py`)
- Daily update → Scoring engine: scores stocks (evidence: `src/main.py`)
- Daily update → Portfolio analytics: computes dashboard (evidence: `src/main.py`)
- Portfolio builder → Portfolio analytics: uses analytics (evidence: `src/portfolio_builder.py`)
- Portfolio builder → Fundamental cache: uses cache (evidence: `src/portfolio_builder.py`)
- Daily update → Google News RSS: fetches headlines (evidence: `src/main.py`)
- Daily update → News classifier: classifies news (evidence: `src/main.py`)
- News classifier → News cache: stores digest
- Daily update → Mutual fund pipeline: builds fund data (evidence: `src/main.py`)
- Daily update → Dividend pipeline: builds dividends (evidence: `src/main.py`)
- Daily update → Future buy builder: builds buy ideas (evidence: `src/main.py`)
- Daily update → Growth screener: builds screener (evidence: `src/main.py`)
- Operator / schedule → Monthly snapshots: runs snapshot
- Operator / schedule → Morning brief: runs briefing
- Daily update → Portfolio sheet data: builds sheet data (evidence: `src/main.py`)
- Daily update → Sheet writer: writes results (evidence: `src/main.py`)
- Daily update → Sheet formatter: formats sheets (evidence: `src/main.py`)
- Sheet writer → Google Sheets: writes cells
- Sheet formatter → Google Sheets: formats cells
- Telegram service → Telegram bot: sends commands (evidence: `telegram_bot.py`)
- Telegram bot → Bot handlers: dispatches commands (evidence: `telegram_bot.py`)
- Bot handlers → Cached sheet state: reads cached rows (evidence: `handlers.py`)
- Cached sheet state → Google Sheets: reads state and data (evidence: `services/sheets_state.py`)
- Telegram bot → Daily update: runs refresh (evidence: `telegram_bot.py`)