# tomortec/cryptotradingagents architecture

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

- Interactive diagram: https://gitdiagram.com/tomortec/cryptotradingagents
- Repository: https://github.com/tomortec/cryptotradingagents

## Overview

Crypto Trading Agents is a research-and-reporting application: a user supplies an asset, date, analyst selection, and optional context, then receives a trading analysis report. The main stages are data gathering and analyst reports, bull/bear research debate, risk debate, and final trader recommendation. The README also documents Markdown/PDF output, live report logging, and optional scheduled email delivery. The excerpts show the CLI initializing graph state and the graph constructing data tools and memories; detailed runtime wiring for unsampled modules is represented only where documented.

Main entry points: [`tradingagents/agents/utils/memory.py`](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/memory.py) (Situation memory), [`tradingagents/graph/setup.py`](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/graph/setup.py) (Graph setup), [`tradingagents/agents/analysts`](https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/analysts) (Analyst team), [`tradingagents/graph/trading_graph.py`](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/graph/trading_graph.py) (Trading graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry and reports"]
  node_cli["CLI and reports<br/>[main.py]"]
  node_script["Script entry<br/>[run.py]"]
  node_report["Report output<br/>[main.py]"]
  node_mailer["Email delivery<br/>[send.py]"]
end

subgraph group_orchestration["Analysis workflow"]
  node_graph["Trading graph<br/>[trading_graph.py]"]
  node_setup["Graph setup<br/>[setup.py]"]
  node_state["Agent state<br/>[agent_states.py]"]
end

subgraph group_agents["Research and decisions"]
  node_analysts["Analyst team"]
  node_market["Market analyst<br/>[market_analyst.py]"]
  node_social["Social analyst"]
  node_news["News analyst<br/>[news_analyst.py]"]
  node_fundamentals["Fundamentals analyst"]
  node_research["Research debate"]
  node_bull["Bull researcher<br/>[bull_researcher.py]"]
  node_bear["Bear researcher<br/>[bear_researcher.py]"]
  node_research_manager["Research manager"]
  node_risk["Risk debate"]
  node_risk_manager["Risk manager<br/>[risk_manager.py]"]
  node_trader["Trader decision<br/>[trader.py]"]
end

subgraph group_data["Market data"]
  node_toolkit["Data tools<br/>[agent_utils.py]"]
  node_interface["Data interface<br/>[interface.py]"]
  node_providers["Crypto data sources"]
end

subgraph group_memory["Learning context"]
  node_memory[("Situation memory<br/>[memory.py]")]
end

node_user(("User"))
node_llm{{"LLM service"}}
node_chromadb[("Chroma store")]
node_email_service{{"SMTP service"}}
node_scheduler(("OS scheduler"))

node_user -->|"provides inputs"| node_cli
node_user -->|"sets parameters"| node_script
node_cli -->|"runs analysis"| node_graph
node_script -->|"runs analysis"| node_graph
node_graph -->|"builds workflow"| node_setup
node_graph -->|"initializes state"| node_state
node_setup -->|"dispatches stages"| node_analysts
node_analysts -->|"includes"| node_market
node_analysts -->|"includes"| node_social
node_analysts -->|"includes"| node_news
node_analysts -->|"includes"| node_fundamentals
node_market -->|"requests data"| node_toolkit
node_social -->|"requests data"| node_toolkit
node_news -->|"requests data"| node_toolkit
node_fundamentals -->|"requests data"| node_toolkit
node_toolkit -->|"fetches data"| node_interface
node_interface -->|"retrieves from"| node_providers
node_providers -->|"returns data"| node_interface
node_setup -->|"dispatches debate"| node_research
node_research -->|"includes"| node_bull
node_research -->|"includes"| node_bear
node_research -->|"judges debate"| node_research_manager
node_setup -->|"dispatches debate"| node_risk
node_risk -->|"judges debate"| node_risk_manager
node_setup -->|"dispatches decision"| node_trader
node_research_manager -->|"invokes"| node_llm
node_risk_manager -->|"invokes"| node_llm
node_bull -->|"invokes"| node_llm
node_bear -->|"invokes"| node_llm
node_research_manager -->|"queries memories"| node_memory
node_risk_manager -->|"queries memories"| node_memory
node_bull -->|"queries memories"| node_memory
node_bear -->|"queries memories"| node_memory
node_memory -->|"queries and stores"| node_chromadb
node_graph -->|"creates memories"| node_memory
node_cli -->|"renders and logs"| node_report
node_trader -->|"supplies recommendation"| node_report
node_scheduler -.->|"starts delivery"| node_mailer
node_mailer -.->|"reads latest report"| node_report
node_mailer -.->|"sends email"| node_email_service

click node_cli "https://github.com/tomortec/cryptotradingagents/blob/main/cli/main.py"
click node_script "https://github.com/tomortec/cryptotradingagents/blob/main/cli/run.py"
click node_report "https://github.com/tomortec/cryptotradingagents/blob/main/cli/main.py"
click node_mailer "https://github.com/tomortec/cryptotradingagents/blob/main/mailsender/send.py"
click node_graph "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/graph/trading_graph.py"
click node_setup "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/graph/setup.py"
click node_state "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/agent_states.py"
click node_analysts "https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/analysts"
click node_market "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/market_analyst.py"
click node_social "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/social_media_analyst.py"
click node_news "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/news_analyst.py"
click node_fundamentals "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/fundamentals_analyst.py"
click node_research "https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/researchers"
click node_bull "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/researchers/bull_researcher.py"
click node_bear "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/researchers/bear_researcher.py"
click node_research_manager "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/managers/research_manager.py"
click node_risk "https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/risk_mgmt"
click node_risk_manager "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/managers/risk_manager.py"
click node_trader "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/trader/trader.py"
click node_toolkit "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/agent_utils.py"
click node_interface "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/dataflows/interface.py"
click node_providers "https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/dataflows"
click node_memory "https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/memory.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_script,node_report,node_mailer,node_user toneBlue
class node_graph,node_setup,node_state,node_chromadb toneAmber
class node_analysts,node_market,node_social,node_news,node_fundamentals,node_research,node_bull,node_bear,node_research_manager,node_risk,node_risk_manager,node_trader toneMint
class node_toolkit,node_interface,node_providers,node_scheduler toneRose
class node_memory,node_llm,node_email_service toneIndigo
```

## Components

### User entry and reports

- [CLI and reports](https://github.com/tomortec/cryptotradingagents/blob/main/cli/main.py): `cli/main.py`
- [Script entry](https://github.com/tomortec/cryptotradingagents/blob/main/cli/run.py): `cli/run.py`
- [Report output](https://github.com/tomortec/cryptotradingagents/blob/main/cli/main.py): `cli/main.py`
- [Email delivery](https://github.com/tomortec/cryptotradingagents/blob/main/mailsender/send.py): `mailsender/send.py`

### Analysis workflow

- [Trading graph](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/graph/trading_graph.py): `tradingagents/graph/trading_graph.py`
- [Graph setup](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/graph/setup.py): `tradingagents/graph/setup.py`
- [Agent state](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/agent_states.py): `tradingagents/agents/utils/agent_states.py`

### Research and decisions

- [Analyst team](https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/analysts): `tradingagents/agents/analysts`
- [Market analyst](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/market_analyst.py): `tradingagents/agents/analysts/market_analyst.py`
- [Social analyst](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/social_media_analyst.py): `tradingagents/agents/analysts/social_media_analyst.py`
- [News analyst](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/news_analyst.py): `tradingagents/agents/analysts/news_analyst.py`
- [Fundamentals analyst](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/analysts/fundamentals_analyst.py): `tradingagents/agents/analysts/fundamentals_analyst.py`
- [Research debate](https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/researchers): `tradingagents/agents/researchers`
- [Bull researcher](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/researchers/bull_researcher.py): `tradingagents/agents/researchers/bull_researcher.py`
- [Bear researcher](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/researchers/bear_researcher.py): `tradingagents/agents/researchers/bear_researcher.py`
- [Research manager](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/managers/research_manager.py): `tradingagents/agents/managers/research_manager.py`
- [Risk debate](https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/agents/risk_mgmt): `tradingagents/agents/risk_mgmt`
- [Risk manager](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/managers/risk_manager.py): `tradingagents/agents/managers/risk_manager.py`
- [Trader decision](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/trader/trader.py): `tradingagents/agents/trader/trader.py`

### Market data

- [Data tools](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/agent_utils.py): `tradingagents/agents/utils/agent_utils.py`
- [Data interface](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/dataflows/interface.py): `tradingagents/dataflows/interface.py`
- [Crypto data sources](https://github.com/tomortec/cryptotradingagents/tree/main/tradingagents/dataflows): `tradingagents/dataflows`

### Learning context

- [Situation memory](https://github.com/tomortec/cryptotradingagents/blob/main/tradingagents/agents/utils/memory.py): `tradingagents/agents/utils/memory.py`

### Other components

- **User**
- **LLM service**
- **Chroma store**
- **SMTP service**
- **OS scheduler**

## Connections

- User → CLI and reports: provides inputs
- User → Script entry: sets parameters
- CLI and reports → Trading graph: runs analysis
- Script entry → Trading graph: runs analysis
- Trading graph → Graph setup: builds workflow
- Trading graph → Agent state: initializes state
- Graph setup → Analyst team: dispatches stages
- Analyst team → Market analyst: includes
- Analyst team → Social analyst: includes
- Analyst team → News analyst: includes
- Analyst team → Fundamentals analyst: includes
- Market analyst → Data tools: requests data
- Social analyst → Data tools: requests data
- News analyst → Data tools: requests data
- Fundamentals analyst → Data tools: requests data
- Data tools → Data interface: fetches data
- Data interface → Crypto data sources: retrieves from
- Crypto data sources → Data interface: returns data
- Graph setup → Research debate: dispatches debate
- Research debate → Bull researcher: includes
- Research debate → Bear researcher: includes
- Research debate → Research manager: judges debate
- Graph setup → Risk debate: dispatches debate
- Risk debate → Risk manager: judges debate
- Graph setup → Trader decision: dispatches decision
- Research manager → LLM service: invokes
- Risk manager → LLM service: invokes
- Bull researcher → LLM service: invokes
- Bear researcher → LLM service: invokes
- Research manager → Situation memory: queries memories
- Risk manager → Situation memory: queries memories
- Bull researcher → Situation memory: queries memories
- Bear researcher → Situation memory: queries memories
- Situation memory → Chroma store: queries and stores
- Trading graph → Situation memory: creates memories
- CLI and reports → Report output: renders and logs
- Trader decision → Report output: supplies recommendation
- OS scheduler → Email delivery: starts delivery
- Email delivery → Report output: reads latest report
- Email delivery → SMTP service: sends email