# jiajin182/stock-screener architecture

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

- Interactive diagram: https://gitdiagram.com/jiajin182/stock-screener
- Repository: https://github.com/jiajin182/stock-screener

## Overview

Intelligent Stock Screener scans a stock universe, combines price-based phase and momentum analysis with fundamental screening, scores buy/sell opportunities, and produces ranked reports. The main daily path is driven by the optimized scan entry point; position management separately analyzes Robinhood holdings and recommends stop adjustments. The graph preserves documented market-regime, VCP, risk, and delivery capabilities. Some subsystem links are based on README descriptions because their implementation was not sampled.

Main entry points: [`src/screening/optimized_batch_processor.py`](https://github.com/jiajin182/stock-screener/blob/main/src/screening/optimized_batch_processor.py) (Batch Processor), [`run_optimized_scan.py`](https://github.com/jiajin182/stock-screener/blob/main/run_optimized_scan.py) (Optimized Scan), [`src/data/fundamentals_fetcher.py`](https://github.com/jiajin182/stock-screener/blob/main/src/data/fundamentals_fetcher.py) (Quarterly Fundamentals), [`src/data/fetcher.py`](https://github.com/jiajin182/stock-screener/blob/main/src/data/fetcher.py) (Price Fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan Workflow"]
  node_scan_entry["Optimized Scan"]
  node_batch["Batch Processor"]
  node_batch_legacy["Full-Market Batch<br/>[batch_processor.py]"]
end

subgraph group_data["Market Data"]
  node_universe["Stock Universe"]
  node_price_fetch["Price Fetcher<br/>[fetcher.py]"]
  node_fundamental_fetch["Quarterly Fundamentals"]
  node_git_cache[("Git Fundamentals Cache")]
  node_fundamental_data["Enhanced Fundamentals"]
  node_storage[("Stock Database<br/>[storage.py]")]
  node_quality["Data Quality<br/>[quality.py]"]
end

subgraph group_analysis["Analysis Engine"]
  node_phase["Phase &amp; VCP Indicators"]
  node_indicators["Technical Indicators<br/>[indicators.py]"]
  node_signal["Signal &amp; Risk Scoring<br/>[signal_engine.py]"]
  node_screener["Candidate Screener<br/>[screener.py]"]
  node_quant["Quant Engine<br/>[quant_engine.py]"]
end

subgraph group_positions["Position Management"]
  node_position_entry["Position Reports"]
  node_position_manage["Position Manager"]
  node_broker_positions["Robinhood Positions"]
end

subgraph group_delivery["Reports &amp; Alerts"]
  node_scheduler["Screening Scheduler<br/>[scheduler.py]"]
  node_email["Email Alerts<br/>[email_notifier.py]"]
  node_slack["Slack Alerts<br/>[slack_notifier.py]"]
  node_report["Ranked Scan Report"]
end

node_operator(("Investor / Operator"))
node_market_data{{"Market Data Provider"}}
node_smtp{{"SMTP Service"}}
node_slack_service{{"Slack Service"}}

node_operator -->|"runs scan"| node_scan_entry
node_scan_entry -->|"loads universe"| node_universe
node_scan_entry -->|"runs batches"| node_batch
node_batch -->|"fetches prices"| node_price_fetch
node_batch -->|"fetches fundamentals"| node_fundamental_fetch
node_batch -->|"uses cache"| node_git_cache
node_price_fetch -.->|"requests prices"| node_market_data
node_fundamental_fetch -.->|"requests financials"| node_market_data
node_git_cache -->|"refreshes data"| node_fundamental_fetch
node_batch -->|"classifies phases"| node_phase
node_batch -.->|"uses analysis"| node_fundamental_data
node_signal -->|"uses phase data"| node_phase
node_scan_entry -->|"scores signals"| node_signal
node_scan_entry -->|"generates report"| node_report
node_operator -->|"requests review"| node_position_entry
node_position_entry -->|"fetches holdings"| node_broker_positions
node_position_entry -->|"analyzes positions"| node_position_manage
node_position_manage -->|"uses phase analysis"| node_phase
node_position_manage -->|"reads fundamentals"| node_git_cache
node_operator -.->|"starts screening"| node_scheduler
node_scheduler -->|"sends alerts"| node_email
node_scheduler -->|"sends alerts"| node_slack
node_email -->|"sends mail"| node_smtp
node_slack -->|"posts messages"| node_slack_service
node_batch_legacy -->|"fetches prices"| node_price_fetch
node_batch_legacy -->|"fetches financials"| node_fundamental_fetch
node_batch_legacy -->|"classifies phases"| node_phase
node_quant -->|"fetches prices"| node_price_fetch
node_quant -->|"fetches financials"| node_fundamental_fetch
node_quant -->|"scores signals"| node_signal
node_screener -->|"queries data"| node_storage
node_screener -->|"calculates scores"| node_indicators
node_quality -->|"uses storage"| node_storage

click node_scan_entry "https://github.com/jiajin182/stock-screener/blob/main/run_optimized_scan.py"
click node_universe "https://github.com/jiajin182/stock-screener/blob/main/src/data/universe_fetcher.py"
click node_batch "https://github.com/jiajin182/stock-screener/blob/main/src/screening/optimized_batch_processor.py"
click node_price_fetch "https://github.com/jiajin182/stock-screener/blob/main/src/data/fetcher.py"
click node_fundamental_fetch "https://github.com/jiajin182/stock-screener/blob/main/src/data/fundamentals_fetcher.py"
click node_git_cache "https://github.com/jiajin182/stock-screener/blob/main/src/data/git_storage_fetcher.py"
click node_fundamental_data "https://github.com/jiajin182/stock-screener/blob/main/src/data/enhanced_fundamentals.py"
click node_phase "https://github.com/jiajin182/stock-screener/blob/main/src/screening/phase_indicators.py"
click node_indicators "https://github.com/jiajin182/stock-screener/blob/main/src/screening/indicators.py"
click node_signal "https://github.com/jiajin182/stock-screener/blob/main/src/screening/signal_engine.py"
click node_screener "https://github.com/jiajin182/stock-screener/blob/main/src/screening/screener.py"
click node_batch_legacy "https://github.com/jiajin182/stock-screener/blob/main/src/screening/batch_processor.py"
click node_quant "https://github.com/jiajin182/stock-screener/blob/main/src/screening/quant_engine.py"
click node_position_entry "https://github.com/jiajin182/stock-screener/blob/main/automated_position_report.py"
click node_position_manage "https://github.com/jiajin182/stock-screener/blob/main/src/analysis/position_manager.py"
click node_broker_positions "https://github.com/jiajin182/stock-screener/blob/main/src/data/robinhood_positions.py"
click node_storage "https://github.com/jiajin182/stock-screener/blob/main/src/data/storage.py"
click node_quality "https://github.com/jiajin182/stock-screener/blob/main/src/data/quality.py"
click node_scheduler "https://github.com/jiajin182/stock-screener/blob/main/src/notifications/scheduler.py"
click node_email "https://github.com/jiajin182/stock-screener/blob/main/src/notifications/email_notifier.py"
click node_slack "https://github.com/jiajin182/stock-screener/blob/main/src/notifications/slack_notifier.py"
click node_report "https://github.com/jiajin182/stock-screener/blob/main/run_optimized_scan.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_scan_entry,node_batch,node_batch_legacy toneBlue
class node_universe,node_price_fetch,node_fundamental_fetch,node_git_cache,node_fundamental_data,node_storage,node_quality toneAmber
class node_phase,node_indicators,node_signal,node_screener,node_quant toneMint
class node_position_entry,node_position_manage,node_broker_positions toneRose
class node_scheduler,node_email,node_slack,node_report,node_operator,node_market_data,node_smtp,node_slack_service toneIndigo
```

## Components

### Scan Workflow

- [Optimized Scan](https://github.com/jiajin182/stock-screener/blob/main/run_optimized_scan.py): `run_optimized_scan.py`
- [Batch Processor](https://github.com/jiajin182/stock-screener/blob/main/src/screening/optimized_batch_processor.py): `src/screening/optimized_batch_processor.py`
- [Full-Market Batch](https://github.com/jiajin182/stock-screener/blob/main/src/screening/batch_processor.py): `src/screening/batch_processor.py`

### Market Data

- [Stock Universe](https://github.com/jiajin182/stock-screener/blob/main/src/data/universe_fetcher.py): `src/data/universe_fetcher.py`
- [Price Fetcher](https://github.com/jiajin182/stock-screener/blob/main/src/data/fetcher.py): `src/data/fetcher.py`
- [Quarterly Fundamentals](https://github.com/jiajin182/stock-screener/blob/main/src/data/fundamentals_fetcher.py): `src/data/fundamentals_fetcher.py`
- [Git Fundamentals Cache](https://github.com/jiajin182/stock-screener/blob/main/src/data/git_storage_fetcher.py): `src/data/git_storage_fetcher.py`
- [Enhanced Fundamentals](https://github.com/jiajin182/stock-screener/blob/main/src/data/enhanced_fundamentals.py): `src/data/enhanced_fundamentals.py`
- [Stock Database](https://github.com/jiajin182/stock-screener/blob/main/src/data/storage.py): `src/data/storage.py`
- [Data Quality](https://github.com/jiajin182/stock-screener/blob/main/src/data/quality.py): `src/data/quality.py`

### Analysis Engine

- [Phase & VCP Indicators](https://github.com/jiajin182/stock-screener/blob/main/src/screening/phase_indicators.py): `src/screening/phase_indicators.py`
- [Technical Indicators](https://github.com/jiajin182/stock-screener/blob/main/src/screening/indicators.py): `src/screening/indicators.py`
- [Signal & Risk Scoring](https://github.com/jiajin182/stock-screener/blob/main/src/screening/signal_engine.py): `src/screening/signal_engine.py`
- [Candidate Screener](https://github.com/jiajin182/stock-screener/blob/main/src/screening/screener.py): `src/screening/screener.py`
- [Quant Engine](https://github.com/jiajin182/stock-screener/blob/main/src/screening/quant_engine.py): `src/screening/quant_engine.py`

### Position Management

- [Position Reports](https://github.com/jiajin182/stock-screener/blob/main/automated_position_report.py): `automated_position_report.py`
- [Position Manager](https://github.com/jiajin182/stock-screener/blob/main/src/analysis/position_manager.py): `src/analysis/position_manager.py`
- [Robinhood Positions](https://github.com/jiajin182/stock-screener/blob/main/src/data/robinhood_positions.py): `src/data/robinhood_positions.py`

### Reports & Alerts

- [Screening Scheduler](https://github.com/jiajin182/stock-screener/blob/main/src/notifications/scheduler.py): `src/notifications/scheduler.py`
- [Email Alerts](https://github.com/jiajin182/stock-screener/blob/main/src/notifications/email_notifier.py): `src/notifications/email_notifier.py`
- [Slack Alerts](https://github.com/jiajin182/stock-screener/blob/main/src/notifications/slack_notifier.py): `src/notifications/slack_notifier.py`
- [Ranked Scan Report](https://github.com/jiajin182/stock-screener/blob/main/run_optimized_scan.py): `run_optimized_scan.py`

### Other components

- **Investor / Operator**
- **Market Data Provider**
- **SMTP Service**
- **Slack Service**

## Connections

- Investor / Operator → Optimized Scan: runs scan (evidence: `README.md`)
- Optimized Scan → Stock Universe: loads universe (evidence: `run_optimized_scan.py`)
- Optimized Scan → Batch Processor: runs batches (evidence: `run_optimized_scan.py`)
- Batch Processor → Price Fetcher: fetches prices (evidence: `src/screening/optimized_batch_processor.py`)
- Batch Processor → Quarterly Fundamentals: fetches fundamentals (evidence: `src/screening/optimized_batch_processor.py`)
- Batch Processor → Git Fundamentals Cache: uses cache (evidence: `src/screening/optimized_batch_processor.py`)
- Price Fetcher → Market Data Provider: requests prices
- Quarterly Fundamentals → Market Data Provider: requests financials
- Git Fundamentals Cache → Quarterly Fundamentals: refreshes data (evidence: `src/data/git_storage_fetcher.py`)
- Batch Processor → Phase & VCP Indicators: classifies phases (evidence: `src/screening/optimized_batch_processor.py`)
- Batch Processor → Enhanced Fundamentals: uses analysis
- Signal & Risk Scoring → Phase & VCP Indicators: uses phase data (evidence: `src/screening/signal_engine.py`)
- Optimized Scan → Signal & Risk Scoring: scores signals (evidence: `run_optimized_scan.py`)
- Optimized Scan → Ranked Scan Report: generates report (evidence: `README.md`)
- Investor / Operator → Position Reports: requests review (evidence: `README.md`)
- Position Reports → Robinhood Positions: fetches holdings (evidence: `automated_position_report.py`)
- Position Reports → Position Manager: analyzes positions (evidence: `automated_position_report.py`)
- Position Manager → Phase & VCP Indicators: uses phase analysis (evidence: `src/analysis/position_manager.py`)
- Position Manager → Git Fundamentals Cache: reads fundamentals (evidence: `src/analysis/position_manager.py`)
- Investor / Operator → Screening Scheduler: starts screening
- Screening Scheduler → Email Alerts: sends alerts (evidence: `src/notifications/scheduler.py`)
- Screening Scheduler → Slack Alerts: sends alerts (evidence: `src/notifications/scheduler.py`)
- Email Alerts → SMTP Service: sends mail (evidence: `src/notifications/email_notifier.py`)
- Slack Alerts → Slack Service: posts messages (evidence: `src/notifications/slack_notifier.py`)
- Full-Market Batch → Price Fetcher: fetches prices (evidence: `src/screening/batch_processor.py`)
- Full-Market Batch → Quarterly Fundamentals: fetches financials (evidence: `src/screening/batch_processor.py`)
- Full-Market Batch → Phase & VCP Indicators: classifies phases (evidence: `src/screening/batch_processor.py`)
- Quant Engine → Price Fetcher: fetches prices (evidence: `src/screening/quant_engine.py`)
- Quant Engine → Quarterly Fundamentals: fetches financials (evidence: `src/screening/quant_engine.py`)
- Quant Engine → Signal & Risk Scoring: scores signals (evidence: `src/screening/quant_engine.py`)
- Candidate Screener → Stock Database: queries data (evidence: `src/screening/screener.py`)
- Candidate Screener → Technical Indicators: calculates scores (evidence: `src/screening/screener.py`)
- Data Quality → Stock Database: uses storage (evidence: `src/data/quality.py`)
