2. System Architecture - IBD Growth Strategy

2.1 Data flow (end-to-end)¶

┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA SOURCES                                                                 │
│  • IBD exports (.xls): Big Cap 20, Big Cap 50 (IBD 50 screen), RS Master      │
│  • E*TRADE raw CSVs: IRA + Brokerage positions                               │
│  • Market data: yfinance (prices, beta, market cap, debt, ^TNX)              │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ INGESTION                                                                    │
│  watch_downloads.py  → rename/move files into data/input + holdings          │
│  normalize_etrade.py → Ticker, Shares, Cost_Basis                            │
│  ingest_ibd_lists.py → IRA_Watchlist, Brokerage_Watchlist, Conviction         │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SCORING & RISK                                                               │
│  capm_wacc.py        → Rf, CAPM, Beta_Penalty, Alpha_Gap, WACC_Stock         │
│  (embedded in ingest + portfolio_analyzer)                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ ANALYSIS (per account)                                                       │
│  portfolio_analyzer.py → join holdings × universe, status flags, reports    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ OUTPUT                                                                       │
│  CSV reports/summaries, performance_history.csv, kpi_summary.csv,            │
│  performance_latest.json, performance_tracker_state.json                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ DASHBOARD                                                                    │
│  dashboard.html (browser) ← fetch data/output/performance_latest.json        │
│  (served via python -m http.server or weekly_run auto-launch)                │
└─────────────────────────────────────────────────────────────────────────────┘

2.2 Two-strategy split (IRA vs Brokerage)¶

Aspect	IRA strategy	Brokerage strategy
Policy (May 2026)	Aggressive momentum; tax-free rotation	Quality buy-and-hold; minimize ST gains
Universe	Big Cap 20 + Big Cap 50 (merged)	IBD RS Master (screen); BC20 quality names for entries
Primary sort	`IBD_Rank` (asc), with multi-list priority	`Price_Change_Pct` positive first, then `Risk_Adj_Leader_Score` (desc)
Core score	`Risk_Adj_Score` = `Composite_Rating` × `Beta_Penalty`	`Risk_Adj_Leader_Score` = `Leader_Score` × `Beta_Penalty`
Hold horizon	Days to weeks (follow signals)	12+ months minimum when possible
Watchlist output	`data/output/IRA_Watchlist.csv`	`data/output/Brokerage_Watchlist.csv`
Portfolio analyzer	`--strategy ira`	`--strategy brokerage`
Position status	`ON_LIST` / `WATCH`	`LEADER` / `RISK`

Cross-strategy: tickers present in both watchlists feed Cross_Strategy_Conviction.csv and Cross_Strategy flags on holdings when applicable.

2.3 Pipeline file roles (every file)¶

File	Role
`watch_downloads.py`	Watches `~/Downloads` (+ optional IBD folders), classifies IBD/E*TRADE files with `etrade_identify.py`, renames and moves into `data/input/` and `holdings/`.
`etrade_identify.py`	Pure classifier: filename + first lines → `ira`, `brokerage`, or IBD subtype.
`normalize_etrade.py`	Raw E*TRADE position export → `Ticker`, `Shares`, `Cost_Basis`.
`ingest_ibd_lists.py`	Parses IBD `.xls` (via LibreOffice CSV) or CSV; builds IRA + Brokerage watchlists + conviction merge; runs CAPM/WACC enrichment.
`capm_wacc.py`	Shared math: Rf, CAPM, beta penalty, alpha gap, per-stock WACC, portfolio WACC.
`portfolio_analyzer.py`	Joins normalized holdings to a watchlist; yfinance prices; IRA or Brokerage columns; writes `_Report.csv` / `_Summary.csv`.
`performance_tracker.py`	Weekly snapshot: hypothetical top 5 / conviction 9 + actual accounts; CSV + JSON; `--force` for same-week re-run.
`weekly_run.py`	Orchestrates steps 1–6: normalize → ingest → portfolio_analyzer ×2 → Excel open → performance snapshot → opens dashboard URL (HTTP server on 8765 if free).
`process_growth_stocks.py`	Standalone RS / Leader Score + CAPM pipeline (legacy / alternate weekly summary); not required for `weekly_run.py`.
`dashboard.html`	Single-page UI; reads `data/output/performance_latest.json` via `fetch`.