# meth04/tradingagent-vn architecture

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

- Interactive diagram: https://gitdiagram.com/meth04/tradingagent-vn
- Repository: https://github.com/meth04/tradingagent-vn

## Overview

TradingAgent-VN simulates an AI investment workspace for Vietnamese equities. Its central workflow collects market and news data, runs specialist analysis, synthesizes investment decisions, applies risk and governance, and presents research or backtest results. Separate capabilities include financial-report RAG, persistent memory and reporting, and several portfolio/backtest strategies. The README documents the product-level stages; source excerpts and the index support selected implementation links. Other runtime paths are included as documented subsystems without inferring unshown calls.

Main entry points: [`vnstock/workflows/base.py`](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/workflows/base.py) (Specialist agents), [`vnstock/tools/backtest/engine.py`](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/tools/backtest/engine.py) (Backtest engine), [`vnstock/agents/financial_agent.py`](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/financial_agent.py) (Financial analyst), [`cognitive_trading/decision/debate_engine.py`](https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/decision/debate_engine.py) (Decision debate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data collection"]
  node_market_crawler["Market crawler<br/>[crawler.py]"]
  node_news_pipeline["News ingestion<br/>[pipeline.py]"]
  node_news_sources["News sources"]
  node_market_db[("Market database<br/>[repo.py]")]
  node_news_db[("News database<br/>[articles_repo.py]")]
end

subgraph group_analysis["Investment analysis"]
  node_specialists["Specialist agents<br/>[base.py]"]
  node_financial_agent["Financial analyst<br/>[financial_agent.py]"]
  node_rag["Financial RAG"]
  node_llm["LLM client<br/>[llm.py]"]
  node_cio["CIO synthesis<br/>[strategist.py]"]
  node_prompt_schema["Decision schemas<br/>[prompting.py]"]
end

subgraph group_cognitive["Cognitive trading"]
  node_planner["Planner and context<br/>[context_packer.py]"]
  node_swarm["Analyst swarm<br/>[base_analyst.py]"]
  node_debate["Decision debate<br/>[debate_engine.py]"]
  node_governance["Governance<br/>[schemas.py]"]
  node_risk["Risk engine<br/>[risk_engine.py]"]
  node_memory[("Trading memory")]
  node_reports["Daily reporting<br/>[daily_reporter.py]"]
end

subgraph group_portfolio["Workflows and backtesting"]
  node_backtest["Backtest engine<br/>[engine.py]"]
  node_strategies["Portfolio strategies"]
end

subgraph group_interfaces["User interfaces"]
  node_realtime_api["Realtime API<br/>[main.py]"]
  node_realtime_ui["Realtime app<br/>[page.tsx]"]
  node_research_ui["Research dashboard"]
  node_news_ui["News dashboard"]
end

node_investor(("Investor"))

node_investor -->|"uses"| node_realtime_ui
node_realtime_ui -.->|"requests analysis"| node_realtime_api
node_realtime_api -->|"invokes analysis"| node_specialists
node_market_crawler -->|"stores prices"| node_market_db
node_news_sources -->|"provides articles"| node_news_pipeline
node_news_pipeline -->|"stores articles"| node_news_db
node_specialists -->|"runs financial analysis"| node_financial_agent
node_specialists -->|"requests completion"| node_llm
node_financial_agent -.->|"queries reports"| node_rag
node_financial_agent -->|"requests completion"| node_llm
node_cio -->|"uses actions"| node_prompt_schema
node_planner -.->|"prepares context"| node_swarm
node_swarm -.->|"feeds debate"| node_debate
node_debate -->|"requests completion"| node_llm
node_debate -->|"validates decisions"| node_governance
node_governance -.->|"constrains decisions"| node_risk
node_planner -->|"uses context"| node_memory
node_memory -.->|"supports reflection"| node_reports
node_specialists -->|"evaluated by"| node_backtest
node_backtest -->|"runs workflows"| node_strategies
node_backtest -->|"loads market data"| node_market_db
node_investor -->|"reviews results"| node_research_ui
node_research_ui -.->|"presents backtests"| node_backtest
node_investor -->|"reviews news"| node_news_ui

click node_market_crawler "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/jobs/crawler.py"
click node_news_pipeline "https://github.com/meth04/tradingagent-vn/blob/main/tracking_news/app/ingest/pipeline.py"
click node_news_sources "https://github.com/meth04/tradingagent-vn/tree/main/tracking_news/app/sources"
click node_market_db "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/database/repo.py"
click node_news_db "https://github.com/meth04/tradingagent-vn/blob/main/tracking_news/app/db/articles_repo.py"
click node_specialists "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/workflows/base.py"
click node_financial_agent "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/financial_agent.py"
click node_rag "https://github.com/meth04/tradingagent-vn/tree/main/vnstock/libs/rag_engine"
click node_llm "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/core/llm.py"
click node_cio "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/strategist.py"
click node_prompt_schema "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/prompting.py"
click node_planner "https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/planner/context_packer.py"
click node_swarm "https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/swarm/base_analyst.py"
click node_debate "https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/decision/debate_engine.py"
click node_governance "https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/governance/schemas.py"
click node_risk "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/engine/risk_engine.py"
click node_memory "https://github.com/meth04/tradingagent-vn/tree/main/cognitive_trading/memory"
click node_reports "https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/reporting/daily_reporter.py"
click node_backtest "https://github.com/meth04/tradingagent-vn/blob/main/vnstock/tools/backtest/engine.py"
click node_strategies "https://github.com/meth04/tradingagent-vn/tree/main/vnstock/workflows"
click node_realtime_api "https://github.com/meth04/tradingagent-vn/blob/main/app/backend/main.py"
click node_realtime_ui "https://github.com/meth04/tradingagent-vn/blob/main/app/frontend/src/app/page.tsx"
click node_research_ui "https://github.com/meth04/tradingagent-vn/tree/main/dashboard/src/app"
click node_news_ui "https://github.com/meth04/tradingagent-vn/blob/main/tracking_news/apps/dashboard_streamlit.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_market_crawler,node_news_pipeline,node_news_sources,node_market_db,node_news_db toneBlue
class node_specialists,node_financial_agent,node_rag,node_llm,node_cio,node_prompt_schema toneAmber
class node_planner,node_swarm,node_debate,node_governance,node_risk,node_memory,node_reports toneMint
class node_backtest,node_strategies toneRose
class node_realtime_api,node_realtime_ui,node_research_ui,node_news_ui,node_investor toneIndigo
```

## Components

### Data collection

- [Market crawler](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/jobs/crawler.py): `vnstock/jobs/crawler.py`
- [News ingestion](https://github.com/meth04/tradingagent-vn/blob/main/tracking_news/app/ingest/pipeline.py): `tracking_news/app/ingest/pipeline.py`
- [News sources](https://github.com/meth04/tradingagent-vn/tree/main/tracking_news/app/sources): `tracking_news/app/sources`
- [Market database](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/database/repo.py): `vnstock/database/repo.py`
- [News database](https://github.com/meth04/tradingagent-vn/blob/main/tracking_news/app/db/articles_repo.py): `tracking_news/app/db/articles_repo.py`

### Investment analysis

- [Specialist agents](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/workflows/base.py): `vnstock/workflows/base.py`
- [Financial analyst](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/financial_agent.py): `vnstock/agents/financial_agent.py`
- [Financial RAG](https://github.com/meth04/tradingagent-vn/tree/main/vnstock/libs/rag_engine): `vnstock/libs/rag_engine`
- [LLM client](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/core/llm.py): `vnstock/core/llm.py`
- [CIO synthesis](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/strategist.py): `vnstock/agents/strategist.py`
- [Decision schemas](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/agents/prompting.py): `vnstock/agents/prompting.py`

### Cognitive trading

- [Planner and context](https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/planner/context_packer.py): `cognitive_trading/planner/context_packer.py`
- [Analyst swarm](https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/swarm/base_analyst.py): `cognitive_trading/swarm/base_analyst.py`
- [Decision debate](https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/decision/debate_engine.py): `cognitive_trading/decision/debate_engine.py`
- [Governance](https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/governance/schemas.py): `cognitive_trading/governance/schemas.py`
- [Risk engine](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/engine/risk_engine.py): `vnstock/engine/risk_engine.py`
- [Trading memory](https://github.com/meth04/tradingagent-vn/tree/main/cognitive_trading/memory): `cognitive_trading/memory`
- [Daily reporting](https://github.com/meth04/tradingagent-vn/blob/main/cognitive_trading/reporting/daily_reporter.py): `cognitive_trading/reporting/daily_reporter.py`

### Workflows and backtesting

- [Backtest engine](https://github.com/meth04/tradingagent-vn/blob/main/vnstock/tools/backtest/engine.py): `vnstock/tools/backtest/engine.py`
- [Portfolio strategies](https://github.com/meth04/tradingagent-vn/tree/main/vnstock/workflows): `vnstock/workflows`

### User interfaces

- [Realtime API](https://github.com/meth04/tradingagent-vn/blob/main/app/backend/main.py): `app/backend/main.py`
- [Realtime app](https://github.com/meth04/tradingagent-vn/blob/main/app/frontend/src/app/page.tsx): `app/frontend/src/app/page.tsx`
- [Research dashboard](https://github.com/meth04/tradingagent-vn/tree/main/dashboard/src/app): `dashboard/src/app`
- [News dashboard](https://github.com/meth04/tradingagent-vn/blob/main/tracking_news/apps/dashboard_streamlit.py): `tracking_news/apps/dashboard_streamlit.py`

### Other components

- **Investor**

## Connections

- Investor → Realtime app: uses (evidence: `README.md`)
- Realtime app → Realtime API: requests analysis
- Realtime API → Specialist agents: invokes analysis
- Market crawler → Market database: stores prices (evidence: `README.md`)
- News sources → News ingestion: provides articles (evidence: `tracking_news/app/ingest/pipeline.py`)
- News ingestion → News database: stores articles (evidence: `tracking_news/app/ingest/pipeline.py`)
- Specialist agents → Financial analyst: runs financial analysis (evidence: `vnstock/workflows/base.py`)
- Specialist agents → LLM client: requests completion (evidence: `vnstock/workflows/base.py`)
- Financial analyst → Financial RAG: queries reports
- Financial analyst → LLM client: requests completion (evidence: `vnstock/agents/financial_agent.py`)
- CIO synthesis → Decision schemas: uses actions
- Planner and context → Analyst swarm: prepares context
- Analyst swarm → Decision debate: feeds debate (evidence: `README.md`)
- Decision debate → LLM client: requests completion (evidence: `cognitive_trading/decision/debate_engine.py`)
- Decision debate → Governance: validates decisions (evidence: `cognitive_trading/decision/debate_engine.py`)
- Governance → Risk engine: constrains decisions (evidence: `README.md`)
- Planner and context → Trading memory: uses context (evidence: `cognitive_trading/planner/context_packer.py`)
- Trading memory → Daily reporting: supports reflection (evidence: `README.md`)
- Specialist agents → Backtest engine: evaluated by (evidence: `README.md`)
- Backtest engine → Portfolio strategies: runs workflows (evidence: `vnstock/tools/backtest/engine.py`)
- Backtest engine → Market database: loads market data (evidence: `vnstock/tools/backtest/engine.py`)
- Investor → Research dashboard: reviews results (evidence: `README.md`)
- Research dashboard → Backtest engine: presents backtests (evidence: `README.md`)
- Investor → News dashboard: reviews news (evidence: `README.md`)