# daniel9572/tracefang architecture

> Architecture diagram of the GitHub repository daniel9572/tracefang, 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/daniel9572/tracefang
- Repository: https://github.com/daniel9572/tracefang

## Overview

TraceFang is a multi-market trading analysis platform. A user selects a watched instrument and its single bound real-time source; the backend collects quotes and same-source candles, serves local history and live updates, and the web workspace renders the chart and expert-analysis tools. The README also describes watchlists, source management, gold-event analysis, historical-data admission, and persistence. The graph emphasizes documented runtime responsibilities; some subsystem wiring is inferred only at the directory level because its implementation was not sampled.

Main entry points: [`src/tracefang/api.py`](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/api.py) (HTTP and streams), [`web/src/App.tsx`](https://github.com/daniel9572/tracefang/blob/main/web/src/App.tsx) (Market workspace), [`src/tracefang/application/services.py`](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/services.py) (Market data services), [`src/tracefang/application/acquisition.py`](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/acquisition.py) (Acquisition runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Market workspace"]
  node_webapp["Market workspace<br/>[App.tsx]"]
  node_chart["Chart rendering<br/>[MarketChart.tsx]"]
end

subgraph group_runtime["Market data runtime"]
  node_api["HTTP and streams<br/>[api.py]"]
  node_acquisition["Acquisition runtime<br/>[acquisition.py]"]
  node_routing["Market data services<br/>[services.py]"]
  node_realtime["Realtime bars<br/>[realtime_bars.py]"]
  node_history["History retrieval<br/>[history.py]"]
  node_writer["Async persistence<br/>[persistence.py]"]
  node_watchlists["Watchlists and instruments<br/>[instruments.py]"]
  node_sourceconfig["Source routing<br/>[source_config.py]"]
end

subgraph group_providers["Provider adapters"]
  node_providerjin["Jin10 channels<br/>[provider.py]"]
  node_providertong["Tonghuashun<br/>[provider.py]"]
  node_providerweb["Jin10 web<br/>[provider.py]"]
end

subgraph group_state["Persistence and history"]
  node_postgres[("Market data store<br/>[store.py]")]
  node_frames[("Raw frame archive<br/>[store.py]")]
  node_historymgmt["History admission<br/>[admission.py]"]
  node_histpostgres[("Research history store<br/>[postgres.py]")]
end

subgraph group_analysis["Trading analysis"]
  node_expert["Expert analysis"]
  node_expertfeatures["Analysis features<br/>[expertAnalysis.ts]"]
  node_gold["Gold events<br/>[gold_events.py]"]
end

node_user(("Trader"))
node_external(("Market data providers"))
node_browser(("Browser"))
node_pgservice[("PostgreSQL")]
node_jetstream["NATS JetStream"]

node_user -->|"selects and views"| node_webapp
node_webapp -->|"requests market data"| node_api
node_api -->|"returns REST and live events"| node_webapp
node_webapp -->|"renders prices"| node_chart
node_webapp -->|"opens analysis"| node_expert
node_expert -->|"uses indicators and replay"| node_expertfeatures
node_api -->|"reads and updates"| node_watchlists
node_api -->|"reads and updates routes"| node_sourceconfig
node_api -->|"requests quotes and candles"| node_routing
node_api -->|"serves live bars"| node_realtime
node_api -->|"requests missing history"| node_history
node_acquisition -->|"collects selected source"| node_routing
node_routing -->|"requests market data"| node_providerjin
node_routing -->|"requests market data"| node_providertong
node_providerjin -->|"receives market feed"| node_external
node_providertong -->|"requests market feed"| node_external
node_providerweb -.->|"receives web feed"| node_external
node_acquisition -->|"updates live bars"| node_realtime
node_realtime -->|"queues persistence"| node_writer
node_writer -->|"writes quotes and candles"| node_postgres
node_api -->|"reads cached data"| node_postgres
node_postgres -->|"stores market state"| node_pgservice
node_acquisition -->|"archives raw frames"| node_frames
node_frames -->|"persists and replays frames"| node_jetstream
node_historymgmt -->|"validates and admits datasets"| node_histpostgres
node_histpostgres -->|"stores trusted history"| node_pgservice
node_api -->|"serves event analysis"| node_gold
node_browser -->|"uses workspace"| node_webapp

click node_webapp "https://github.com/daniel9572/tracefang/blob/main/web/src/App.tsx"
click node_chart "https://github.com/daniel9572/tracefang/blob/main/web/src/MarketChart.tsx"
click node_expert "https://github.com/daniel9572/tracefang/blob/main/web/src/ExpertModeWorkspace.tsx"
click node_expertfeatures "https://github.com/daniel9572/tracefang/blob/main/web/src/expertAnalysis.ts"
click node_gold "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/gold_events.py"
click node_api "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/api.py"
click node_acquisition "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/acquisition.py"
click node_routing "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/services.py"
click node_realtime "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/realtime_bars.py"
click node_history "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/history.py"
click node_providerjin "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/providers/jin10_local/provider.py"
click node_providertong "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/providers/tonghuashun_futures/provider.py"
click node_providerweb "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/providers/jin10_web/provider.py"
click node_postgres "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/postgres/store.py"
click node_writer "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/persistence.py"
click node_watchlists "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/instruments.py"
click node_sourceconfig "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/source_config.py"
click node_frames "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/jetstream/store.py"
click node_historymgmt "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/history_management/admission.py"
click node_histpostgres "https://github.com/daniel9572/tracefang/blob/main/src/tracefang/history_management/postgres.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_webapp,node_chart,node_browser toneBlue
class node_api,node_acquisition,node_routing,node_realtime,node_history,node_writer,node_watchlists,node_sourceconfig,node_pgservice toneAmber
class node_providerjin,node_providertong,node_providerweb toneMint
class node_postgres,node_frames,node_historymgmt,node_histpostgres toneRose
class node_expert,node_expertfeatures,node_gold,node_user,node_external,node_jetstream toneIndigo
```

## Components

### Market workspace

- [Market workspace](https://github.com/daniel9572/tracefang/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Chart rendering](https://github.com/daniel9572/tracefang/blob/main/web/src/MarketChart.tsx): `web/src/MarketChart.tsx`

### Market data runtime

- [HTTP and streams](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/api.py): `src/tracefang/api.py`
- [Acquisition runtime](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/acquisition.py): `src/tracefang/application/acquisition.py`
- [Market data services](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/services.py): `src/tracefang/application/services.py`
- [Realtime bars](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/realtime_bars.py): `src/tracefang/application/realtime_bars.py`
- [History retrieval](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/history.py): `src/tracefang/application/history.py`
- [Async persistence](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/persistence.py): `src/tracefang/application/persistence.py`
- [Watchlists and instruments](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/instruments.py): `src/tracefang/instruments.py`
- [Source routing](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/source_config.py): `src/tracefang/infrastructure/source_config.py`

### Provider adapters

- [Jin10 channels](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/providers/jin10_local/provider.py): `src/tracefang/infrastructure/providers/jin10_local/provider.py`
- [Tonghuashun](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/providers/tonghuashun_futures/provider.py): `src/tracefang/infrastructure/providers/tonghuashun_futures/provider.py`
- [Jin10 web](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/providers/jin10_web/provider.py): `src/tracefang/infrastructure/providers/jin10_web/provider.py`

### Persistence and history

- [Market data store](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/postgres/store.py): `src/tracefang/infrastructure/postgres/store.py`
- [Raw frame archive](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/infrastructure/jetstream/store.py): `src/tracefang/infrastructure/jetstream/store.py`
- [History admission](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/history_management/admission.py): `src/tracefang/history_management/admission.py`
- [Research history store](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/history_management/postgres.py): `src/tracefang/history_management/postgres.py`

### Trading analysis

- [Expert analysis](https://github.com/daniel9572/tracefang/blob/main/web/src/ExpertModeWorkspace.tsx): `web/src/ExpertModeWorkspace.tsx`
- [Analysis features](https://github.com/daniel9572/tracefang/blob/main/web/src/expertAnalysis.ts): `web/src/expertAnalysis.ts`
- [Gold events](https://github.com/daniel9572/tracefang/blob/main/src/tracefang/application/gold_events.py): `src/tracefang/application/gold_events.py`

### Other components

- **Trader**
- **Market data providers**
- **Browser**
- **PostgreSQL**
- **NATS JetStream**

## Connections

- Trader → Market workspace: selects and views
- Market workspace → HTTP and streams: requests market data
- HTTP and streams → Market workspace: returns REST and live events
- Market workspace → Chart rendering: renders prices
- Market workspace → Expert analysis: opens analysis
- Expert analysis → Analysis features: uses indicators and replay
- HTTP and streams → Watchlists and instruments: reads and updates
- HTTP and streams → Source routing: reads and updates routes
- HTTP and streams → Market data services: requests quotes and candles
- HTTP and streams → Realtime bars: serves live bars
- HTTP and streams → History retrieval: requests missing history
- Acquisition runtime → Market data services: collects selected source
- Market data services → Jin10 channels: requests market data
- Market data services → Tonghuashun: requests market data
- Jin10 channels → Market data providers: receives market feed
- Tonghuashun → Market data providers: requests market feed
- Jin10 web → Market data providers: receives web feed
- Acquisition runtime → Realtime bars: updates live bars
- Realtime bars → Async persistence: queues persistence
- Async persistence → Market data store: writes quotes and candles
- HTTP and streams → Market data store: reads cached data
- Market data store → PostgreSQL: stores market state
- Acquisition runtime → Raw frame archive: archives raw frames
- Raw frame archive → NATS JetStream: persists and replays frames
- History admission → Research history store: validates and admits datasets
- Research history store → PostgreSQL: stores trusted history
- HTTP and streams → Gold events: serves event analysis
- Browser → Market workspace: uses workspace