# oficcejo/tdx-api architecture

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

- Interactive diagram: https://gitdiagram.com/oficcejo/tdx-api
- Repository: https://github.com/oficcejo/tdx-api

## Overview

This repository provides a Go client for querying TDX stock data, plus a Web dashboard and REST API. The primary workflow is a browser or API caller requesting stock data; Web handlers dispatch to the client, which encodes TDX protocol requests and decodes responses. Separate branches cover code and trading-calendar data, historical-data downloads, and optional Tonghuashun adjusted K-lines. The main runtime calls are supported by excerpts; some extended API wiring is only documented, so uncertain links are omitted.

Main entry points: [`client.go`](https://github.com/oficcejo/tdx-api/blob/main/client.go) (TDX client), [`web/server.go`](https://github.com/oficcejo/tdx-api/blob/main/web/server.go) (HTTP API handlers), [`extend/pull-trade.go`](https://github.com/oficcejo/tdx-api/blob/main/extend/pull-trade.go) (Trade downloader), [`extend/pull-kline.go`](https://github.com/oficcejo/tdx-api/blob/main/extend/pull-kline.go) (K-line downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_ui["Dashboard UI<br/>[app.js]"]
  node_api["HTTP API handlers<br/>[server.go]"]
  node_extended_api["Extended API"]
  node_tasks["Background tasks<br/>[tasks.go]"]
end

subgraph group_client["TDX client"]
  node_client_core["TDX client<br/>[client.go]"]
  node_connection["Connection setup<br/>[dial.go]"]
  node_code_catalog[("Stock code catalog<br/>[codes.go]")]
  node_calendar[("Trading calendar<br/>[workday.go]")]
end

subgraph group_extensions["Data extensions"]
  node_kline_pull["K-line downloader<br/>[pull-kline.go]"]
  node_trade_pull["Trade downloader<br/>[pull-trade.go]"]
  node_mysql_pull[("MySQL K-lines")]
  node_ths_source["Tonghuashun source<br/>[spider-ths.go]"]
  node_income["Income analysis<br/>[income.go]"]
end

subgraph group_protocol["Protocol"]
  node_protocol_frames["Frame encoding<br/>[frame.go]"]
  node_protocol_models["Request / response models<br/>[model_kline.go]"]
  node_quote_data["Quotes and trades<br/>[model_quote.go]"]
end

node_user(("Browser / API caller"))
node_tdx_servers{{"TDX servers"}}
node_ths_service{{"Tonghuashun service"}}
node_storage[("Local / SQL storage")]

node_user -->|"uses"| node_ui
node_ui -->|"fetches data"| node_api
node_user -->|"requests endpoints"| node_api
node_api -->|"queries stock data"| node_client_core
node_extended_api -->|"queries stock data"| node_client_core
node_api -->|"starts pull task"| node_kline_pull
node_tasks -.->|"tracks task state"| node_api
node_client_core -->|"sends frames"| node_protocol_frames
node_protocol_frames -->|"encodes requests"| node_protocol_models
node_protocol_models -.->|"decodes responses"| node_client_core
node_connection -.->|"connects to"| node_tdx_servers
node_client_core -.->|"exchanges data"| node_tdx_servers
node_client_core -->|"uses code metadata"| node_code_catalog
node_code_catalog -->|"persists catalog"| node_storage
node_calendar -->|"persists workdays"| node_storage
node_kline_pull -->|"fetches K-lines"| node_client_core
node_kline_pull -->|"stores K-lines"| node_storage
node_mysql_pull -->|"fetches K-lines"| node_client_core
node_mysql_pull -->|"stores K-lines"| node_storage
node_trade_pull -->|"fetches trades"| node_client_core
node_trade_pull -->|"iterates workdays"| node_calendar
node_trade_pull -->|"writes CSV files"| node_storage
node_ths_source -->|"requests adjusted data"| node_ths_service
node_api -.->|"serves alternate K-lines"| node_ths_source
node_income -->|"uses price types"| node_protocol_models
node_client_core -.->|"returns market data"| node_quote_data

click node_ui "https://github.com/oficcejo/tdx-api/blob/main/web/static/app.js"
click node_api "https://github.com/oficcejo/tdx-api/blob/main/web/server.go"
click node_extended_api "https://github.com/oficcejo/tdx-api/blob/main/web/server_api_extended.go"
click node_tasks "https://github.com/oficcejo/tdx-api/blob/main/web/tasks.go"
click node_client_core "https://github.com/oficcejo/tdx-api/blob/main/client.go"
click node_connection "https://github.com/oficcejo/tdx-api/blob/main/dial.go"
click node_code_catalog "https://github.com/oficcejo/tdx-api/blob/main/codes.go"
click node_calendar "https://github.com/oficcejo/tdx-api/blob/main/workday.go"
click node_protocol_frames "https://github.com/oficcejo/tdx-api/blob/main/protocol/frame.go"
click node_protocol_models "https://github.com/oficcejo/tdx-api/blob/main/protocol/model_kline.go"
click node_quote_data "https://github.com/oficcejo/tdx-api/blob/main/protocol/model_quote.go"
click node_kline_pull "https://github.com/oficcejo/tdx-api/blob/main/extend/pull-kline.go"
click node_trade_pull "https://github.com/oficcejo/tdx-api/blob/main/extend/pull-trade.go"
click node_mysql_pull "https://github.com/oficcejo/tdx-api/blob/main/extend/pull-kline-mysql.go"
click node_ths_source "https://github.com/oficcejo/tdx-api/blob/main/extend/spider-ths.go"
click node_income "https://github.com/oficcejo/tdx-api/blob/main/extend/income.go"

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_ui,node_api,node_extended_api,node_tasks,node_user toneBlue
class node_client_core,node_connection,node_code_catalog,node_calendar,node_storage toneAmber
class node_kline_pull,node_trade_pull,node_mysql_pull,node_ths_source,node_income,node_tdx_servers toneMint
class node_protocol_frames,node_protocol_models,node_quote_data toneRose
class node_ths_service toneIndigo
```

## Components

### Web application

- [Dashboard UI](https://github.com/oficcejo/tdx-api/blob/main/web/static/app.js): `web/static/app.js`
- [HTTP API handlers](https://github.com/oficcejo/tdx-api/blob/main/web/server.go): `web/server.go`
- [Extended API](https://github.com/oficcejo/tdx-api/blob/main/web/server_api_extended.go): `web/server_api_extended.go`
- [Background tasks](https://github.com/oficcejo/tdx-api/blob/main/web/tasks.go): `web/tasks.go`

### TDX client

- [TDX client](https://github.com/oficcejo/tdx-api/blob/main/client.go): `client.go`
- [Connection setup](https://github.com/oficcejo/tdx-api/blob/main/dial.go): `dial.go`
- [Stock code catalog](https://github.com/oficcejo/tdx-api/blob/main/codes.go): `codes.go`
- [Trading calendar](https://github.com/oficcejo/tdx-api/blob/main/workday.go): `workday.go`

### Data extensions

- [K-line downloader](https://github.com/oficcejo/tdx-api/blob/main/extend/pull-kline.go): `extend/pull-kline.go`
- [Trade downloader](https://github.com/oficcejo/tdx-api/blob/main/extend/pull-trade.go): `extend/pull-trade.go`
- [MySQL K-lines](https://github.com/oficcejo/tdx-api/blob/main/extend/pull-kline-mysql.go): `extend/pull-kline-mysql.go`
- [Tonghuashun source](https://github.com/oficcejo/tdx-api/blob/main/extend/spider-ths.go): `extend/spider-ths.go`
- [Income analysis](https://github.com/oficcejo/tdx-api/blob/main/extend/income.go): `extend/income.go`

### Protocol

- [Frame encoding](https://github.com/oficcejo/tdx-api/blob/main/protocol/frame.go): `protocol/frame.go`
- [Request / response models](https://github.com/oficcejo/tdx-api/blob/main/protocol/model_kline.go): `protocol/model_kline.go`
- [Quotes and trades](https://github.com/oficcejo/tdx-api/blob/main/protocol/model_quote.go): `protocol/model_quote.go`

### Other components

- **Browser / API caller**
- **TDX servers**
- **Tonghuashun service**
- **Local / SQL storage**

## Connections

- Browser / API caller → Dashboard UI: uses (evidence: `README.md`)
- Dashboard UI → HTTP API handlers: fetches data (evidence: `web/static/app.js`)
- Browser / API caller → HTTP API handlers: requests endpoints (evidence: `README.md`)
- HTTP API handlers → TDX client: queries stock data (evidence: `web/server.go`)
- Extended API → TDX client: queries stock data (evidence: `web/server_api_extended.go`)
- HTTP API handlers → K-line downloader: starts pull task (evidence: `web/server.go`)
- Background tasks → HTTP API handlers: tracks task state
- TDX client → Frame encoding: sends frames (evidence: `client.go`)
- Frame encoding → Request / response models: encodes requests (evidence: `protocol/frame.go`)
- Request / response models → TDX client: decodes responses
- Connection setup → TDX servers: connects to
- TDX client → TDX servers: exchanges data
- TDX client → Stock code catalog: uses code metadata (evidence: `client.go`)
- Stock code catalog → Local / SQL storage: persists catalog (evidence: `codes.go`)
- Trading calendar → Local / SQL storage: persists workdays (evidence: `workday.go`)
- K-line downloader → TDX client: fetches K-lines (evidence: `extend/pull-kline.go`)
- K-line downloader → Local / SQL storage: stores K-lines (evidence: `extend/pull-kline.go`)
- MySQL K-lines → TDX client: fetches K-lines (evidence: `extend/pull-kline-mysql.go`)
- MySQL K-lines → Local / SQL storage: stores K-lines (evidence: `extend/pull-kline-mysql.go`)
- Trade downloader → TDX client: fetches trades (evidence: `extend/pull-trade.go`)
- Trade downloader → Trading calendar: iterates workdays (evidence: `extend/pull-trade.go`)
- Trade downloader → Local / SQL storage: writes CSV files (evidence: `extend/pull-trade.go`)
- Tonghuashun source → Tonghuashun service: requests adjusted data (evidence: `extend/spider-ths.go`)
- HTTP API handlers → Tonghuashun source: serves alternate K-lines
- Income analysis → Request / response models: uses price types (evidence: `extend/income.go`)
- TDX client → Quotes and trades: returns market data
