# ayushh404/falcon-hedge-fund architecture

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

- Interactive diagram: https://gitdiagram.com/ayushh404/falcon-hedge-fund
- Repository: https://github.com/ayushh404/falcon-hedge-fund

## Overview

This is an Indian-stock swing-trade signal generator, not a broker or execution system. The main workflow is a weekly scan: load market data, gate on market regime, rank sectors and stocks, evaluate setups and filters, then produce reviewable candidate cards. A user executes manually and approves taken trades for daily exit monitoring. Macro and announcement screening are additional candidate safeguards. Source excerpts and the index establish the weekly orchestration and selected calls; daily tracking and several optional capabilities are represented from README documentation.

Main entry points: [`pipeline.py`](https://github.com/ayushh404/falcon-hedge-fund/blob/main/pipeline.py) (Weekly and daily orchestration), [`macro.py`](https://github.com/ayushh404/falcon-hedge-fund/blob/main/macro.py) (Macro catalyst tilts), [`data.py`](https://github.com/ayushh404/falcon-hedge-fund/blob/main/data.py) (Market data loader), [`main.py`](https://github.com/ayushh404/falcon-hedge-fund/blob/main/main.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run control"]
  node_cli["CLI commands<br/>[main.py]"]
  node_pipeline["Weekly and daily orchestration<br/>[pipeline.py]"]
  node_backtest["Ranking backtest<br/>[backtest.py]"]
end

subgraph group_signals["Signal pipeline"]
  node_regime["Market regime gate<br/>[regime.py]"]
  node_sector_rank["Sector ranking<br/>[sectors.py]"]
  node_stock_rank["Stock factor ranking<br/>[scoring.py]"]
  node_technical_setup["Technical setups<br/>[technicals.py]"]
  node_indicators["Indicator calculations<br/>[indicators.py]"]
  node_filters["Hard candidate filters<br/>[filters.py]"]
end

subgraph group_safeguards["Review safeguards"]
  node_macro_engine["Macro catalyst tilts<br/>[macro.py]"]
  node_exposure_map["Exposure map<br/>[exposure_map.yaml]"]
  node_yaml_reader["YAML reader<br/>[yaml_lite.py]"]
  node_news_feed["News event extraction<br/>[news.py]"]
  node_news_filter["Announcement screening<br/>[news_filter.py]"]
  node_ai_review["Chart and news review<br/>[ai_review.py]"]
  node_gallery["Review gallery<br/>[gallery.py]"]
end

subgraph group_tracking["Tracking and alerts"]
  node_position_risk["Sizing and exits<br/>[risk.py]"]
  node_reporting["Charts and Telegram cards<br/>[report.py]"]
  node_state[("Position state<br/>[state.json]")]
  node_candidate_output["Candidate and watchlist outputs"]
end

subgraph group_runtime["Data and integrations"]
  node_market_data["Market data loader<br/>[data.py]"]
  node_universe["NSE universe lists<br/>[nse_lists.py]"]
  node_synthetic["Demo data<br/>[synthetic.py]"]
  node_announcements["NSE announcements"]
end

node_user(("Operator"))
node_manual_broker(("Manual broker action"))
node_telegram["Telegram"]
node_anthropic["Anthropic API"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches scans"| node_pipeline
node_cli -->|"runs backtest"| node_backtest
node_pipeline -->|"loads data"| node_market_data
node_market_data -->|"refreshes universe"| node_universe
node_market_data -->|"uses for demo"| node_synthetic
node_market_data -.->|"fetches market prices"| node_user
node_pipeline -->|"checks regime"| node_regime
node_pipeline -->|"ranks sectors"| node_sector_rank
node_pipeline -->|"scores stocks"| node_stock_rank
node_stock_rank -->|"analyzes setups"| node_technical_setup
node_technical_setup -->|"uses indicators"| node_indicators
node_pipeline -->|"filters candidates"| node_filters
node_pipeline -->|"sizes positions"| node_position_risk
node_pipeline -->|"computes macro tilts"| node_macro_engine
node_macro_engine -->|"loads sensitivities"| node_exposure_map
node_macro_engine -->|"reads map"| node_yaml_reader
node_macro_engine -->|"extracts events"| node_news_feed
node_news_feed -.->|"labels events"| node_anthropic
node_macro_engine -->|"uses market proxies"| node_market_data
node_pipeline -->|"screens survivors"| node_news_filter
node_news_filter -->|"fetches filings"| node_announcements
node_news_filter -->|"reviews flags"| node_ai_review
node_pipeline -->|"reviews charts"| node_ai_review
node_ai_review -->|"requests review"| node_anthropic
node_pipeline -->|"writes review gallery"| node_gallery
node_pipeline -->|"renders and sends cards"| node_reporting
node_reporting -->|"sends alerts"| node_telegram
node_user -->|"executes manually"| node_manual_broker
node_user -->|"approves taken trades"| node_pipeline
node_telegram -->|"polls approvals"| node_cli
node_pipeline -->|"checks daily exits"| node_position_risk
node_position_risk -->|"calculates trailing stops"| node_indicators
node_pipeline -->|"updates tracking state"| node_state
node_pipeline -->|"writes scan results"| node_candidate_output
node_pipeline -->|"sends exit alerts"| node_reporting

click node_cli "https://github.com/ayushh404/falcon-hedge-fund/blob/main/main.py"
click node_pipeline "https://github.com/ayushh404/falcon-hedge-fund/blob/main/pipeline.py"
click node_market_data "https://github.com/ayushh404/falcon-hedge-fund/blob/main/data.py"
click node_universe "https://github.com/ayushh404/falcon-hedge-fund/blob/main/nse_lists.py"
click node_synthetic "https://github.com/ayushh404/falcon-hedge-fund/blob/main/synthetic.py"
click node_regime "https://github.com/ayushh404/falcon-hedge-fund/blob/main/regime.py"
click node_sector_rank "https://github.com/ayushh404/falcon-hedge-fund/blob/main/sectors.py"
click node_stock_rank "https://github.com/ayushh404/falcon-hedge-fund/blob/main/scoring.py"
click node_technical_setup "https://github.com/ayushh404/falcon-hedge-fund/blob/main/technicals.py"
click node_indicators "https://github.com/ayushh404/falcon-hedge-fund/blob/main/indicators.py"
click node_filters "https://github.com/ayushh404/falcon-hedge-fund/blob/main/filters.py"
click node_position_risk "https://github.com/ayushh404/falcon-hedge-fund/blob/main/risk.py"
click node_macro_engine "https://github.com/ayushh404/falcon-hedge-fund/blob/main/macro.py"
click node_exposure_map "https://github.com/ayushh404/falcon-hedge-fund/blob/main/data/exposure_map.yaml"
click node_yaml_reader "https://github.com/ayushh404/falcon-hedge-fund/blob/main/yaml_lite.py"
click node_news_feed "https://github.com/ayushh404/falcon-hedge-fund/blob/main/news.py"
click node_news_filter "https://github.com/ayushh404/falcon-hedge-fund/blob/main/news_filter.py"
click node_announcements "https://github.com/ayushh404/falcon-hedge-fund/blob/main/nse_announcements.py"
click node_ai_review "https://github.com/ayushh404/falcon-hedge-fund/blob/main/ai_review.py"
click node_gallery "https://github.com/ayushh404/falcon-hedge-fund/blob/main/gallery.py"
click node_reporting "https://github.com/ayushh404/falcon-hedge-fund/blob/main/report.py"
click node_state "https://github.com/ayushh404/falcon-hedge-fund/blob/main/data/state.json"
click node_candidate_output "https://github.com/ayushh404/falcon-hedge-fund/tree/main/out"
click node_backtest "https://github.com/ayushh404/falcon-hedge-fund/blob/main/backtest.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_cli,node_pipeline,node_backtest toneBlue
class node_regime,node_sector_rank,node_stock_rank,node_technical_setup,node_indicators,node_filters toneAmber
class node_macro_engine,node_exposure_map,node_yaml_reader,node_news_feed,node_news_filter,node_ai_review,node_gallery,node_anthropic toneMint
class node_position_risk,node_reporting,node_state,node_candidate_output toneRose
class node_market_data,node_universe,node_synthetic,node_announcements,node_user,node_manual_broker,node_telegram toneIndigo
```

## Components

### Run control

- [CLI commands](https://github.com/ayushh404/falcon-hedge-fund/blob/main/main.py): `main.py`
- [Weekly and daily orchestration](https://github.com/ayushh404/falcon-hedge-fund/blob/main/pipeline.py): `pipeline.py`
- [Ranking backtest](https://github.com/ayushh404/falcon-hedge-fund/blob/main/backtest.py): `backtest.py`

### Signal pipeline

- [Market regime gate](https://github.com/ayushh404/falcon-hedge-fund/blob/main/regime.py): `regime.py`
- [Sector ranking](https://github.com/ayushh404/falcon-hedge-fund/blob/main/sectors.py): `sectors.py`
- [Stock factor ranking](https://github.com/ayushh404/falcon-hedge-fund/blob/main/scoring.py): `scoring.py`
- [Technical setups](https://github.com/ayushh404/falcon-hedge-fund/blob/main/technicals.py): `technicals.py`
- [Indicator calculations](https://github.com/ayushh404/falcon-hedge-fund/blob/main/indicators.py): `indicators.py`
- [Hard candidate filters](https://github.com/ayushh404/falcon-hedge-fund/blob/main/filters.py): `filters.py`

### Review safeguards

- [Macro catalyst tilts](https://github.com/ayushh404/falcon-hedge-fund/blob/main/macro.py): `macro.py`
- [Exposure map](https://github.com/ayushh404/falcon-hedge-fund/blob/main/data/exposure_map.yaml): `data/exposure_map.yaml`
- [YAML reader](https://github.com/ayushh404/falcon-hedge-fund/blob/main/yaml_lite.py): `yaml_lite.py`
- [News event extraction](https://github.com/ayushh404/falcon-hedge-fund/blob/main/news.py): `news.py`
- [Announcement screening](https://github.com/ayushh404/falcon-hedge-fund/blob/main/news_filter.py): `news_filter.py`
- [Chart and news review](https://github.com/ayushh404/falcon-hedge-fund/blob/main/ai_review.py): `ai_review.py`
- [Review gallery](https://github.com/ayushh404/falcon-hedge-fund/blob/main/gallery.py): `gallery.py`

### Tracking and alerts

- [Sizing and exits](https://github.com/ayushh404/falcon-hedge-fund/blob/main/risk.py): `risk.py`
- [Charts and Telegram cards](https://github.com/ayushh404/falcon-hedge-fund/blob/main/report.py): `report.py`
- [Position state](https://github.com/ayushh404/falcon-hedge-fund/blob/main/data/state.json): `data/state.json`
- [Candidate and watchlist outputs](https://github.com/ayushh404/falcon-hedge-fund/tree/main/out): `out`

### Data and integrations

- [Market data loader](https://github.com/ayushh404/falcon-hedge-fund/blob/main/data.py): `data.py`
- [NSE universe lists](https://github.com/ayushh404/falcon-hedge-fund/blob/main/nse_lists.py): `nse_lists.py`
- [Demo data](https://github.com/ayushh404/falcon-hedge-fund/blob/main/synthetic.py): `synthetic.py`
- [NSE announcements](https://github.com/ayushh404/falcon-hedge-fund/blob/main/nse_announcements.py): `nse_announcements.py`

### Other components

- **Operator**
- **Manual broker action**
- **Telegram**
- **Anthropic API**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Weekly and daily orchestration: dispatches scans (evidence: `main.py`)
- CLI commands → Ranking backtest: runs backtest (evidence: `main.py`)
- Weekly and daily orchestration → Market data loader: loads data (evidence: `pipeline.py`)
- Market data loader → NSE universe lists: refreshes universe (evidence: `data.py`)
- Market data loader → Demo data: uses for demo (evidence: `data.py`)
- Market data loader → Operator: fetches market prices
- Weekly and daily orchestration → Market regime gate: checks regime (evidence: `pipeline.py`)
- Weekly and daily orchestration → Sector ranking: ranks sectors (evidence: `pipeline.py`)
- Weekly and daily orchestration → Stock factor ranking: scores stocks (evidence: `pipeline.py`)
- Stock factor ranking → Technical setups: analyzes setups (evidence: `scoring.py`)
- Technical setups → Indicator calculations: uses indicators (evidence: `technicals.py`)
- Weekly and daily orchestration → Hard candidate filters: filters candidates (evidence: `pipeline.py`)
- Weekly and daily orchestration → Sizing and exits: sizes positions (evidence: `pipeline.py`)
- Weekly and daily orchestration → Macro catalyst tilts: computes macro tilts (evidence: `pipeline.py`)
- Macro catalyst tilts → Exposure map: loads sensitivities (evidence: `README.md`)
- Macro catalyst tilts → YAML reader: reads map (evidence: `macro.py`)
- Macro catalyst tilts → News event extraction: extracts events (evidence: `macro.py`)
- News event extraction → Anthropic API: labels events (evidence: `README.md`)
- Macro catalyst tilts → Market data loader: uses market proxies (evidence: `README.md`)
- Weekly and daily orchestration → Announcement screening: screens survivors (evidence: `pipeline.py`)
- Announcement screening → NSE announcements: fetches filings (evidence: `news_filter.py`)
- Announcement screening → Chart and news review: reviews flags (evidence: `news_filter.py`)
- Weekly and daily orchestration → Chart and news review: reviews charts (evidence: `pipeline.py`)
- Chart and news review → Anthropic API: requests review (evidence: `README.md`)
- Weekly and daily orchestration → Review gallery: writes review gallery (evidence: `pipeline.py`)
- Weekly and daily orchestration → Charts and Telegram cards: renders and sends cards (evidence: `pipeline.py`)
- Charts and Telegram cards → Telegram: sends alerts (evidence: `report.py`)
- Operator → Manual broker action: executes manually (evidence: `README.md`)
- Operator → Weekly and daily orchestration: approves taken trades (evidence: `README.md`)
- Telegram → CLI commands: polls approvals (evidence: `README.md`)
- Weekly and daily orchestration → Sizing and exits: checks daily exits (evidence: `README.md`)
- Sizing and exits → Indicator calculations: calculates trailing stops (evidence: `risk.py`)
- Weekly and daily orchestration → Position state: updates tracking state (evidence: `README.md`)
- Weekly and daily orchestration → Candidate and watchlist outputs: writes scan results (evidence: `pipeline.py`)
- Weekly and daily orchestration → Charts and Telegram cards: sends exit alerts (evidence: `README.md`)
