# fbivinay/btc-paper-trader architecture

> Architecture diagram of the GitHub repository fbivinay/btc-paper-trader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fbivinay/btc-paper-trader
- Repository: https://github.com/fbivinay/btc-paper-trader

## Overview

Bitcoin ETF Trend Model is a daily paper-trading and portfolio-monitoring product for an Indian resident investing in Bitcoin and gold ETFs alongside T-bills. Its main workflow fetches and validates market data, computes target weights, records immutable decisions, and simulates the portfolio after tax and charges; a separate guarded execution run can send orders, while alerts support manual trading. The dashboard reads the stored record and presents performance, decisions, trades, alerts, and run health. Research compares candidate strategies. Some module internals were not sampled, so links to those documented capabilities are shown only at the orchestrator level.

Main entry points: [`ml/etf_daily.py`](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_daily.py) (Daily orchestrator), [`web/app/page.tsx`](https://github.com/fbivinay/btc-paper-trader/blob/main/web/app/page.tsx) (Dashboard page), [`ml/etf_research.py`](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_research.py) (Strategy comparison), [`ml/etf_data.py`](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_data.py) (Market data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operation["Daily operation"]
  node_daily["Daily orchestrator<br/>[etf_daily.py]"]
  node_prices["Market data<br/>[etf_data.py]"]
  node_ledger["Supabase REST client<br/>[db.py]"]
  node_dbschema[("Portfolio database<br/>[schema.sql]")]
end

subgraph group_portfolio["Model and portfolio"]
  node_model["Trend model<br/>[etf_model.py]"]
  node_taxsim["Tax portfolio simulation<br/>[etf_tax_sim.py]"]
end

subgraph group_execution["Trading and alerts"]
  node_brokerclient["Broker adapter<br/>[broker.py]"]
end

subgraph group_research["Strategy research"]
  node_research["Strategy comparison<br/>[etf_research.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard["Dashboard page<br/>[page.tsx]"]
  node_webclient["Browser data client<br/>[supabase.ts]"]
  node_stats["Performance statistics<br/>[stats.ts]"]
  node_chart["Equity chart<br/>[EquityChart.tsx]"]
  node_golive["Go-live guide<br/>[page.tsx]"]
end

node_schedule(("Scheduled runs"))
node_yahoo["Yahoo chart API"]
node_alpaca["Alpaca brokerage"]
node_push["Phone push service"]
node_browser(("Dashboard user"))

node_schedule -->|"starts run"| node_daily
node_daily -->|"loads prices"| node_prices
node_prices -->|"fetches quotes"| node_yahoo
node_daily -->|"computes weights"| node_model
node_daily -->|"simulates portfolio"| node_taxsim
node_daily -->|"records and reads"| node_ledger
node_ledger -->|"accesses tables"| node_dbschema
node_daily -.->|"requests rebalance"| node_brokerclient
node_brokerclient -.->|"submits orders"| node_alpaca
node_daily -.->|"sends alert"| node_push
node_research -->|"loads history"| node_prices
node_research -->|"uses signals"| node_model
node_research -->|"judges strategies"| node_taxsim
node_browser -->|"views"| node_dashboard
node_dashboard -->|"loads records"| node_webclient
node_webclient -->|"reads tables"| node_dbschema
node_dashboard -->|"calculates metrics"| node_stats
node_dashboard -->|"renders series"| node_chart
node_dashboard -->|"opens guide"| node_golive

click node_daily "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_daily.py"
click node_prices "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_data.py"
click node_model "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_model.py"
click node_taxsim "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_tax_sim.py"
click node_ledger "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/db.py"
click node_dbschema "https://github.com/fbivinay/btc-paper-trader/blob/main/supabase/schema.sql"
click node_research "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_research.py"
click node_brokerclient "https://github.com/fbivinay/btc-paper-trader/blob/main/ml/broker.py"
click node_dashboard "https://github.com/fbivinay/btc-paper-trader/blob/main/web/app/page.tsx"
click node_webclient "https://github.com/fbivinay/btc-paper-trader/blob/main/web/lib/supabase.ts"
click node_stats "https://github.com/fbivinay/btc-paper-trader/blob/main/web/lib/stats.ts"
click node_chart "https://github.com/fbivinay/btc-paper-trader/blob/main/web/components/EquityChart.tsx"
click node_golive "https://github.com/fbivinay/btc-paper-trader/blob/main/web/app/go-live/page.tsx"

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_daily,node_prices,node_ledger,node_dbschema,node_browser toneBlue
class node_model,node_taxsim toneAmber
class node_brokerclient,node_yahoo toneMint
class node_research toneRose
class node_dashboard,node_webclient,node_stats,node_chart,node_golive,node_schedule,node_alpaca,node_push toneIndigo
```

## Components

### Daily operation

- [Daily orchestrator](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_daily.py): `ml/etf_daily.py`
- [Market data](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_data.py): `ml/etf_data.py`
- [Supabase REST client](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/db.py): `ml/db.py`
- [Portfolio database](https://github.com/fbivinay/btc-paper-trader/blob/main/supabase/schema.sql): `supabase/schema.sql`

### Model and portfolio

- [Trend model](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_model.py): `ml/etf_model.py`
- [Tax portfolio simulation](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_tax_sim.py): `ml/etf_tax_sim.py`

### Trading and alerts

- [Broker adapter](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/broker.py): `ml/broker.py`

### Strategy research

- [Strategy comparison](https://github.com/fbivinay/btc-paper-trader/blob/main/ml/etf_research.py): `ml/etf_research.py`

### Dashboard

- [Dashboard page](https://github.com/fbivinay/btc-paper-trader/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Browser data client](https://github.com/fbivinay/btc-paper-trader/blob/main/web/lib/supabase.ts): `web/lib/supabase.ts`
- [Performance statistics](https://github.com/fbivinay/btc-paper-trader/blob/main/web/lib/stats.ts): `web/lib/stats.ts`
- [Equity chart](https://github.com/fbivinay/btc-paper-trader/blob/main/web/components/EquityChart.tsx): `web/components/EquityChart.tsx`
- [Go-live guide](https://github.com/fbivinay/btc-paper-trader/blob/main/web/app/go-live/page.tsx): `web/app/go-live/page.tsx`

### Other components

- **Scheduled runs**
- **Yahoo chart API**
- **Alpaca brokerage**
- **Phone push service**
- **Dashboard user**

## Connections

- Scheduled runs → Daily orchestrator: starts run
- Daily orchestrator → Market data: loads prices
- Market data → Yahoo chart API: fetches quotes
- Daily orchestrator → Trend model: computes weights
- Daily orchestrator → Tax portfolio simulation: simulates portfolio
- Daily orchestrator → Supabase REST client: records and reads
- Supabase REST client → Portfolio database: accesses tables
- Daily orchestrator → Broker adapter: requests rebalance
- Broker adapter → Alpaca brokerage: submits orders
- Daily orchestrator → Phone push service: sends alert
- Strategy comparison → Market data: loads history
- Strategy comparison → Trend model: uses signals
- Strategy comparison → Tax portfolio simulation: judges strategies
- Dashboard user → Dashboard page: views
- Dashboard page → Browser data client: loads records
- Browser data client → Portfolio database: reads tables
- Dashboard page → Performance statistics: calculates metrics
- Dashboard page → Equity chart: renders series
- Dashboard page → Go-live guide: opens guide