# firaold/news-sentiment-stock-prediction architecture

> Architecture diagram of the GitHub repository firaold/news-sentiment-stock-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firaold/news-sentiment-stock-prediction
- Repository: https://github.com/firaold/news-sentiment-stock-prediction

## Overview

##### Project Type and Purpose
- This is a data-science analytics pipeline (not a web app). It ingests financial news and stock-price data, performs sentiment and technical-indicator analysis, and uncovers correlations between sentiment and returns.

##### Main Components
a. Data Sources
- External News API (e.g., RSS feeds, scraped headlines)
- Stock Price API (e.g., yfinance)
b. Data Ingestion Layer
- scripts/download_stock_data.py
- (Implicit) news-download module inside NewsAnalyzer or separate script
c. Data Storage
- Local “data/” folder (gitignored) containing raw CSV/JSON
d. Processing & Analysis Modules (src/)
- BaseAnalyzer (common I/O, error handling)
- NewsAnalyzer (sentiment, EDA, topic modeling)
- StockAnalyzer (RSI, MACD, moving averages via TA-Lib/PyNance)
- CorrelationAnalyzer (combines sentiment & returns)
e. Notebooks & Visualization
- Jupyter notebooks under notebooks/ for EDA, technical indicators, correlation analysis
- “Plot Visualizations” folder with saved charts
f. Testing & CI
- tests/test_news_analyzer.py (unit tests for NewsAnalyzer)
- GitHub Actions workflows (.github/workflows/ci.yml, unittests.yml)
g. External Libraries & Frameworks
- TextBlob / NLTK for NLP
- TA-Lib / PyNance for technical indicators
- Pandas, NumPy for data manipulation
- Matplotlib, Seaborn for plotting

##### Relationships & Data Flow
1. Data Sources → Data Ingestion Layer (download scripts)
2. Ingestion writes Raw Data → Data Storage
3. Processing Modules read Raw Data:
- NewsAnalyzer reads headlines → performs sentiment & topic modeling → outputs cleaned sentiment data
- StockAnalyzer reads price data → computes indicators → outputs indicator data
4. CorrelationAnalyzer reads sentiment + indicators → computes correlation results
5. Notebooks read processed outputs → generate interactive EDA, visualizations → save figures to “Plot Visualizations”
6. Tests validate NewsAnalyzer; CI pipelines run on GitHub on each push/pull

##### Architectural Patterns & Principles
- Modular OOP: BaseAnalyzer parent, specialized child analyzers (follows DRY)
- Data-Pipeline pattern: clear extract → transform → load & analyze stages
- Layered separation: ingestion, processing, visualization, testing

##### Must-Include Elements
- Component names & roles
- Data sources vs. storage vs. compute vs. visualization vs. CI
- Callouts for key technologies (TextBlob, TA-Lib, Pandas, Matplotlib)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        NewsAPI["External News API"]:::datasource
        StockAPI["Stock Price API"]:::datasource
        DownloadScript["Stock Data Download Script"]:::script
        RawData["Raw Data Storage (data/)"]:::storage
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        BaseAnalyzer["BaseAnalyzer (I/O, error handling)"]:::processing
        NewsAnalyzer["NewsAnalyzer (sentiment/NLP)"]:::processing
        StockAnalyzer["StockAnalyzer (technical indicators)"]:::processing
        CorrelationAnalyzer["CorrelationAnalyzer (sentiment vs returns)"]:::processing
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        Notebooks["Jupyter Notebooks (EDA, analysis)"]:::notebook
        Plots["Saved Plot Visualizations"]:::notebook
    end

    %% CI/Test Layer
    subgraph "CI/Test Layer"
        direction TB
        Tests["Unit Tests (NewsAnalyzer)"]:::ci
        CI["GitHub Actions Workflows"]:::ci
    end

    %% Data Flow
    NewsAPI -->|"fetch headlines"| DownloadScript
    StockAPI -->|"fetch prices"| DownloadScript
    DownloadScript -->|"writes CSV/JSON"| RawData
    RawData -->|"reads raw headlines"| NewsAnalyzer
    RawData -->|"reads raw prices"| StockAnalyzer
    NewsAnalyzer -->|"outputs sentiment data"| CorrelationAnalyzer
    StockAnalyzer -->|"outputs indicator data"| CorrelationAnalyzer
    CorrelationAnalyzer -->|"outputs correlation results"| Notebooks
    Notebooks -->|"saves charts"| Plots
    Tests -->|"validates NewsAnalyzer"| NewsAnalyzer
    CI -->|"runs on push/pull"| Tests

    %% Click Events
    click DownloadScript "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/scripts/download_stock_data.py"
    click BaseAnalyzer "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/src/base_analyzer.py"
    click NewsAnalyzer "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/src/news_analyzer.py"
    click StockAnalyzer "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/src/stock_analyzer.py"
    click CorrelationAnalyzer "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/src/correlation_analyzer.py"
    click Tests "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/tests/test_news_analyzer.py"
    click CI "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/firaold/news-sentiment-stock-prediction/blob/main/.github/workflows/unittests.yml"
    click Notebooks "https://github.com/firaold/news-sentiment-stock-prediction/tree/main/notebooks/"
    click Plots "https://github.com/firaold/news-sentiment-stock-prediction/tree/main/Plot Visualizations/"

    %% Styles
    classDef datasource fill:#f9f,stroke:#333,stroke-width:1px
    classDef script fill:#cfc,stroke:#333,stroke-width:1px
    classDef storage fill:#ccf,stroke:#333,stroke-width:1px
    classDef processing fill:#cff,stroke:#333,stroke-width:1px
    classDef notebook fill:#fcf,stroke:#333,stroke-width:1px
    classDef ci fill:#ffc,stroke:#333,stroke-width:1px
```
