# cameronbyrne4/nvidia-tracker architecture

> Architecture diagram of the GitHub repository cameronbyrne4/nvidia-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cameronbyrne4/nvidia-tracker
- Repository: https://github.com/cameronbyrne4/nvidia-tracker

## Overview

##### Project type and purpose
- This is a full‑stack web application (“NVIDIA Tracker”) combining a React/Vite frontend with a Python‑based backend.
- Purpose: scrape selected subreddits for NVDA‑related posts/comments, compute an aggregated sentiment score, and display results in a responsive UI.

##### File structure
- Top‑level:
- frontend/ → React + Vite application (App.jsx, StockChart.jsx, SentimentBadge.jsx, etc.)
- main.py → entrypoint for the Python web server / REST API
- scraper.py → module to fetch Reddit posts/comments
- sentiment_analyzer.py → module to compute sentiment from scraped text
- stock_data.py & stock_cache.json → simple cache/data‑access layer for stock metadata or past sentiment
- requirements.txt → Python dependencies
- Build configs in frontend: package.json, vite.config.js, tailwind.config.js
- No traditional database—caching uses a JSON file.

##### Extract insights from README
- Frontend: React + Vite, dynamic, styled with Tailwind
- Backend: scrapes Reddit, analyzes sentiment, provides an API
- Future scope: multi‑stock searches, advanced NLP

##### Main components
a. Frontend Client
- React app served by Vite (Node.js dev server or a static host)
- UI components: StockChart, StockMetrics, SentimentBadge
b. Backend API Server
- Python web framework in main.py (e.g., Flask or FastAPI)
- Exposes endpoints such as /api/sentiment or /api/stock‑data
c. Scraper Module
- scraper.py uses Reddit’s API or web‑scraping to retrieve posts/comments
d. Sentiment Analyzer
- sentiment_analyzer.py processes text, returns a numeric sentiment score + recommendation
e. Data Access / Cache
- stock_data.py reads/writes stock_cache.json to avoid re‑scraping on every request
f. External Service
- Reddit API (or HTML endpoints) as data source

##### Interactions & data flow
- User in browser → React App → HTTP GET /api/sentiment?symbol=NVDA
- Backend main.py
→ checks stock_cache.json via stock_data.py
→ if stale or missing: calls scraper.py → Reddit API
→ passes raw text to sentiment_analyzer.py → sentiment result
→ writes/updates cache → returns JSON payload to client
- React receives JSON → updates UI (charts, badges)

##### Architectural patterns & design principles
- Clear separation of concerns:
- Presentation (frontend)
- Business logic (API server)
- Data ingestion (scraper)
- Data processing (sentiment analyzer)
- Caching/persistence (JSON file)
- Stateless API endpoints with cached state
- Modular Python code for easy replacement (e.g., swap scraper for other stocks)
- Frontend components follow React composition

##### Detail without over‑fragmentation
- Module (scraper, sentiment analyzer, cache)
- Don’t collapse everything into “backend”—show internal parts
- How the Python modules collaborate under main.py
- Future extension points (e.g., new scraper for other stocks)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend
    U["User"]:::external
    U -->|"interacts via browser"| FE["React App"]:::frontend

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["React App"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API Server"
        API["Python API (main.py)"]:::backend
        subgraph "Business Logic"
            SD["Data Access / Cache"]:::backend
            SM["Sentiment Analyzer"]:::backend
            SC["Scraper Module"]:::backend
        end
    end

    %% External Services and Storage
    RED["Reddit API"]:::external
    CACHE["stock_cache.json"]:::storage

    %% Data Flows
    FE -->|"GET /api/sentiment?symbol=NVDA"| API
    API -->|"check cache"| SD
    SD -->|"load/write"| CACHE
    SD -->|"cache miss"| API
    API -->|"scrape data"| SC
    SC -->|"fetch posts/comments"| RED
    SC -->|"raw text"| API
    API -->|"analyze text"| SM
    SM -->|"sentiment score"| API
    API -->|"JSON response"| FE

    %% Click Events
    click FE "https://github.com/cameronbyrne4/nvidia-tracker/tree/main/frontend/"
    click API "https://github.com/cameronbyrne4/nvidia-tracker/blob/main/main.py"
    click SC "https://github.com/cameronbyrne4/nvidia-tracker/blob/main/scraper.py"
    click SM "https://github.com/cameronbyrne4/nvidia-tracker/blob/main/sentiment_analyzer.py"
    click SD "https://github.com/cameronbyrne4/nvidia-tracker/blob/main/stock_data.py"
    click CACHE "https://github.com/cameronbyrne4/nvidia-tracker/blob/main/stock_cache.json"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0044CC;
    classDef backend fill:#DFFFD0,stroke:#006600;
    classDef external fill:#FFE0B2,stroke:#CC5500;
    classDef storage fill:#F0F0F0,stroke:#888888;
    class U external
    class RED external
    class FE frontend
    class API backend
    class SD,SM,SC backend
    class CACHE storage
```
