# jngk07/stockagent architecture

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

- Interactive diagram: https://gitdiagram.com/jngk07/stockagent
- Repository: https://github.com/jngk07/stockagent

## Overview

#### Purpose and entry points
This is a Python multi-agent stock-trading workflow. It collects stock news, derives sentiment signals, predicts prices, and produces buy/sell trading decisions while persisting stage outputs to PostgreSQL.

Primary execution/UI entry points:
- `main_pipeline.py` — orchestrates the end-to-end agent flow.
- `app.py` — Streamlit-facing application entry point.
- `agent1_news_reader.py` — likely standalone entry for news collection.

#### Pipeline orchestration
`main_pipeline.py` is the control-plane boundary: it should sequence agents and pass each stage’s output into downstream stages. The intended flow is:

1. News acquisition
2. Sentiment signal generation
3. Price prediction
4. Trade decision
5. PostgreSQL logging

Relevant path:
- `main_pipeline.py`

#### News ingestion agent
The news-reader stage obtains stock-related news as the upstream market-context input. Its output is the source material for sentiment analysis and may also be available to prediction/trading logic.

Relevant path:
- `agent1_news_reader.py`

Boundary: external news/data sources enter the repository here; downstream agents should consume normalized news content rather than source-specific API responses.

#### Sentiment signal agent
The sentiment agent converts news input into a trading-oriented sentiment assessment. Its results are persisted as “Sentimental Logs” in PostgreSQL and become a core decision signal for the trader.

Relevant path:
- `agent2_sentiment_signal.py`

Boundary: this stage separates unstructured language/news analysis from structured numeric or categorical market signals.

#### Price prediction agent
The prediction stage estimates future stock prices or price direction, producing a second independent input to the trader. Prediction outputs are stored as “Price Prediction Logs.”

Relevant path:
- `agent4_price_predictor.py`

Boundary: predictive/model logic is isolated from final trade-policy logic, allowing the trader to combine forecasts with sentiment rather than embedding forecasting internally.

#### Trading decision agent
The trader agent consumes the available sentiment and price-prediction signals to determine buy/sell actions. It records decisions in “Trader Logs.”

Relevant path:
- `agent3_trader.py`

This is the policy boundary: upstream agents generate evidence; this component converts evidence into actionable trade recommendations.

#### Persistence, UI, and infrastructure
PostgreSQL is the system of record for sentiment, prediction, and trader logs. The README also identifies an MCP-server connection between local PostgreSQL and Claude Desktop, making the database externally inspectable through that integration.

Streamlit provides the application runtime/UI:
- `app.py`
- `.streamlit/config.toml`

Python dependencies and likely database, agent/model, and UI libraries are declared in:
- `requirements.txt`

