# vedant9912/stocksense-sentiment-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/vedant9912/stocksense-sentiment-analysis
- Repository: https://github.com/vedant9912/stocksense-sentiment-analysis

## Overview

StockSense is a browser-based financial analytics workstation backed by a Spring Boot API and a FastAPI analysis service. Users authenticate, request ticker sentiment or structured research, and view reports alongside charts and watchlists. The documented sentiment flow fetches headlines and scores them; the agent flow gathers market, news, technical, and sentiment evidence before synthesis. The README documents the UI capabilities and deployment integrations; source excerpts establish key calls, while unsampled routes and tool internals are represented only where documented or indexed.

Main entry points: [`stocksense-ai-service/app/agent/agent.py`](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/agent/agent.py) (Research agent), [`stocksense-backend/src/main/java/com/stocksense/controller/StockController.java`](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/controller/StockController.java) (Stock routes), [`stocksense-ai-service/app/main.py`](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/main.py) (FastAPI routes), [`stocksense-backend/src/main/java/com/stocksense/service/UserService.java`](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/UserService.java) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser terminal"]
  node_webui["Terminal UI<br/>[app.js]"]
  node_authui["Login UI<br/>[auth.js]"]
end

subgraph group_backend["Spring backend"]
  node_authcontroller["Auth routes"]
  node_stockcontroller["Stock routes"]
  node_userservice["User service<br/>[UserService.java]"]
  node_jwt["JWT security<br/>[JwtUtil.java]"]
  node_stockservice["Stock service<br/>[StockService.java]"]
  node_fastclient["AI client<br/>[FastAPIClient.java]"]
  node_dto["API data models"]
end

subgraph group_ai["AI services"]
  node_aiapi["FastAPI routes<br/>[main.py]"]
  node_scraper["Headline scraper<br/>[scraper.py]"]
  node_finbert["FinBERT engine<br/>[model.py]"]
  node_agent["Research agent<br/>[agent.py]"]
  node_llm["LLM synthesis<br/>[llm.py]"]
end

subgraph group_research["Research tools"]
  node_market["Market data tool<br/>[market_data.py]"]
  node_news["Research news<br/>[news.py]"]
  node_sentiment["Agent sentiment<br/>[sentiment.py]"]
  node_technical["Technical analysis"]
end

subgraph group_persistence["Persistence"]
  node_repositories["Data repositories"]
  node_entities[("User and analysis records")]
end

node_user(("User"))
node_mysql[("MySQL")]
node_rss["RSS feeds"]
node_hf["Hugging Face inference"]
node_localmodel["Local FinBERT"]
node_tradingview["TradingView charts"]

node_user -->|"signs in"| node_authui
node_authui -->|"submits credentials"| node_authcontroller
node_authcontroller -->|"delegates auth"| node_userservice
node_userservice -->|"uses user repository"| node_repositories
node_userservice -->|"generates token"| node_jwt
node_user -->|"requests analysis"| node_webui
node_webui -->|"calls API"| node_stockcontroller
node_webui -.->|"loads charts"| node_tradingview
node_stockcontroller -->|"delegates requests"| node_stockservice
node_stockcontroller -->|"resolves user"| node_userservice
node_stockservice -->|"requests analysis"| node_fastclient
node_stockservice -->|"reads and writes"| node_repositories
node_repositories -->|"persists records"| node_entities
node_entities -->|"stored in"| node_mysql
node_stockcontroller -->|"accepts and returns"| node_dto
node_fastclient -->|"calls endpoints"| node_aiapi
node_aiapi -->|"fetches headlines"| node_scraper
node_aiapi -->|"scores headlines"| node_finbert
node_scraper -.->|"reads feeds"| node_rss
node_finbert -->|"uses serverless inference"| node_hf
node_finbert -.->|"runs local weights"| node_localmodel
node_aiapi -->|"runs research"| node_agent
node_agent -->|"executes tool"| node_market
node_agent -->|"executes tool"| node_news
node_agent -->|"executes tool"| node_technical
node_agent -->|"executes tool"| node_sentiment
node_sentiment -->|"scores titles"| node_finbert
node_agent -->|"synthesizes evidence"| node_llm

