# mohamedafzal0719/stock architecture

> Architecture diagram of the GitHub repository mohamedafzal0719/stock, 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/mohamedafzal0719/stock
- Repository: https://github.com/mohamedafzal0719/stock

## Overview

GoldBeES is a market-forecasting and trading platform with a Next.js dashboard and FastAPI backend. Its principal workflow is market-data acquisition and validation, feature generation, model training and evaluation, then API-served forecasts and analysis. The README also documents backtesting and explainability; the tree and source index show dedicated implementations for these and news, calendar, and agent capabilities. The graph follows documented or excerpted relationships; unsampled routes and integrations are not inferred.

Main entry points: [`backend/src/utils/db.py`](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/utils/db.py) (PostgreSQL stores), [`backend/api/main.py`](https://github.com/mohamedafzal0719/stock/blob/main/backend/api/main.py) (FastAPI routes), [`backend/src/features/engineer.py`](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/features/engineer.py) (Feature engineering), [`backend/src/services/inference.py`](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/inference.py) (Forecast inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Web dashboard<br/>[page.js]"]
end

subgraph group_api["API and workflows"]
  node_api_service["FastAPI routes<br/>[main.py]"]
  node_pipeline["Data pipeline trigger<br/>[main.py]"]
end

subgraph group_market["Market intelligence"]
  node_downloader["Market downloader<br/>[downloader.py]"]
  node_cleaner["Data cleaner<br/>[cleaner.py]"]
  node_features["Feature engineering<br/>[engineer.py]"]
  node_news["News sentiment<br/>[news_nlp.py]"]
  node_calendar["Economic calendar"]
end

subgraph group_ml["Forecasting models"]
  node_trainer["Model training<br/>[meta_model.py]"]
  node_train_dispatch["Training coordinator<br/>[train_all.py]"]
  node_deep_models["Deep architectures<br/>[deep_models.py]"]
  node_deep_wrapper["Sequence model wrapper<br/>[deep_wrapper.py]"]
  node_evaluator["Model evaluation<br/>[evaluator.py]"]
  node_inference["Forecast inference<br/>[inference.py]"]
  node_backtest["Strategy backtesting<br/>[backtest.py]"]
  node_agents["Trading agents<br/>[agents.py]"]
  node_rl["Reinforcement learning<br/>[rl_agent.py]"]
end

subgraph group_data["Persistence and quality"]
  node_validator["Data validation<br/>[validation.py]"]
  node_store[("PostgreSQL stores<br/>[db.py]")]
end

node_user(("Dashboard user"))
node_external_market(("Yahoo Finance"))
node_external_news(("RSS news sources"))

node_user -->|"uses"| node_dashboard
node_dashboard -.->|"requests data"| node_api_service
node_api_service -->|"triggers"| node_pipeline
node_pipeline -->|"runs download"| node_downloader
node_pipeline -->|"runs cleaning"| node_cleaner
node_pipeline -->|"runs engineering"| node_features
node_downloader -->|"downloads prices"| node_external_market
node_downloader -->|"validates data"| node_validator
node_cleaner -.->|"persists cleaned data"| node_store
node_features -->|"reads and writes features"| node_store
node_features -->|"uses sentiment"| node_news
node_features -.->|"uses calendar context"| node_calendar
node_news -->|"ingests feeds"| node_external_news
node_news -->|"stores events"| node_store
node_calendar -->|"uses database"| node_store
node_train_dispatch -->|"starts training"| node_trainer
node_trainer -->|"loads features and saves metrics"| node_store
node_trainer -->|"uses sequence models"| node_deep_wrapper
node_deep_wrapper -->|"builds architectures"| node_deep_models
node_trainer -.->|"evaluates predictions"| node_evaluator
node_api_service -->|"requests forecasts"| node_inference
node_inference -->|"loads engineered features"| node_features
node_inference -->|"uses deep model"| node_deep_wrapper
node_inference -->|"reads market events"| node_store
node_api_service -->|"exposes backtesting"| node_backtest
node_backtest -->|"requests predictions"| node_inference
node_api_service -->|"exposes agent features"| node_agents
node_agents -.->|"uses agent model"| node_rl

click node_dashboard "https://github.com/mohamedafzal0719/stock/blob/main/frontend/src/app/page.js"
click node_api_service "https://github.com/mohamedafzal0719/stock/blob/main/backend/api/main.py"
click node_pipeline "https://github.com/mohamedafzal0719/stock/blob/main/backend/api/main.py"
click node_downloader "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/data/downloader.py"
click node_cleaner "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/data/cleaner.py"
click node_validator "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/utils/validation.py"
click node_features "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/features/engineer.py"
click node_news "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/news_nlp.py"
click node_calendar "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/economic_calendar.py"
click node_store "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/utils/db.py"
click node_trainer "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/meta_model.py"
click node_train_dispatch "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/train_all.py"
click node_deep_models "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/deep_models.py"
click node_deep_wrapper "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/deep_wrapper.py"
click node_evaluator "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/evaluator.py"
click node_inference "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/inference.py"
click node_backtest "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/backtest.py"
click node_agents "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/agents.py"
click node_rl "https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/rl_agent.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_dashboard,node_user toneBlue
class node_api_service,node_pipeline toneAmber
class node_downloader,node_cleaner,node_features,node_news,node_calendar toneMint
class node_trainer,node_train_dispatch,node_deep_models,node_deep_wrapper,node_evaluator,node_inference,node_backtest,node_agents,node_rl toneRose
class node_validator,node_store,node_external_market,node_external_news toneIndigo
```

## Components

### Dashboard

- [Web dashboard](https://github.com/mohamedafzal0719/stock/blob/main/frontend/src/app/page.js): `frontend/src/app/page.js`

### API and workflows

- [FastAPI routes](https://github.com/mohamedafzal0719/stock/blob/main/backend/api/main.py): `backend/api/main.py`
- [Data pipeline trigger](https://github.com/mohamedafzal0719/stock/blob/main/backend/api/main.py): `backend/api/main.py`

### Market intelligence

- [Market downloader](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/data/downloader.py): `backend/src/data/downloader.py`
- [Data cleaner](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/data/cleaner.py): `backend/src/data/cleaner.py`
- [Feature engineering](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/features/engineer.py): `backend/src/features/engineer.py`
- [News sentiment](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/news_nlp.py): `backend/src/services/news_nlp.py`
- [Economic calendar](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/economic_calendar.py): `backend/src/services/economic_calendar.py`

### Forecasting models

- [Model training](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/meta_model.py): `backend/src/models/meta_model.py`
- [Training coordinator](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/train_all.py): `backend/src/models/train_all.py`
- [Deep architectures](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/deep_models.py): `backend/src/models/deep_models.py`
- [Sequence model wrapper](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/deep_wrapper.py): `backend/src/models/deep_wrapper.py`
- [Model evaluation](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/evaluator.py): `backend/src/models/evaluator.py`
- [Forecast inference](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/inference.py): `backend/src/services/inference.py`
- [Strategy backtesting](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/backtest.py): `backend/src/services/backtest.py`
- [Trading agents](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/services/agents.py): `backend/src/services/agents.py`
- [Reinforcement learning](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/models/rl_agent.py): `backend/src/models/rl_agent.py`

### Persistence and quality

- [Data validation](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/utils/validation.py): `backend/src/utils/validation.py`
- [PostgreSQL stores](https://github.com/mohamedafzal0719/stock/blob/main/backend/src/utils/db.py): `backend/src/utils/db.py`

### Other components

- **Dashboard user**
- **Yahoo Finance**
- **RSS news sources**

## Connections

- Dashboard user → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → FastAPI routes: requests data
- FastAPI routes → Data pipeline trigger: triggers (evidence: `backend/api/main.py`)
- Data pipeline trigger → Market downloader: runs download (evidence: `backend/api/main.py`)
- Data pipeline trigger → Data cleaner: runs cleaning (evidence: `backend/api/main.py`)
- Data pipeline trigger → Feature engineering: runs engineering (evidence: `backend/api/main.py`)
- Market downloader → Yahoo Finance: downloads prices (evidence: `backend/src/data/downloader.py`)
- Market downloader → Data validation: validates data (evidence: `backend/src/data/downloader.py`)
- Data cleaner → PostgreSQL stores: persists cleaned data
- Feature engineering → PostgreSQL stores: reads and writes features (evidence: `backend/src/features/engineer.py`)
- Feature engineering → News sentiment: uses sentiment (evidence: `backend/src/features/engineer.py`)
- Feature engineering → Economic calendar: uses calendar context (evidence: `backend/src/features/engineer.py`)
- News sentiment → RSS news sources: ingests feeds (evidence: `backend/src/services/news_nlp.py`)
- News sentiment → PostgreSQL stores: stores events (evidence: `backend/src/services/news_nlp.py`)
- Economic calendar → PostgreSQL stores: uses database (evidence: `backend/src/services/economic_calendar.py`)
- Training coordinator → Model training: starts training (evidence: `backend/src/models/train_all.py`)
- Model training → PostgreSQL stores: loads features and saves metrics (evidence: `backend/src/models/meta_model.py`)
- Model training → Sequence model wrapper: uses sequence models (evidence: `backend/src/models/meta_model.py`)
- Sequence model wrapper → Deep architectures: builds architectures (evidence: `backend/src/models/deep_wrapper.py`)
- Model training → Model evaluation: evaluates predictions
- FastAPI routes → Forecast inference: requests forecasts (evidence: `backend/api/main.py`)
- Forecast inference → Feature engineering: loads engineered features (evidence: `backend/src/services/inference.py`)
- Forecast inference → Sequence model wrapper: uses deep model (evidence: `backend/src/services/inference.py`)
- Forecast inference → PostgreSQL stores: reads market events (evidence: `backend/src/services/inference.py`)
- FastAPI routes → Strategy backtesting: exposes backtesting (evidence: `backend/api/main.py`)
- Strategy backtesting → Forecast inference: requests predictions (evidence: `backend/src/services/backtest.py`)
- FastAPI routes → Trading agents: exposes agent features (evidence: `backend/api/main.py`)
- Trading agents → Reinforcement learning: uses agent model
