# putra10/papertrad architecture

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

## Overview

This is an LLM-driven Alpaca paper-trading bot: it checks the market session, assembles candidates and context, asks a model for decisions, executes paper orders, and records results for monitoring. Its main runtime is concentrated in `paper_trader.py`; the README documents additional dashboard and scheduled-session capabilities. Source excerpts are partial, so the graph omits uncertain internal wiring and treats the documented workflow as evidence for unsampled features.

Main entry points: [`paper_trader.py`](https://github.com/putra10/papertrad/blob/main/paper_trader.py) (Session runner), [`trade_log.jsonl`](https://github.com/putra10/papertrad/blob/main/trade_log.jsonl) (Trade event log), [`sync_dashboard.py`](https://github.com/putra10/papertrad/blob/main/sync_dashboard.py) (Portfolio mirror sync), [`build_dashboard.py`](https://github.com/putra10/papertrad/blob/main/build_dashboard.py) (Dashboard generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Trading workflow"]
  node_runner["Session runner<br/>[paper_trader.py]"]
  node_market_context["Market calendar<br/>[paper_trader.py]"]
  node_screen["Candidate screening<br/>[paper_trader.py]"]
  node_market_data["Market data context<br/>[paper_trader.py]"]
  node_news["News context<br/>[paper_trader.py]"]
  node_decision_prompt["Decision prompt<br/>[paper_trader.py]"]
  node_decision_engine["LLM decisions<br/>[paper_trader.py]"]
  node_order_planning["Order planning<br/>[paper_trader.py]"]
  node_order_execution["Paper order execution<br/>[paper_trader.py]"]
end

subgraph group_integrations["External services"]
  node_alpaca["Alpaca paper and market APIs"]
  node_openrouter["OpenRouter"]
  node_supabase[("Supabase account store")]
end

subgraph group_records["Trading records"]
  node_trade_log[("Trade event log<br/>[trade_log.jsonl]")]
  node_baseline[("Buy-and-hold baseline state")]
end

subgraph group_monitoring["Monitoring"]
  node_dashboard_builder["Dashboard generator<br/>[build_dashboard.py]"]
  node_dashboard_page["Equity and portfolio dashboard<br/>[index.html]"]
  node_dashboard_sync["Portfolio mirror sync<br/>[sync_dashboard.py]"]
end

node_operator(("Operator or scheduler"))
node_local_accounts[("Local dashboard accounts")]

node_operator -->|"starts run"| node_runner
node_runner -->|"checks session"| node_market_context
node_market_context -->|"requests clock/calendar"| node_alpaca
node_runner -->|"requests candidates"| node_screen
node_screen -->|"screens stocks"| node_alpaca
node_runner -->|"fetches tape and bars"| node_market_data
node_market_data -->|"reads snapshots/bars"| node_alpaca
node_runner -->|"fetches headlines"| node_news
node_news -->|"reads news"| node_alpaca
node_runner -->|"assembles context"| node_decision_prompt
node_market_context -->|"provides day context"| node_decision_prompt
node_screen -->|"provides candidates"| node_decision_prompt
node_market_data -->|"provides price history"| node_decision_prompt
node_news -->|"provides headlines"| node_decision_prompt
node_decision_prompt -->|"supplies prompt"| node_decision_engine
node_decision_engine -->|"requests completion"| node_openrouter
node_decision_engine -->|"returns decisions"| node_order_planning
node_runner -->|"provides account/positions"| node_order_planning
node_order_planning -->|"dispatches orders"| node_order_execution
node_order_execution -->|"submits and checks fills"| node_alpaca
node_runner -->|"records decisions and snapshots"| node_trade_log
node_order_execution -->|"records fills"| node_trade_log
node_runner -->|"reads/updates benchmark state"| node_baseline
node_runner -->|"rebuilds dashboard"| node_dashboard_builder
node_trade_log -->|"provides events"| node_dashboard_builder
node_dashboard_builder -->|"writes page"| node_dashboard_page
node_runner -.->|"invokes optional sync"| node_dashboard_sync
node_trade_log -->|"provides latest portfolio"| node_dashboard_sync
node_dashboard_sync -.->|"upserts account"| node_supabase
node_dashboard_sync -.->|"writes account"| node_local_accounts

click node_runner "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_market_context "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_screen "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_market_data "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_news "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_decision_prompt "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_decision_engine "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_order_planning "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_order_execution "https://github.com/putra10/papertrad/blob/main/paper_trader.py"
click node_trade_log "https://github.com/putra10/papertrad/blob/main/trade_log.jsonl"
click node_baseline "https://github.com/putra10/papertrad/blob/main/baseline_state.json"
click node_dashboard_builder "https://github.com/putra10/papertrad/blob/main/build_dashboard.py"
click node_dashboard_page "https://github.com/putra10/papertrad/blob/main/docs/index.html"
click node_dashboard_sync "https://github.com/putra10/papertrad/blob/main/sync_dashboard.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_runner,node_market_context,node_screen,node_market_data,node_news,node_decision_prompt,node_decision_engine,node_order_planning,node_order_execution toneBlue
class node_alpaca,node_openrouter,node_supabase,node_local_accounts toneAmber
class node_trade_log,node_baseline toneMint
class node_dashboard_builder,node_dashboard_page,node_dashboard_sync,node_operator toneRose
```

## Components

### Trading workflow

- [Session runner](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [Market calendar](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [Candidate screening](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [Market data context](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [News context](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [Decision prompt](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [LLM decisions](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [Order planning](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`
- [Paper order execution](https://github.com/putra10/papertrad/blob/main/paper_trader.py): `paper_trader.py`

### External services

- **Alpaca paper and market APIs**
- **OpenRouter**
- **Supabase account store**

### Trading records

- [Trade event log](https://github.com/putra10/papertrad/blob/main/trade_log.jsonl): `trade_log.jsonl`
- [Buy-and-hold baseline state](https://github.com/putra10/papertrad/blob/main/baseline_state.json): `baseline_state.json`

### Monitoring

- [Dashboard generator](https://github.com/putra10/papertrad/blob/main/build_dashboard.py): `build_dashboard.py`
- [Equity and portfolio dashboard](https://github.com/putra10/papertrad/blob/main/docs/index.html): `docs/index.html`
- [Portfolio mirror sync](https://github.com/putra10/papertrad/blob/main/sync_dashboard.py): `sync_dashboard.py`

### Other components

- **Operator or scheduler**
- **Local dashboard accounts**

## Connections

- Operator or scheduler → Session runner: starts run
- Session runner → Market calendar: checks session
- Market calendar → Alpaca paper and market APIs: requests clock/calendar
- Session runner → Candidate screening: requests candidates
- Candidate screening → Alpaca paper and market APIs: screens stocks
- Session runner → Market data context: fetches tape and bars
- Market data context → Alpaca paper and market APIs: reads snapshots/bars
- Session runner → News context: fetches headlines
- News context → Alpaca paper and market APIs: reads news
- Session runner → Decision prompt: assembles context
- Market calendar → Decision prompt: provides day context
- Candidate screening → Decision prompt: provides candidates
- Market data context → Decision prompt: provides price history
- News context → Decision prompt: provides headlines
- Decision prompt → LLM decisions: supplies prompt
- LLM decisions → OpenRouter: requests completion
- LLM decisions → Order planning: returns decisions
- Session runner → Order planning: provides account/positions
- Order planning → Paper order execution: dispatches orders
- Paper order execution → Alpaca paper and market APIs: submits and checks fills
- Session runner → Trade event log: records decisions and snapshots
- Paper order execution → Trade event log: records fills
- Session runner → Buy-and-hold baseline state: reads/updates benchmark state
- Session runner → Dashboard generator: rebuilds dashboard
- Trade event log → Dashboard generator: provides events
- Dashboard generator → Equity and portfolio dashboard: writes page
- Session runner → Portfolio mirror sync: invokes optional sync
- Trade event log → Portfolio mirror sync: provides latest portfolio
- Portfolio mirror sync → Supabase account store: upserts account
- Portfolio mirror sync → Local dashboard accounts: writes account