# mattappsaibagus-wq/halal-global-stocks-and-crypto architecture

> Architecture diagram of the GitHub repository mattappsaibagus-wq/halal-global-stocks-and-crypto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mattappsaibagus-wq/halal-global-stocks-and-crypto
- Repository: https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto

## Overview

This repository is a Shariah-screened global equities and spot-crypto scanner with a dashboard and research tools. Its main workflow screens each watchlist symbol first, analyzes only HALAL assets for signals, consolidates recommendations, and publishes scan results for the dashboard. News is displayed as context, not used as a trading signal. README capabilities also include compliance alerts, signal tracking, backtesting, momentum rotation, and basket planning. The pipeline and selected agent interactions are supported by sampled source; some dashboard and scheduling details are documented in the README but their implementation was not sampled.

Main entry points: [`run_pipeline.py`](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/run_pipeline.py) (Scan Pipeline), [`agents/shariah_agent.py`](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/shariah_agent.py) (Shariah Screener), [`agents/advisor.py`](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/advisor.py) (Recommendation Advisor), [`agents/learning_loop.py`](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/learning_loop.py) (Signal Learning Loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Screening and Signals"]
  node_pipeline["Scan Pipeline<br/>[run_pipeline.py]"]
  node_screener["Shariah Screener<br/>[shariah_agent.py]"]
  node_standards["Screening Standards<br/>[standards.py]"]
  node_crypto_registry["Crypto Allowlist"]
  node_signal_agents["Technical Agents"]
  node_news["News Scanner<br/>[news_scanner.py]"]
end

subgraph group_advice["Advice and Tracking"]
  node_advisor["Recommendation Advisor<br/>[advisor.py]"]
  node_config["Advisor Configuration"]
  node_learning["Signal Learning Loop<br/>[learning_loop.py]"]
  node_learning_history[("Learning History")]
  node_executor["Trade Executor<br/>[executor.py]"]
  node_risk_guards["Execution Risk Guards<br/>[risk_guards.py]"]
  node_compliance["Compliance Watch"]
  node_compliance_state[("Compliance State")]
end

subgraph group_research["Research Tools"]
  node_backtest["Signal Backtest<br/>[backtest.py]"]
  node_rotation["Momentum Rotation<br/>[rotation.py]"]
end

subgraph group_presentation["Dashboard and Alerts"]
  node_dashboard["Dashboard<br/>[index.html]"]
  node_dashboard_data["Dashboard Scan Data"]
end

node_investor(("Investor"))
node_watchlist["Symbol Watchlist<br/>[watchlist.txt]"]
node_yahoo["Yahoo Finance"]
node_google_news["Google News RSS"]
node_github["GitHub Issues"]

node_investor -->|"edits symbols"| node_watchlist
node_watchlist -->|"loads symbols"| node_pipeline
node_pipeline -->|"screens first"| node_screener
node_screener -->|"applies rules"| node_standards
node_screener -->|"checks pairs"| node_crypto_registry
node_screener -->|"fetches fundamentals"| node_yahoo
node_pipeline -->|"runs for HALAL"| node_signal_agents
node_pipeline -->|"fetches headlines"| node_news
node_news -->|"requests feeds"| node_google_news
node_signal_agents -->|"fetches market data"| node_yahoo
node_pipeline -->|"consolidates results"| node_advisor
node_advisor -->|"loads settings"| node_config
node_pipeline -->|"records recommendations"| node_learning
node_learning -->|"reads and writes"| node_learning_history
node_learning -->|"fetches closes"| node_yahoo
node_pipeline -->|"updates screening state"| node_compliance
node_compliance -->|"reads and writes"| node_compliance_state
node_compliance -.->|"opens alert issue"| node_github
node_advisor -.->|"passes recommendations"| node_executor
node_executor -->|"checks trade"| node_risk_guards
node_executor -->|"fetches current price"| node_yahoo
node_backtest -->|"runs rotation test"| node_rotation
node_backtest -->|"fetches history"| node_yahoo
node_pipeline -->|"writes scan data"| node_dashboard_data
node_dashboard -->|"loads scan results"| node_dashboard_data
node_dashboard -->|"shows results"| node_investor

click node_watchlist "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/watchlist.txt"
click node_pipeline "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/run_pipeline.py"
click node_screener "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/shariah_agent.py"
click node_standards "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/standards.py"
click node_crypto_registry "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/data/halal_crypto_registry.json"
click node_signal_agents "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/agents"
click node_news "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/news_scanner.py"
click node_advisor "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/advisor.py"
click node_config "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/data/advisor_config.json"
click node_learning "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/learning_loop.py"
click node_learning_history "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/data"
click node_executor "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/trading/executor.py"
click node_risk_guards "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/trading/risk_guards.py"
click node_compliance "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/compliance_watch.py"
click node_compliance_state "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/data"
click node_backtest "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/backtest.py"
click node_rotation "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/rotation.py"
click node_dashboard "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/dashboard/index.html"
click node_dashboard_data "https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/dashboard"

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_pipeline,node_screener,node_standards,node_crypto_registry,node_signal_agents,node_news toneBlue
class node_advisor,node_config,node_learning,node_learning_history,node_executor,node_risk_guards,node_compliance,node_compliance_state toneAmber
class node_backtest,node_rotation toneMint
class node_dashboard,node_dashboard_data toneRose
class node_investor,node_yahoo,node_google_news,node_github toneIndigo
class node_watchlist toneTeal
```

## Components

### Screening and Signals

- [Scan Pipeline](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/run_pipeline.py): `run_pipeline.py`
- [Shariah Screener](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/shariah_agent.py): `agents/shariah_agent.py`
- [Screening Standards](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/standards.py): `agents/standards.py`
- [Crypto Allowlist](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/data/halal_crypto_registry.json): `data/halal_crypto_registry.json`
- [Technical Agents](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/agents): `agents`
- [News Scanner](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/news_scanner.py): `agents/news_scanner.py`

### Advice and Tracking

- [Recommendation Advisor](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/advisor.py): `agents/advisor.py`
- [Advisor Configuration](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/data/advisor_config.json): `data/advisor_config.json`
- [Signal Learning Loop](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/learning_loop.py): `agents/learning_loop.py`
- [Learning History](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/data): `data`
- [Trade Executor](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/trading/executor.py): `trading/executor.py`
- [Execution Risk Guards](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/trading/risk_guards.py): `trading/risk_guards.py`
- [Compliance Watch](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/agents/compliance_watch.py): `agents/compliance_watch.py`
- [Compliance State](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/data): `data`

### Research Tools

- [Signal Backtest](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/backtest.py): `backtest.py`
- [Momentum Rotation](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/rotation.py): `rotation.py`

### Dashboard and Alerts

- [Dashboard](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/dashboard/index.html): `dashboard/index.html`
- [Dashboard Scan Data](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/tree/main/dashboard): `dashboard`

### Other components

- **Investor**
- [Symbol Watchlist](https://github.com/mattappsaibagus-wq/halal-global-stocks-and-crypto/blob/main/watchlist.txt): `watchlist.txt`
- **Yahoo Finance**
- **Google News RSS**
- **GitHub Issues**

## Connections

- Investor → Symbol Watchlist: edits symbols
- Symbol Watchlist → Scan Pipeline: loads symbols
- Scan Pipeline → Shariah Screener: screens first
- Shariah Screener → Screening Standards: applies rules
- Shariah Screener → Crypto Allowlist: checks pairs
- Shariah Screener → Yahoo Finance: fetches fundamentals
- Scan Pipeline → Technical Agents: runs for HALAL
- Scan Pipeline → News Scanner: fetches headlines
- News Scanner → Google News RSS: requests feeds
- Technical Agents → Yahoo Finance: fetches market data
- Scan Pipeline → Recommendation Advisor: consolidates results
- Recommendation Advisor → Advisor Configuration: loads settings
- Scan Pipeline → Signal Learning Loop: records recommendations
- Signal Learning Loop → Learning History: reads and writes
- Signal Learning Loop → Yahoo Finance: fetches closes
- Scan Pipeline → Compliance Watch: updates screening state
- Compliance Watch → Compliance State: reads and writes
- Compliance Watch → GitHub Issues: opens alert issue
- Recommendation Advisor → Trade Executor: passes recommendations
- Trade Executor → Execution Risk Guards: checks trade
- Trade Executor → Yahoo Finance: fetches current price
- Signal Backtest → Momentum Rotation: runs rotation test
- Signal Backtest → Yahoo Finance: fetches history
- Scan Pipeline → Dashboard Scan Data: writes scan data
- Dashboard → Dashboard Scan Data: loads scan results
- Dashboard → Investor: shows results