Main entry points: [`main_pipeline.py`](https://github.com/jngk07/stockagent/blob/main/main_pipeline.py) (Pipeline Orchestrator), [`agent3_trader.py`](https://github.com/jngk07/stockagent/blob/main/agent3_trader.py) (Trade Decision), [`agent2_sentiment_signal.py`](https://github.com/jngk07/stockagent/blob/main/agent2_sentiment_signal.py) (Sentiment Signal), [`agent4_price_predictor.py`](https://github.com/jngk07/stockagent/blob/main/agent4_price_predictor.py) (Price Predictor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application Runtime"]
  node_streamlit_ui["Streamlit UI<br/>Streamlit app<br/>[app.py]"]
  node_pipeline["Pipeline Orchestrator<br/>Python workflow<br/>[main_pipeline.py]"]
end

subgraph group_agents["Trading Agents"]
  node_news_reader["News Reader<br/>ingestion agent"]
  node_sentiment_agent["Sentiment Signal<br/>analysis agent"]
  node_price_predictor["Price Predictor<br/>forecasting agent"]
  node_trader["Trade Decision<br/>policy agent<br/>[agent3_trader.py]"]
end

subgraph group_storage["Persistence &amp; Integration"]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_sentiment_logs["Sentimental Logs<br/>log records"]
  node_prediction_logs["Price Prediction Logs<br/>log records"]
  node_trader_logs["Trader Logs<br/>log records"]
  node_claude_mcp{{"Claude Desktop MCP<br/>external integration"}}
end

node_news_sources(("External News Sources<br/>external data"))

node_streamlit_ui -->|"runs workflow"| node_pipeline
node_pipeline -->|"news stage"| node_news_reader
node_news_sources -->|"stock news"| node_news_reader
node_news_reader -->|"normalized news"| node_sentiment_agent
node_pipeline -->|"prediction stage"| node_price_predictor
node_sentiment_agent -->|"sentiment signal"| node_trader
node_price_predictor -->|"price forecast"| node_trader
node_pipeline -->|"decision stage"| node_trader
node_sentiment_agent -->|"writes"| node_sentiment_logs
node_price_predictor -->|"writes"| node_prediction_logs
node_trader -->|"writes"| node_trader_logs
node_sentiment_logs -->|"stored in"| node_postgres
node_prediction_logs -->|"stored in"| node_postgres
node_trader_logs -->|"stored in"| node_postgres
node_claude_mcp -.->|"MCP connection"| node_postgres

click node_streamlit_ui "https://github.com/jngk07/stockagent/blob/main/app.py"
click node_pipeline "https://github.com/jngk07/stockagent/blob/main/main_pipeline.py"
click node_news_reader "https://github.com/jngk07/stockagent/blob/main/agent1_news_reader.py"
click node_sentiment_agent "https://github.com/jngk07/stockagent/blob/main/agent2_sentiment_signal.py"
click node_price_predictor "https://github.com/jngk07/stockagent/blob/main/agent4_price_predictor.py"
click node_trader "https://github.com/jngk07/stockagent/blob/main/agent3_trader.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_streamlit_ui,node_pipeline toneBlue
class node_news_reader,node_sentiment_agent,node_price_predictor,node_trader toneAmber
class node_postgres,node_sentiment_logs,node_prediction_logs,node_trader_logs,node_claude_mcp toneMint
class node_news_sources toneNeutral
```

## Components

### Application Runtime

- [Streamlit UI](https://github.com/jngk07/stockagent/blob/main/app.py): Streamlit app · `app.py`
- [Pipeline Orchestrator](https://github.com/jngk07/stockagent/blob/main/main_pipeline.py): Python workflow · Sequences the end-to-end trading workflow. · `main_pipeline.py`

### Trading Agents

- [News Reader](https://github.com/jngk07/stockagent/blob/main/agent1_news_reader.py): ingestion agent · Normalizes stock news for downstream agents. · `agent1_news_reader.py`
- [Sentiment Signal](https://github.com/jngk07/stockagent/blob/main/agent2_sentiment_signal.py): analysis agent · Converts news into trading-oriented sentiment. · `agent2_sentiment_signal.py`
- [Price Predictor](https://github.com/jngk07/stockagent/blob/main/agent4_price_predictor.py): forecasting agent · Produces price or direction forecasts independent of trade policy. · `agent4_price_predictor.py`
- [Trade Decision](https://github.com/jngk07/stockagent/blob/main/agent3_trader.py): policy agent · Combines evidence into buy/sell recommendations. · `agent3_trader.py`

### Persistence & Integration

- **PostgreSQL**: system of record · Stores sentiment, prediction, and trader logs.
- **Sentimental Logs**: log records
- **Price Prediction Logs**: log records
- **Trader Logs**: log records
- **Claude Desktop MCP**: external integration · Inspects the local PostgreSQL connection through MCP.

### Other components

- **External News Sources**: external data

## Connections

- Streamlit UI → Pipeline Orchestrator: runs workflow
- Pipeline Orchestrator → News Reader: news stage
- External News Sources → News Reader: stock news
- News Reader → Sentiment Signal: normalized news
- Pipeline Orchestrator → Price Predictor: prediction stage
- Sentiment Signal → Trade Decision: sentiment signal
- Price Predictor → Trade Decision: price forecast
- Pipeline Orchestrator → Trade Decision: decision stage
- Sentiment Signal → Sentimental Logs: writes
- Price Predictor → Price Prediction Logs: writes
- Trade Decision → Trader Logs: writes
- Sentimental Logs → PostgreSQL: stored in
- Price Prediction Logs → PostgreSQL: stored in
- Trader Logs → PostgreSQL: stored in
- Claude Desktop MCP → PostgreSQL: MCP connection
