# gamaranathareddy/investment-notifier architecture

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

- Interactive diagram: https://gitdiagram.com/gamaranathareddy/investment-notifier
- Repository: https://github.com/gamaranathareddy/investment-notifier

## Overview

The product is a long-term investing monitor and symbol-discovery system. Its main workflow fetches market history, evaluates exit risks and entry opportunities, then formats and sends Telegram alerts; a separate discovery workflow ranks candidates for a dashboard. The README also documents watchlist configuration, Telegram delivery, and daily automation. Some runtime wiring is only partially excerpted, so uncertain relationships are omitted; the discovery and monitoring branches are kept distinct.

Main entry points: [`investor_alert.py`](https://github.com/gamaranathareddy/investment-notifier/blob/main/investor_alert.py) (Investor monitor), [`discover_symbols.py`](https://github.com/gamaranathareddy/investment-notifier/blob/main/discover_symbols.py) (Symbol discovery), [`lib/alerts.py`](https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/alerts.py) (Alert formatting), [`lib/market_data.py`](https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/market_data.py) (Market history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Analysis workflows"]
  node_investor["Investor monitor<br/>[investor_alert.py]"]
  node_discovery["Symbol discovery"]
  node_scheduler["Alert scheduler<br/>[scheduler.py]"]
end

subgraph group_shared["Analysis services"]
  node_market["Market history<br/>[market_data.py]"]
  node_signals["Signal calculations<br/>[signals.py]"]
  node_configlib["Config parsing<br/>[config.py]"]
  node_alerts["Alert formatting<br/>[alerts.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_streamlit["Investment dashboard<br/>[streamlit_app.py]"]
  node_flask["Flask dashboard<br/>[web_ui.py]"]
  node_template["Dashboard template<br/>[index.html]"]
end

subgraph group_state["Configuration and state"]
  node_settings["Strategy settings<br/>[config.json]"]
  node_watchlist["Watchlist symbols<br/>[stocks.json]"]
  node_recommendations["Recommendations"]
  node_alertstate[("Alert state<br/>[alerts.json]")]
end

node_investor_user(("Long-term investor"))
node_prices["Yahoo Finance"]
node_telegram["Telegram"]
node_clock(("Daily schedule"))

node_investor -->|"loads rules"| node_configlib
node_investor -->|"fetches prices"| node_market
node_investor -->|"evaluates signals"| node_signals
node_investor -->|"formats alerts"| node_alerts
node_market -->|"downloads history"| node_prices
node_discovery -->|"loads rules"| node_configlib
node_discovery -->|"fetches prices"| node_market
node_discovery -->|"scores candidates"| node_signals
node_scheduler -->|"uses alert helpers"| node_alerts
node_clock -.->|"triggers"| node_scheduler
node_alerts -->|"sends messages"| node_telegram
node_alerts -.->|"tracks dedupe state"| node_alertstate
node_investor -.->|"runs monitor"| node_investor
node_investor -->|"reads symbols"| node_watchlist
node_discovery -->|"writes results"| node_recommendations
node_streamlit -->|"runs discovery"| node_discovery
node_streamlit -.->|"displays results"| node_recommendations
node_flask -->|"renders page"| node_template
node_flask -->|"reads and edits"| node_settings

click node_investor "https://github.com/gamaranathareddy/investment-notifier/blob/main/investor_alert.py"
click node_discovery "https://github.com/gamaranathareddy/investment-notifier/blob/main/discover_symbols.py"
click node_scheduler "https://github.com/gamaranathareddy/investment-notifier/blob/main/scheduler.py"
click node_market "https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/market_data.py"
click node_signals "https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/signals.py"
click node_configlib "https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/config.py"
click node_alerts "https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/alerts.py"
click node_streamlit "https://github.com/gamaranathareddy/investment-notifier/blob/main/streamlit_app.py"
click node_flask "https://github.com/gamaranathareddy/investment-notifier/blob/main/web_ui.py"
click node_template "https://github.com/gamaranathareddy/investment-notifier/blob/main/templates/index.html"
click node_settings "https://github.com/gamaranathareddy/investment-notifier/blob/main/config.json"
click node_watchlist "https://github.com/gamaranathareddy/investment-notifier/blob/main/stocks.json"
click node_recommendations "https://github.com/gamaranathareddy/investment-notifier/blob/main/recommended_symbols.json"
click node_alertstate "https://github.com/gamaranathareddy/investment-notifier/blob/main/state/alerts.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_investor,node_discovery,node_scheduler toneBlue
class node_market,node_signals,node_configlib,node_alerts toneAmber
class node_streamlit,node_flask,node_template toneMint
class node_settings,node_watchlist,node_recommendations,node_alertstate toneRose
class node_investor_user,node_prices,node_telegram,node_clock toneIndigo
```

## Components

### Analysis workflows

- [Investor monitor](https://github.com/gamaranathareddy/investment-notifier/blob/main/investor_alert.py): `investor_alert.py`
- [Symbol discovery](https://github.com/gamaranathareddy/investment-notifier/blob/main/discover_symbols.py): `discover_symbols.py`
- [Alert scheduler](https://github.com/gamaranathareddy/investment-notifier/blob/main/scheduler.py): `scheduler.py`

### Analysis services

- [Market history](https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/market_data.py): `lib/market_data.py`
- [Signal calculations](https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/signals.py): `lib/signals.py`
- [Config parsing](https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/config.py): `lib/config.py`
- [Alert formatting](https://github.com/gamaranathareddy/investment-notifier/blob/main/lib/alerts.py): `lib/alerts.py`

### User interfaces

- [Investment dashboard](https://github.com/gamaranathareddy/investment-notifier/blob/main/streamlit_app.py): `streamlit_app.py`
- [Flask dashboard](https://github.com/gamaranathareddy/investment-notifier/blob/main/web_ui.py): `web_ui.py`
- [Dashboard template](https://github.com/gamaranathareddy/investment-notifier/blob/main/templates/index.html): `templates/index.html`

### Configuration and state

- [Strategy settings](https://github.com/gamaranathareddy/investment-notifier/blob/main/config.json): `config.json`
- [Watchlist symbols](https://github.com/gamaranathareddy/investment-notifier/blob/main/stocks.json): `stocks.json`
- [Recommendations](https://github.com/gamaranathareddy/investment-notifier/blob/main/recommended_symbols.json): `recommended_symbols.json`
- [Alert state](https://github.com/gamaranathareddy/investment-notifier/blob/main/state/alerts.json): `state/alerts.json`

### Other components

- **Long-term investor**
- **Yahoo Finance**
- **Telegram**
- **Daily schedule**

## Connections

- Investor monitor → Config parsing: loads rules (evidence: `investor_alert.py`)
- Investor monitor → Market history: fetches prices (evidence: `investor_alert.py`)
- Investor monitor → Signal calculations: evaluates signals (evidence: `investor_alert.py`)
- Investor monitor → Alert formatting: formats alerts (evidence: `investor_alert.py`)
- Market history → Yahoo Finance: downloads history (evidence: `lib/market_data.py`)
- Symbol discovery → Config parsing: loads rules (evidence: `discover_symbols.py`)
- Symbol discovery → Market history: fetches prices (evidence: `discover_symbols.py`)
- Symbol discovery → Signal calculations: scores candidates (evidence: `discover_symbols.py`)
- Alert scheduler → Alert formatting: uses alert helpers (evidence: `scheduler.py`)
- Daily schedule → Alert scheduler: triggers
- Alert formatting → Telegram: sends messages (evidence: `lib/alerts.py`)
- Alert formatting → Alert state: tracks dedupe state
- Investor monitor → Investor monitor: runs monitor (evidence: `investor_alert.py`)
- Investor monitor → Watchlist symbols: reads symbols (evidence: `README.md`)
- Symbol discovery → Recommendations: writes results (evidence: `discover_symbols.py`)
- Investment dashboard → Symbol discovery: runs discovery (evidence: `streamlit_app.py`)
- Investment dashboard → Recommendations: displays results
- Flask dashboard → Dashboard template: renders page (evidence: `web_ui.py`)
- Flask dashboard → Strategy settings: reads and edits (evidence: `web_ui.py`)