# tnt-likely/panwatch architecture

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

- Interactive diagram: https://gitdiagram.com/tnt-likely/panwatch
- Repository: https://github.com/tnt-likely/panwatch

## Overview

PanWatch is a self-hosted, multi-market stock-monitoring and AI research application. Users manage watchlists and portfolio accounts, inspect market data and strategy-ranked opportunities, then run deep multi-agent analysis or use scheduled agents; results can feed alerts and multi-channel notifications. The frontend talks to a FastAPI application assembled from domain routers, with shared market-data, AI, persistence, scheduling, and notification services. The README documents the major product capabilities; some backend wiring is unsampled, so the graph shows only supported orchestration and documented flows.

Main entry points: [`packages/marketdata/src/marketdata/engine.py`](https://github.com/tnt-likely/panwatch/blob/main/packages/marketdata/src/marketdata/engine.py) (Market-data engine), [`src/bootstrap/application.py`](https://github.com/tnt-likely/panwatch/blob/main/src/bootstrap/application.py) (FastAPI app), [`src/modules/strategy/strategy_engine.py`](https://github.com/tnt-likely/panwatch/blob/main/src/modules/strategy/strategy_engine.py) (Signal strategies), [`src/modules/market/price_alert_engine.py`](https://github.com/tnt-likely/panwatch/blob/main/src/modules/market/price_alert_engine.py) (Price alert engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["PanWatch UI<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_assistant_ui["Assistant interface<br/>[Assistant.tsx]"]
end

subgraph group_research["Research and strategy"]
  node_assistant["Assistant service<br/>[service.py]"]
  node_assistant_tasks["Assistant task runner<br/>[task_runner.py]"]
  node_tradingagents["TradingAgents analysis<br/>[agent.py]"]
  node_strategy["Signal strategies<br/>[strategy_engine.py]"]
  node_backtest["Strategy backtest<br/>[engine.py]"]
end

subgraph group_operations["Monitoring and trading"]
  node_automation["Scheduled agents"]
  node_market_api["Market endpoints"]
  node_market_service["Market monitoring"]
  node_portfolio["Portfolio management"]
  node_paper["Paper trading"]
  node_alerts["Price alert engine"]
end

subgraph group_platform["Shared platform"]
  node_backend["FastAPI app<br/>[application.py]"]
  node_marketdata["Market-data engine<br/>[engine.py]"]
  node_notifications["Notifications<br/>[notifier.py]"]
  node_ai["AI provider client<br/>[ai_client.py]"]
  node_database[("Application database<br/>[database.py]")]
end

node_user(("Investor"))
node_external_market(("Market-data vendors"))
node_external_ai(("OpenAI-compatible model"))
node_external_channels(("Messaging channels"))

node_user -->|"uses"| node_web
node_web -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"mounts routes"| node_market_api
node_backend -->|"mounts routes"| node_assistant
node_backend -->|"mounts routes"| node_portfolio
node_backend -->|"mounts routes"| node_alerts
node_assistant_ui -->|"starts analysis"| node_assistant
node_assistant -->|"runs task"| node_assistant_tasks
node_assistant_tasks -->|"requests model"| node_ai
node_ai -->|"sends prompts"| node_external_ai
node_assistant_tasks -->|"stores task state"| node_database
node_user -->|"manages accounts"| node_portfolio
node_portfolio -->|"reads and writes"| node_database
node_tradingagents -.->|"uses model"| node_ai
node_automation -.->|"runs analysis"| node_tradingagents
node_automation -->|"delivers reports"| node_notifications
node_market_api -->|"requests quotes"| node_marketdata
node_marketdata -->|"fetches data"| node_external_market
node_market_service -->|"reads market data"| node_marketdata
node_market_service -->|"evaluates rules"| node_alerts
node_alerts -->|"loads quotes and klines"| node_marketdata
node_alerts -->|"sends alerts"| node_notifications
node_notifications -->|"delivers messages"| node_external_channels
node_strategy -->|"stores signals"| node_database
node_strategy -->|"uses market inputs"| node_marketdata
node_backtest -->|"evaluates signals"| node_strategy
node_paper -->|"reads and writes trades"| node_database
node_paper -->|"loads quotes"| node_marketdata
node_paper -->|"uses strategy signals"| node_strategy

click node_web "https://github.com/tnt-likely/panwatch/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/tnt-likely/panwatch/blob/main/frontend/packages/api/src/client.ts"
click node_backend "https://github.com/tnt-likely/panwatch/blob/main/src/bootstrap/application.py"
click node_assistant_ui "https://github.com/tnt-likely/panwatch/blob/main/frontend/src/pages/Assistant.tsx"
click node_assistant "https://github.com/tnt-likely/panwatch/blob/main/src/modules/assistant/service.py"
click node_assistant_tasks "https://github.com/tnt-likely/panwatch/blob/main/src/modules/assistant/task_runner.py"
click node_tradingagents "https://github.com/tnt-likely/panwatch/blob/main/src/modules/automation/tradingagents/agent.py"
click node_automation "https://github.com/tnt-likely/panwatch/tree/main/src/modules/automation"
click node_strategy "https://github.com/tnt-likely/panwatch/blob/main/src/modules/strategy/strategy_engine.py"
click node_backtest "https://github.com/tnt-likely/panwatch/blob/main/src/modules/strategy/backtest/engine.py"
click node_market_api "https://github.com/tnt-likely/panwatch/tree/main/src/modules/market/api"
click node_market_service "https://github.com/tnt-likely/panwatch/tree/main/src/modules/market"
click node_marketdata "https://github.com/tnt-likely/panwatch/blob/main/packages/marketdata/src/marketdata/engine.py"
click node_portfolio "https://github.com/tnt-likely/panwatch/tree/main/src/modules/portfolio"
click node_paper "https://github.com/tnt-likely/panwatch/blob/main/src/modules/paper_trading/paper_trading_engine.py"
click node_alerts "https://github.com/tnt-likely/panwatch/blob/main/src/modules/market/price_alert_engine.py"
click node_notifications "https://github.com/tnt-likely/panwatch/blob/main/src/platform/notifications/notifier.py"
click node_ai "https://github.com/tnt-likely/panwatch/blob/main/src/platform/ai/ai_client.py"
click node_database "https://github.com/tnt-likely/panwatch/blob/main/src/platform/persistence/database.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_web,node_api_client,node_assistant_ui toneBlue
class node_assistant,node_assistant_tasks,node_tradingagents,node_strategy,node_backtest toneAmber
class node_automation,node_market_api,node_market_service,node_portfolio,node_paper,node_alerts toneMint
class node_backend,node_marketdata,node_notifications,node_ai,node_database toneRose
class node_user,node_external_market,node_external_ai,node_external_channels toneIndigo
```

## Components

### Web experience

- [PanWatch UI](https://github.com/tnt-likely/panwatch/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/tnt-likely/panwatch/blob/main/frontend/packages/api/src/client.ts): `frontend/packages/api/src/client.ts`
- [Assistant interface](https://github.com/tnt-likely/panwatch/blob/main/frontend/src/pages/Assistant.tsx): `frontend/src/pages/Assistant.tsx`

### Research and strategy

- [Assistant service](https://github.com/tnt-likely/panwatch/blob/main/src/modules/assistant/service.py): `src/modules/assistant/service.py`
- [Assistant task runner](https://github.com/tnt-likely/panwatch/blob/main/src/modules/assistant/task_runner.py): `src/modules/assistant/task_runner.py`
- [TradingAgents analysis](https://github.com/tnt-likely/panwatch/blob/main/src/modules/automation/tradingagents/agent.py): `src/modules/automation/tradingagents/agent.py`
- [Signal strategies](https://github.com/tnt-likely/panwatch/blob/main/src/modules/strategy/strategy_engine.py): `src/modules/strategy/strategy_engine.py`
- [Strategy backtest](https://github.com/tnt-likely/panwatch/blob/main/src/modules/strategy/backtest/engine.py): `src/modules/strategy/backtest/engine.py`

### Monitoring and trading

- [Scheduled agents](https://github.com/tnt-likely/panwatch/tree/main/src/modules/automation): `src/modules/automation`
- [Market endpoints](https://github.com/tnt-likely/panwatch/tree/main/src/modules/market/api): `src/modules/market/api`
- [Market monitoring](https://github.com/tnt-likely/panwatch/tree/main/src/modules/market): `src/modules/market`
- [Portfolio management](https://github.com/tnt-likely/panwatch/tree/main/src/modules/portfolio): `src/modules/portfolio`
- [Paper trading](https://github.com/tnt-likely/panwatch/blob/main/src/modules/paper_trading/paper_trading_engine.py): `src/modules/paper_trading/paper_trading_engine.py`
- [Price alert engine](https://github.com/tnt-likely/panwatch/blob/main/src/modules/market/price_alert_engine.py): `src/modules/market/price_alert_engine.py`

### Shared platform

- [FastAPI app](https://github.com/tnt-likely/panwatch/blob/main/src/bootstrap/application.py): `src/bootstrap/application.py`
- [Market-data engine](https://github.com/tnt-likely/panwatch/blob/main/packages/marketdata/src/marketdata/engine.py): `packages/marketdata/src/marketdata/engine.py`
- [Notifications](https://github.com/tnt-likely/panwatch/blob/main/src/platform/notifications/notifier.py): `src/platform/notifications/notifier.py`
- [AI provider client](https://github.com/tnt-likely/panwatch/blob/main/src/platform/ai/ai_client.py): `src/platform/ai/ai_client.py`
- [Application database](https://github.com/tnt-likely/panwatch/blob/main/src/platform/persistence/database.py): `src/platform/persistence/database.py`

### Other components

- **Investor**
- **Market-data vendors**
- **OpenAI-compatible model**
- **Messaging channels**

## Connections

- Investor → PanWatch UI: uses
- PanWatch UI → API client: requests data
- API client → FastAPI app: calls API
- FastAPI app → Market endpoints: mounts routes
- FastAPI app → Assistant service: mounts routes
- FastAPI app → Portfolio management: mounts routes
- FastAPI app → Price alert engine: mounts routes
- Assistant interface → Assistant service: starts analysis
- Assistant service → Assistant task runner: runs task
- Assistant task runner → AI provider client: requests model
- AI provider client → OpenAI-compatible model: sends prompts
- Assistant task runner → Application database: stores task state
- Investor → Portfolio management: manages accounts
- Portfolio management → Application database: reads and writes
- TradingAgents analysis → AI provider client: uses model
- Scheduled agents → TradingAgents analysis: runs analysis
- Scheduled agents → Notifications: delivers reports
- Market endpoints → Market-data engine: requests quotes
- Market-data engine → Market-data vendors: fetches data
- Market monitoring → Market-data engine: reads market data
- Market monitoring → Price alert engine: evaluates rules
- Price alert engine → Market-data engine: loads quotes and klines
- Price alert engine → Notifications: sends alerts
- Notifications → Messaging channels: delivers messages
- Signal strategies → Application database: stores signals
- Signal strategies → Market-data engine: uses market inputs
- Strategy backtest → Signal strategies: evaluates signals
- Paper trading → Application database: reads and writes trades
- Paper trading → Market-data engine: loads quotes
- Paper trading → Signal strategies: uses strategy signals