# fedzg/tradingsim architecture

> Architecture diagram of the GitHub repository fedzg/tradingsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fedzg/tradingsim
- Repository: https://github.com/fedzg/tradingsim

## Overview

TradingSim is a scheduled, Alpaca Paper-only trading worker. Its main workflow wakes at Rome-time slots, gathers broker and market data, produces analysis, and—outside the briefing slot—reviews proposals against risk constraints before execution. It also scans candidate markets for permissioned, monitoring-only watchlist additions and queues reports and alerts for Telegram. The run-loop and several subsystem calls are visible in excerpts; some capability links rely on README statements or source-index references, so unsampled implementation details are not inferred.

Main entry points: [`src/run.ts`](https://github.com/fedzg/tradingsim/blob/main/src/run.ts) (Scheduled worker), [`src/broker.ts`](https://github.com/fedzg/tradingsim/blob/main/src/broker.ts) (Paper broker), [`src/market.ts`](https://github.com/fedzg/tradingsim/blob/main/src/market.ts) (Market data), [`src/order-review-context.ts`](https://github.com/fedzg/tradingsim/blob/main/src/order-review-context.ts) (Order review context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Scheduling and orchestration"]
  node_worker["Scheduled worker<br/>[run.ts]"]
  node_wake["Wake schedule<br/>[time.ts]"]
end

subgraph group_trading["Trading and review"]
  node_broker["Paper broker<br/>[broker.ts]"]
  node_mcp["Alpaca MCP client<br/>[mcp.ts]"]
  node_agents["Analyst agents<br/>[agents.ts]"]
  node_review["Order review context"]
  node_risk["Risk checks<br/>[risk.ts]"]
end

subgraph group_market["Market analysis and discovery"]
  node_marketdata["Market data<br/>[market.ts]"]
  node_indicators["Market indicators<br/>[indicators.ts]"]
  node_discovery["Market discovery<br/>[discovery.ts]"]
  node_discoveryfeeds["Discovery feeds"]
  node_chartscenarios["Chart scenarios<br/>[chart-scenarios.ts]"]
  node_news["News signals<br/>[news-signals.ts]"]
  node_efficiency["Feed metrics"]
end

subgraph group_delivery["State and notifications"]
  node_state[("Runtime state<br/>[state.ts]")]
  node_chat["Notification outbox<br/>[chat.ts]"]
  node_notifications["Notification formatting<br/>[notifications.ts]"]
  node_telegram["Telegram channel<br/>[telegram.ts]"]
end

node_operator(("Operator"))
node_codex["Codex CLI"]
node_yahoo["Yahoo Finance"]
node_telegramservice["Telegram"]

node_operator -->|"starts or checks"| node_worker
node_worker -->|"uses schedule"| node_wake
node_worker -->|"loads snapshot"| node_broker
node_broker -->|"requests account data"| node_mcp
node_mcp -->|"returns tool data"| node_broker
node_worker -->|"loads charts and news"| node_marketdata
node_marketdata -->|"requests stock bars"| node_mcp
node_marketdata -->|"loads price series"| node_yahoo
node_worker -->|"measures feeds"| node_efficiency
node_worker -->|"reviews proposals"| node_agents
node_agents -->|"invokes analysis"| node_codex
node_worker -->|"builds review context"| node_review
node_review -->|"uses market evidence"| node_indicators
node_review -->|"uses risk limits"| node_risk
node_worker -->|"checks and gates orders"| node_risk
node_worker -->|"runs discovery"| node_discovery
node_discovery -->|"scans instruments"| node_discoveryfeeds
node_discoveryfeeds -->|"loads series"| node_marketdata
node_discoveryfeeds -->|"computes evidence"| node_indicators
node_worker -->|"builds scenarios"| node_chartscenarios
node_worker -->|"uses news signals"| node_news
node_worker -->|"reads and writes state"| node_state
node_broker -->|"reads fake broker state"| node_state
node_worker -->|"queues report and alerts"| node_chat
node_chat -->|"persists outbox"| node_state
node_worker -->|"formats notifications"| node_notifications
node_notifications -->|"uses order data"| node_broker
node_notifications -->|"queues messages"| node_chat
node_telegram -->|"delivers messages"| node_telegramservice
node_operator -->|"grants watchlist permission"| node_discovery

click node_worker "https://github.com/fedzg/tradingsim/blob/main/src/run.ts"
click node_wake "https://github.com/fedzg/tradingsim/blob/main/src/time.ts"
click node_broker "https://github.com/fedzg/tradingsim/blob/main/src/broker.ts"
click node_mcp "https://github.com/fedzg/tradingsim/blob/main/src/mcp.ts"
click node_agents "https://github.com/fedzg/tradingsim/blob/main/src/agents.ts"
click node_review "https://github.com/fedzg/tradingsim/blob/main/src/order-review-context.ts"
click node_risk "https://github.com/fedzg/tradingsim/blob/main/src/risk.ts"
click node_marketdata "https://github.com/fedzg/tradingsim/blob/main/src/market.ts"
click node_indicators "https://github.com/fedzg/tradingsim/blob/main/src/indicators.ts"
click node_discovery "https://github.com/fedzg/tradingsim/blob/main/src/discovery.ts"
click node_discoveryfeeds "https://github.com/fedzg/tradingsim/blob/main/src/discovery-sources.ts"
click node_chartscenarios "https://github.com/fedzg/tradingsim/blob/main/src/chart-scenarios.ts"
click node_news "https://github.com/fedzg/tradingsim/blob/main/src/news-signals.ts"
click node_efficiency "https://github.com/fedzg/tradingsim/blob/main/src/efficiency-metrics.ts"
click node_state "https://github.com/fedzg/tradingsim/blob/main/src/state.ts"
click node_chat "https://github.com/fedzg/tradingsim/blob/main/src/chat.ts"
click node_notifications "https://github.com/fedzg/tradingsim/blob/main/src/notifications.ts"
click node_telegram "https://github.com/fedzg/tradingsim/blob/main/src/telegram.ts"

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_worker,node_wake toneBlue
class node_broker,node_mcp,node_agents,node_review,node_risk toneAmber
class node_marketdata,node_indicators,node_discovery,node_discoveryfeeds,node_chartscenarios,node_news,node_efficiency toneMint
class node_state,node_chat,node_notifications,node_telegram toneRose
class node_operator,node_codex,node_yahoo,node_telegramservice toneIndigo
```

## Components

### Scheduling and orchestration

- [Scheduled worker](https://github.com/fedzg/tradingsim/blob/main/src/run.ts): `src/run.ts`
- [Wake schedule](https://github.com/fedzg/tradingsim/blob/main/src/time.ts): `src/time.ts`

### Trading and review

- [Paper broker](https://github.com/fedzg/tradingsim/blob/main/src/broker.ts): `src/broker.ts`
- [Alpaca MCP client](https://github.com/fedzg/tradingsim/blob/main/src/mcp.ts): `src/mcp.ts`
- [Analyst agents](https://github.com/fedzg/tradingsim/blob/main/src/agents.ts): `src/agents.ts`
- [Order review context](https://github.com/fedzg/tradingsim/blob/main/src/order-review-context.ts): `src/order-review-context.ts`
- [Risk checks](https://github.com/fedzg/tradingsim/blob/main/src/risk.ts): `src/risk.ts`

### Market analysis and discovery

- [Market data](https://github.com/fedzg/tradingsim/blob/main/src/market.ts): `src/market.ts`
- [Market indicators](https://github.com/fedzg/tradingsim/blob/main/src/indicators.ts): `src/indicators.ts`
- [Market discovery](https://github.com/fedzg/tradingsim/blob/main/src/discovery.ts): `src/discovery.ts`
- [Discovery feeds](https://github.com/fedzg/tradingsim/blob/main/src/discovery-sources.ts): `src/discovery-sources.ts`
- [Chart scenarios](https://github.com/fedzg/tradingsim/blob/main/src/chart-scenarios.ts): `src/chart-scenarios.ts`
- [News signals](https://github.com/fedzg/tradingsim/blob/main/src/news-signals.ts): `src/news-signals.ts`
- [Feed metrics](https://github.com/fedzg/tradingsim/blob/main/src/efficiency-metrics.ts): `src/efficiency-metrics.ts`

### State and notifications

- [Runtime state](https://github.com/fedzg/tradingsim/blob/main/src/state.ts): `src/state.ts`
- [Notification outbox](https://github.com/fedzg/tradingsim/blob/main/src/chat.ts): `src/chat.ts`
- [Notification formatting](https://github.com/fedzg/tradingsim/blob/main/src/notifications.ts): `src/notifications.ts`
- [Telegram channel](https://github.com/fedzg/tradingsim/blob/main/src/telegram.ts): `src/telegram.ts`

### Other components

- **Operator**
- **Codex CLI**
- **Yahoo Finance**
- **Telegram**

## Connections

- Operator → Scheduled worker: starts or checks (evidence: `README.md`)
- Scheduled worker → Wake schedule: uses schedule (evidence: `src/run.ts`)
- Scheduled worker → Paper broker: loads snapshot (evidence: `src/run.ts`)
- Paper broker → Alpaca MCP client: requests account data (evidence: `src/broker.ts`)
- Alpaca MCP client → Paper broker: returns tool data (evidence: `src/broker.ts`)
- Scheduled worker → Market data: loads charts and news (evidence: `src/run.ts`)
- Market data → Alpaca MCP client: requests stock bars (evidence: `src/market.ts`)
- Market data → Yahoo Finance: loads price series (evidence: `src/market.ts`)
- Scheduled worker → Feed metrics: measures feeds (evidence: `src/run.ts`)
- Scheduled worker → Analyst agents: reviews proposals (evidence: `src/run.ts`)
- Analyst agents → Codex CLI: invokes analysis (evidence: `src/agents.ts`)
- Scheduled worker → Order review context: builds review context (evidence: `src/run.ts`)
- Order review context → Market indicators: uses market evidence (evidence: `src/order-review-context.ts`)
- Order review context → Risk checks: uses risk limits (evidence: `src/order-review-context.ts`)
- Scheduled worker → Risk checks: checks and gates orders (evidence: `src/run.ts`)
- Scheduled worker → Market discovery: runs discovery (evidence: `src/discovery.ts`)
- Market discovery → Discovery feeds: scans instruments (evidence: `src/discovery.ts`)
- Discovery feeds → Market data: loads series (evidence: `src/discovery-sources.ts`)
- Discovery feeds → Market indicators: computes evidence (evidence: `src/discovery-sources.ts`)
- Scheduled worker → Chart scenarios: builds scenarios (evidence: `src/run.ts`)
- Scheduled worker → News signals: uses news signals (evidence: `README.md`)
- Scheduled worker → Runtime state: reads and writes state (evidence: `src/run.ts`)
- Paper broker → Runtime state: reads fake broker state (evidence: `src/broker.ts`)
- Scheduled worker → Notification outbox: queues report and alerts (evidence: `src/run.ts`)
- Notification outbox → Runtime state: persists outbox (evidence: `src/chat.ts`)
- Scheduled worker → Notification formatting: formats notifications (evidence: `src/run.ts`)
- Notification formatting → Paper broker: uses order data (evidence: `src/notifications.ts`)
- Notification formatting → Notification outbox: queues messages (evidence: `src/notifications.ts`)
- Telegram channel → Telegram: delivers messages (evidence: `README.md`)
- Operator → Market discovery: grants watchlist permission (evidence: `README.md`)