click node_webui "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/resources/static/js/app.js"
click node_authui "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/resources/static/js/auth.js"
click node_authcontroller "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/controller/AuthController.java"
click node_stockcontroller "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/controller/StockController.java"
click node_userservice "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/UserService.java"
click node_jwt "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/security/JwtUtil.java"
click node_stockservice "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/StockService.java"
click node_fastclient "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/FastAPIClient.java"
click node_dto "https://github.com/vedant9912/stocksense-sentiment-analysis/tree/main/stocksense-backend/src/main/java/com/stocksense/dto"
click node_aiapi "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/main.py"
click node_scraper "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/scraper.py"
click node_finbert "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/model.py"
click node_agent "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/agent/agent.py"
click node_llm "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/agent/llm.py"
click node_market "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/market_data.py"
click node_news "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/news.py"
click node_sentiment "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/sentiment.py"
click node_technical "https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/technical_analysis.py"
click node_repositories "https://github.com/vedant9912/stocksense-sentiment-analysis/tree/main/stocksense-backend/src/main/java/com/stocksense/repository"
click node_entities "https://github.com/vedant9912/stocksense-sentiment-analysis/tree/main/stocksense-backend/src/main/java/com/stocksense/entity"

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_webui,node_authui,node_user,node_tradingview toneBlue
class node_authcontroller,node_stockcontroller,node_userservice,node_jwt,node_stockservice,node_fastclient,node_dto,node_mysql toneAmber
class node_aiapi,node_scraper,node_finbert,node_agent,node_llm toneMint
class node_market,node_news,node_sentiment,node_technical toneRose
class node_repositories,node_entities,node_rss,node_hf,node_localmodel toneIndigo
```

## Components

### Browser terminal

- [Terminal UI](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/resources/static/js/app.js): `stocksense-backend/src/main/resources/static/js/app.js`
- [Login UI](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/resources/static/js/auth.js): `stocksense-backend/src/main/resources/static/js/auth.js`

### Spring backend

- [Auth routes](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/controller/AuthController.java): `stocksense-backend/src/main/java/com/stocksense/controller/AuthController.java`
- [Stock routes](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/controller/StockController.java): `stocksense-backend/src/main/java/com/stocksense/controller/StockController.java`
- [User service](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/UserService.java): `stocksense-backend/src/main/java/com/stocksense/service/UserService.java`
- [JWT security](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/security/JwtUtil.java): `stocksense-backend/src/main/java/com/stocksense/security/JwtUtil.java`
- [Stock service](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/StockService.java): `stocksense-backend/src/main/java/com/stocksense/service/StockService.java`
- [AI client](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-backend/src/main/java/com/stocksense/service/FastAPIClient.java): `stocksense-backend/src/main/java/com/stocksense/service/FastAPIClient.java`
- [API data models](https://github.com/vedant9912/stocksense-sentiment-analysis/tree/main/stocksense-backend/src/main/java/com/stocksense/dto): `stocksense-backend/src/main/java/com/stocksense/dto`

### AI services

- [FastAPI routes](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/main.py): `stocksense-ai-service/app/main.py`
- [Headline scraper](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/scraper.py): `stocksense-ai-service/app/scraper.py`
- [FinBERT engine](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/model.py): `stocksense-ai-service/app/model.py`
- [Research agent](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/agent/agent.py): `stocksense-ai-service/app/agent/agent.py`
- [LLM synthesis](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/agent/llm.py): `stocksense-ai-service/app/agent/llm.py`

### Research tools

- [Market data tool](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/market_data.py): `stocksense-ai-service/app/tools/market_data.py`
- [Research news](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/news.py): `stocksense-ai-service/app/tools/news.py`
- [Agent sentiment](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/sentiment.py): `stocksense-ai-service/app/tools/sentiment.py`
- [Technical analysis](https://github.com/vedant9912/stocksense-sentiment-analysis/blob/main/stocksense-ai-service/app/tools/technical_analysis.py): `stocksense-ai-service/app/tools/technical_analysis.py`

### Persistence

- [Data repositories](https://github.com/vedant9912/stocksense-sentiment-analysis/tree/main/stocksense-backend/src/main/java/com/stocksense/repository): `stocksense-backend/src/main/java/com/stocksense/repository`
- [User and analysis records](https://github.com/vedant9912/stocksense-sentiment-analysis/tree/main/stocksense-backend/src/main/java/com/stocksense/entity): `stocksense-backend/src/main/java/com/stocksense/entity`

### Other components

- **User**
- **MySQL**
- **RSS feeds**
- **Hugging Face inference**
- **Local FinBERT**
- **TradingView charts**

## Connections

- User → Login UI: signs in
- Login UI → Auth routes: submits credentials
- Auth routes → User service: delegates auth (evidence: `stocksense-backend/src/main/java/com/stocksense/controller/AuthController.java`)
- User service → Data repositories: uses user repository (evidence: `stocksense-backend/src/main/java/com/stocksense/service/UserService.java`)
- User service → JWT security: generates token (evidence: `stocksense-backend/src/main/java/com/stocksense/service/UserService.java`)
- User → Terminal UI: requests analysis
- Terminal UI → Stock routes: calls API
- Terminal UI → TradingView charts: loads charts
- Stock routes → Stock service: delegates requests (evidence: `stocksense-backend/src/main/java/com/stocksense/controller/StockController.java`)
- Stock routes → User service: resolves user (evidence: `stocksense-backend/src/main/java/com/stocksense/controller/StockController.java`)
- Stock service → AI client: requests analysis (evidence: `stocksense-backend/src/main/java/com/stocksense/service/StockService.java`)
- Stock service → Data repositories: reads and writes (evidence: `stocksense-backend/src/main/java/com/stocksense/service/StockService.java`)
- Data repositories → User and analysis records: persists records (evidence: `stocksense-backend/src/main/java/com/stocksense/repository/WatchlistRepository.java`)
- User and analysis records → MySQL: stored in
- Stock routes → API data models: accepts and returns (evidence: `stocksense-backend/src/main/java/com/stocksense/controller/StockController.java`)
- AI client → FastAPI routes: calls endpoints (evidence: `stocksense-backend/src/main/java/com/stocksense/service/FastAPIClient.java`)
- FastAPI routes → Headline scraper: fetches headlines (evidence: `stocksense-ai-service/app/main.py`)
- FastAPI routes → FinBERT engine: scores headlines (evidence: `stocksense-ai-service/app/main.py`)
- Headline scraper → RSS feeds: reads feeds
- FinBERT engine → Hugging Face inference: uses serverless inference (evidence: `stocksense-ai-service/app/model.py`)
- FinBERT engine → Local FinBERT: runs local weights
- FastAPI routes → Research agent: runs research (evidence: `stocksense-ai-service/app/main.py`)
- Research agent → Market data tool: executes tool (evidence: `stocksense-ai-service/app/agent/agent.py`)
- Research agent → Research news: executes tool (evidence: `stocksense-ai-service/app/agent/agent.py`)
- Research agent → Technical analysis: executes tool (evidence: `stocksense-ai-service/app/agent/agent.py`)
- Research agent → Agent sentiment: executes tool (evidence: `stocksense-ai-service/app/agent/agent.py`)
- Agent sentiment → FinBERT engine: scores titles (evidence: `stocksense-ai-service/app/tools/sentiment.py`)
- Research agent → LLM synthesis: synthesizes evidence (evidence: `stocksense-ai-service/app/agent/agent.py`)
