# teddykwok/trading-alert-dashboard architecture

> Architecture diagram of the GitHub repository teddykwok/trading-alert-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teddykwok/trading-alert-dashboard
- Repository: https://github.com/teddykwok/trading-alert-dashboard

## Overview

Trading Alert Dashboard is a single-operator system for ingesting TradingView alerts, enriching them with chart and AI analysis, and monitoring results live. Its principal workflow is webhook validation and persistence, queued worker processing, then browser updates and optional Telegram notification. The repository also includes a distinct execution and operator-control surface, including safety/capacity checks and trading-session controls, plus alert review and risk planning. Workflow links are grounded in the README; source excerpts provide only partial evidence for execution internals, so those links are limited to visible calls and imports.

Main entry points: [`apps/backend/src/modules/jobs/vision-analysis.worker.ts`](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/jobs/vision-analysis.worker.ts) (Vision worker), [`apps/backend/src/routes/webhook.routes.ts`](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/routes/webhook.routes.ts) (Webhook endpoint), [`apps/frontend/src/App.tsx`](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/frontend/src/App.tsx) (Dashboard app), [`apps/backend/src/modules/operator/trading-control-actions.service.ts`](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/operator/trading-control-actions.service.ts) (Trading control actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Alert ingestion"]
  node_webhook["Webhook endpoint<br/>[webhook.routes.ts]"]
  node_alert_validation["Payload validation<br/>[webhook.schema.ts]"]
  node_alerts["Alert service<br/>[alerts.service.ts]"]
end

subgraph group_analysis["Alert analysis"]
  node_vision_worker["Vision worker"]
  node_market_data["Market data"]
  node_binance_market["Binance provider"]
  node_mock_market["Mock candles<br/>[mock-candles.ts]"]
  node_chart["Chart rendering"]
  node_screenshot["Screenshot capture"]
  node_ai_vision["AI vision analysis"]
  node_openai["OpenAI provider<br/>[openai.provider.ts]"]
end

subgraph group_dashboard["Dashboard and review"]
  node_socket["Realtime events<br/>[socket.ts]"]
  node_telegram["Telegram notifications"]
  node_frontend["Dashboard app<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_trade_review["Trade review service"]
  node_review_repo["Review repository"]
end

subgraph group_execution["Execution controls"]
  node_operator_routes["Operator routes<br/>[operator.routes.ts]"]
  node_control_actions["Trading control actions"]
  node_safety_engine["Safety decisions<br/>[safety-engine.ts]"]
  node_canary_readiness["Canary readiness"]
  node_trading_session["Trading session<br/>[trading-session.ts]"]
  node_execution_status["Execution capacity status<br/>[capacity-status.ts]"]
end

node_tradingview(("TradingView"))
node_postgres[("PostgreSQL")]
node_redis_queue["Redis / BullMQ"]
node_browser(("Operator browser"))

node_tradingview -->|"sends alert"| node_webhook
node_webhook -->|"validates payload"| node_alert_validation
node_webhook -->|"persists alert"| node_alerts
node_webhook -->|"broadcasts event"| node_socket
node_webhook -->|"enqueues job"| node_redis_queue
node_alerts -->|"writes alert"| node_postgres
node_redis_queue -->|"dispatches job"| node_vision_worker
node_vision_worker -->|"requests candles"| node_market_data
node_market_data -->|"uses provider"| node_binance_market
node_market_data -->|"uses fallback"| node_mock_market
node_vision_worker -->|"renders chart"| node_chart
node_chart -->|"captures image"| node_screenshot
node_vision_worker -->|"analyzes screenshot"| node_ai_vision
node_ai_vision -.->|"uses provider"| node_openai
node_vision_worker -->|"saves result"| node_postgres
node_vision_worker -->|"broadcasts update"| node_socket
node_vision_worker -.->|"optionally notifies"| node_telegram
node_browser -->|"views dashboard"| node_frontend
node_frontend -.->|"requests data"| node_api_client
node_api_client -.->|"calls backend"| node_webhook
node_socket -->|"pushes updates"| node_frontend
node_frontend -->|"submits reviews"| node_trade_review
node_trade_review -->|"delegates reads"| node_review_repo
node_review_repo -->|"reads and writes"| node_postgres
node_frontend -.->|"uses control API"| node_operator_routes
node_operator_routes -->|"delegates actions"| node_control_actions
node_control_actions -->|"checks readiness"| node_canary_readiness
node_control_actions -->|"validates session"| node_trading_session
node_control_actions -->|"reads capacity"| node_execution_status
node_safety_engine -->|"uses capacity key"| node_execution_status

click node_webhook "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/routes/webhook.routes.ts"
click node_alert_validation "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/webhook/webhook.schema.ts"
click node_alerts "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/alerts/alerts.service.ts"
click node_vision_worker "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/jobs/vision-analysis.worker.ts"
click node_market_data "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/market-data/market-data.service.ts"
click node_binance_market "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/market-data/binance.provider.ts"
click node_mock_market "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/market-data/mock-candles.ts"
click node_chart "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/chart-renderer/chart-renderer.service.ts"
click node_screenshot "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/chart-renderer/screenshot.service.ts"
click node_ai_vision "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/ai-vision/ai-vision.service.ts"
click node_openai "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/ai-vision/openai.provider.ts"
click node_socket "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/plugins/socket.ts"
click node_telegram "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/notifications/telegram.service.ts"
click node_frontend "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/frontend/src/App.tsx"
click node_api_client "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/frontend/src/api/client.ts"
click node_trade_review "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/trade-review/trade-review.service.ts"
click node_review_repo "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/trade-review/trade-review.repository.ts"
click node_operator_routes "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/routes/operator.routes.ts"
click node_control_actions "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/operator/trading-control-actions.service.ts"
click node_safety_engine "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/safety-engine.ts"
click node_canary_readiness "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/canary-readiness.ts"
click node_trading_session "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/trading-session.ts"
click node_execution_status "https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/capacity-status.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_webhook,node_alert_validation,node_alerts,node_tradingview,node_browser toneBlue
class node_vision_worker,node_market_data,node_binance_market,node_mock_market,node_chart,node_screenshot,node_ai_vision,node_openai,node_postgres,node_redis_queue toneAmber
class node_socket,node_telegram,node_frontend,node_api_client,node_trade_review,node_review_repo toneMint
class node_operator_routes,node_control_actions,node_safety_engine,node_canary_readiness,node_trading_session,node_execution_status toneRose
```

## Components

### Alert ingestion

- [Webhook endpoint](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/routes/webhook.routes.ts): `apps/backend/src/routes/webhook.routes.ts`
- [Payload validation](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/webhook/webhook.schema.ts): `apps/backend/src/modules/webhook/webhook.schema.ts`
- [Alert service](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/alerts/alerts.service.ts): `apps/backend/src/modules/alerts/alerts.service.ts`

### Alert analysis

- [Vision worker](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/jobs/vision-analysis.worker.ts): `apps/backend/src/modules/jobs/vision-analysis.worker.ts`
- [Market data](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/market-data/market-data.service.ts): `apps/backend/src/modules/market-data/market-data.service.ts`
- [Binance provider](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/market-data/binance.provider.ts): `apps/backend/src/modules/market-data/binance.provider.ts`
- [Mock candles](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/market-data/mock-candles.ts): `apps/backend/src/modules/market-data/mock-candles.ts`
- [Chart rendering](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/chart-renderer/chart-renderer.service.ts): `apps/backend/src/modules/chart-renderer/chart-renderer.service.ts`
- [Screenshot capture](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/chart-renderer/screenshot.service.ts): `apps/backend/src/modules/chart-renderer/screenshot.service.ts`
- [AI vision analysis](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/ai-vision/ai-vision.service.ts): `apps/backend/src/modules/ai-vision/ai-vision.service.ts`
- [OpenAI provider](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/ai-vision/openai.provider.ts): `apps/backend/src/modules/ai-vision/openai.provider.ts`

### Dashboard and review

- [Realtime events](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/plugins/socket.ts): `apps/backend/src/plugins/socket.ts`
- [Telegram notifications](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/notifications/telegram.service.ts): `apps/backend/src/modules/notifications/telegram.service.ts`
- [Dashboard app](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/frontend/src/App.tsx): `apps/frontend/src/App.tsx`
- [API client](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/frontend/src/api/client.ts): `apps/frontend/src/api/client.ts`
- [Trade review service](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/trade-review/trade-review.service.ts): `apps/backend/src/modules/trade-review/trade-review.service.ts`
- [Review repository](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/trade-review/trade-review.repository.ts): `apps/backend/src/modules/trade-review/trade-review.repository.ts`

### Execution controls

- [Operator routes](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/routes/operator.routes.ts): `apps/backend/src/routes/operator.routes.ts`
- [Trading control actions](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/operator/trading-control-actions.service.ts): `apps/backend/src/modules/operator/trading-control-actions.service.ts`
- [Safety decisions](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/safety-engine.ts): `apps/backend/src/modules/execution/safety-engine.ts`
- [Canary readiness](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/canary-readiness.ts): `apps/backend/src/modules/execution/canary-readiness.ts`
- [Trading session](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/trading-session.ts): `apps/backend/src/modules/execution/trading-session.ts`
- [Execution capacity status](https://github.com/teddykwok/trading-alert-dashboard/blob/main/apps/backend/src/modules/execution/capacity-status.ts): `apps/backend/src/modules/execution/capacity-status.ts`

### Other components

- **TradingView**
- **PostgreSQL**
- **Redis / BullMQ**
- **Operator browser**

## Connections

- TradingView → Webhook endpoint: sends alert (evidence: `README.md`)
- Webhook endpoint → Payload validation: validates payload (evidence: `README.md`)
- Webhook endpoint → Alert service: persists alert (evidence: `README.md`)
- Webhook endpoint → Realtime events: broadcasts event (evidence: `README.md`)
- Webhook endpoint → Redis / BullMQ: enqueues job (evidence: `README.md`)
- Alert service → PostgreSQL: writes alert (evidence: `README.md`)
- Redis / BullMQ → Vision worker: dispatches job (evidence: `README.md`)
- Vision worker → Market data: requests candles (evidence: `README.md`)
- Market data → Binance provider: uses provider (evidence: `README.md`)
- Market data → Mock candles: uses fallback (evidence: `README.md`)
- Vision worker → Chart rendering: renders chart (evidence: `README.md`)
- Chart rendering → Screenshot capture: captures image (evidence: `README.md`)
- Vision worker → AI vision analysis: analyzes screenshot (evidence: `README.md`)
- AI vision analysis → OpenAI provider: uses provider (evidence: `README.md`)
- Vision worker → PostgreSQL: saves result (evidence: `README.md`)
- Vision worker → Realtime events: broadcasts update (evidence: `README.md`)
- Vision worker → Telegram notifications: optionally notifies (evidence: `README.md`)
- Operator browser → Dashboard app: views dashboard (evidence: `README.md`)
- Dashboard app → API client: requests data (evidence: `apps/frontend/src/App.tsx`)
- API client → Webhook endpoint: calls backend
- Realtime events → Dashboard app: pushes updates (evidence: `README.md`)
- Dashboard app → Trade review service: submits reviews (evidence: `README.md`)
- Trade review service → Review repository: delegates reads (evidence: `apps/backend/src/modules/trade-review/trade-review.service.ts`)
- Review repository → PostgreSQL: reads and writes (evidence: `apps/backend/src/modules/trade-review/trade-review.repository.ts`)
- Dashboard app → Operator routes: uses control API
- Operator routes → Trading control actions: delegates actions (evidence: `apps/backend/src/routes/operator.routes.ts`)
- Trading control actions → Canary readiness: checks readiness (evidence: `apps/backend/src/modules/operator/trading-control-actions.service.ts`)
- Trading control actions → Trading session: validates session (evidence: `apps/backend/src/modules/operator/trading-control-actions.service.ts`)
- Trading control actions → Execution capacity status: reads capacity (evidence: `apps/backend/src/modules/operator/trading-control-actions.service.ts`)
- Safety decisions → Execution capacity status: uses capacity key (evidence: `apps/backend/src/modules/execution/safety-engine.ts`)