# hithink-tech/financial-api architecture

> Architecture diagram of the GitHub repository hithink-tech/financial-api, 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/hithink-tech/financial-api
- Repository: https://github.com/hithink-tech/financial-api

## Overview

This repository provides official A-share financial-data access through a Node.js CLI and a Python SDK, plus local DuckDB research workflows. A typical CLI request starts with a user command, resolves configuration and credentials, dispatches to a remote or local command, then returns structured output. Remote requests map validated capability definitions into Fuyao API calls; local workflows initialize, synchronize, validate, repair, or query a database. The README also documents REST, hosted MCP, and Agent Skill entry points, but their implementations are not present in the supplied tree. Several links for unsampled Python and command modules follow documented responsibilities.

Main entry points: [`hithink-finance-cli/src/commands/remote.ts`](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/remote.ts) (Remote commands), [`hithink-finance-cli/src/cli/program.ts`](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/cli/program.ts) (Command dispatch), [`hithink-finance-cli/src/commands/data/index.ts`](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/data/index.ts) (Database commands), [`hithink-finance-cli/src/cli/main.ts`](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/cli/main.ts) (CLI bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_cli_entry["CLI bootstrap<br/>[main.ts]"]
  node_config["Config resolution<br/>[config.ts]"]
  node_program["Command dispatch<br/>[program.ts]"]
  node_remote_commands["Remote commands<br/>[remote.ts]"]
  node_domain_commands["Domain commands<br/>[index.ts]"]
  node_renderer["Structured output<br/>[renderer.ts]"]
  node_db_commands["Database commands<br/>[index.ts]"]
end

subgraph group_remote["Remote data"]
  node_capabilities["Remote contracts"]
  node_remote_query["Query execution<br/>[remote-query.ts]"]
  node_fuyao_client["HTTP client<br/>[client.ts]"]
  node_fuyao_service[("Fuyao service")]
  node_dump_client["Dump downloader<br/>[dump-client.ts]"]
  node_python_rest[("Fuyao REST API")]
end

subgraph group_local["Local research"]
  node_duckdb[("DuckDB store<br/>[connection.ts]")]
  node_local_query["Local SQL query<br/>[local-query.ts]"]
  node_db_schema["Schema migrations<br/>[migrations.ts]"]
end

subgraph group_python["Python access"]
  node_python_sdk["Python SDK<br/>[sdk.py]"]
  node_python_cli["marketdb CLI<br/>[cli.py]"]
  node_marketdb_updater["Database updates<br/>[auto.py]"]
  node_marketdb_db[("Python DuckDB<br/>[db.py]")]
  node_marketdb_checks["Quality checks<br/>[quality.py]"]
end

node_terminal_user(("Terminal user"))
node_python_user(("Python caller"))
node_hosted_access(("REST / MCP clients"))

node_terminal_user -->|"runs command"| node_cli_entry
node_cli_entry -->|"loads settings"| node_config
node_cli_entry -->|"builds and dispatches"| node_program
node_program -->|"registers commands"| node_remote_commands
node_program -->|"registers commands"| node_domain_commands
node_program -->|"registers commands"| node_db_commands
node_remote_commands -->|"uses definitions"| node_capabilities
node_remote_commands -->|"executes query"| node_remote_query
node_remote_query -->|"requests data"| node_fuyao_client
node_fuyao_client -->|"calls API"| node_fuyao_service
node_remote_commands -->|"downloads dumps"| node_dump_client
node_dump_client -->|"signs and downloads"| node_fuyao_service
node_remote_commands -->|"renders result"| node_renderer
node_db_commands -->|"opens database"| node_duckdb
node_db_commands -->|"migrates schema"| node_db_schema
node_db_commands -->|"renders result"| node_renderer
node_local_query -->|"queries and exports"| node_duckdb
node_python_user -->|"calls SDK"| node_python_sdk
node_python_sdk -->|"requests data"| node_python_rest
node_python_user -->|"runs command"| node_python_cli
node_python_cli -->|"dispatches update"| node_marketdb_updater
node_marketdb_updater -->|"updates database"| node_marketdb_db
node_python_cli -->|"runs validation"| node_marketdb_checks
node_marketdb_checks -->|"checks data"| node_marketdb_db
node_hosted_access -.->|"uses hosted API"| node_fuyao_service

click node_cli_entry "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/cli/main.ts"
click node_config "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/application/config.ts"
click node_program "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/cli/program.ts"
click node_remote_commands "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/remote.ts"
click node_domain_commands "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/market/index.ts"
click node_capabilities "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/contracts/remote-capabilities.ts"
click node_remote_query "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/application/use-cases/remote-query.ts"
click node_fuyao_client "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/fuyao/client.ts"
click node_dump_client "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/duckdb/dump-client.ts"
click node_renderer "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/output/renderer.ts"
click node_db_commands "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/data/index.ts"
click node_duckdb "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/duckdb/connection.ts"
click node_local_query "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/application/use-cases/local-query.ts"
click node_db_schema "https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/duckdb/migrations.ts"
click node_python_sdk "https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/sdk.py"
click node_python_cli "https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/cli.py"
click node_marketdb_updater "https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/updaters/auto.py"
click node_marketdb_db "https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/db.py"
click node_marketdb_checks "https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/checks/quality.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_cli_entry,node_config,node_program,node_remote_commands,node_domain_commands,node_renderer,node_db_commands,node_terminal_user,node_hosted_access toneBlue
class node_capabilities,node_remote_query,node_fuyao_client,node_fuyao_service,node_dump_client,node_python_rest toneAmber
class node_duckdb,node_local_query,node_db_schema toneMint
class node_python_sdk,node_python_cli,node_marketdb_updater,node_marketdb_db,node_marketdb_checks toneRose
class node_python_user toneIndigo
```

## Components

### CLI runtime

- [CLI bootstrap](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/cli/main.ts): `hithink-finance-cli/src/cli/main.ts`
- [Config resolution](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/application/config.ts): `hithink-finance-cli/src/application/config.ts`
- [Command dispatch](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/cli/program.ts): `hithink-finance-cli/src/cli/program.ts`
- [Remote commands](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/remote.ts): `hithink-finance-cli/src/commands/remote.ts`
- [Domain commands](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/market/index.ts): `hithink-finance-cli/src/commands/market/index.ts`
- [Structured output](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/output/renderer.ts): `hithink-finance-cli/src/output/renderer.ts`
- [Database commands](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/commands/data/index.ts): `hithink-finance-cli/src/commands/data/index.ts`

### Remote data

- [Remote contracts](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/contracts/remote-capabilities.ts): `hithink-finance-cli/src/contracts/remote-capabilities.ts`
- [Query execution](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/application/use-cases/remote-query.ts): `hithink-finance-cli/src/application/use-cases/remote-query.ts`
- [HTTP client](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/fuyao/client.ts): `hithink-finance-cli/src/infrastructure/fuyao/client.ts`
- **Fuyao service**
- [Dump downloader](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/duckdb/dump-client.ts): `hithink-finance-cli/src/infrastructure/duckdb/dump-client.ts`
- **Fuyao REST API**

### Local research

- [DuckDB store](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/duckdb/connection.ts): `hithink-finance-cli/src/infrastructure/duckdb/connection.ts`
- [Local SQL query](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/application/use-cases/local-query.ts): `hithink-finance-cli/src/application/use-cases/local-query.ts`
- [Schema migrations](https://github.com/hithink-tech/financial-api/blob/main/hithink-finance-cli/src/infrastructure/duckdb/migrations.ts): `hithink-finance-cli/src/infrastructure/duckdb/migrations.ts`

### Python access

- [Python SDK](https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/sdk.py): `python/marketdb/sdk.py`
- [marketdb CLI](https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/cli.py): `python/marketdb/cli.py`
- [Database updates](https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/updaters/auto.py): `python/marketdb/updaters/auto.py`
- [Python DuckDB](https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/db.py): `python/marketdb/db.py`
- [Quality checks](https://github.com/hithink-tech/financial-api/blob/main/python/marketdb/checks/quality.py): `python/marketdb/checks/quality.py`

### Other components

- **Terminal user**
- **Python caller**
- **REST / MCP clients**

## Connections

- Terminal user → CLI bootstrap: runs command
- CLI bootstrap → Config resolution: loads settings
- CLI bootstrap → Command dispatch: builds and dispatches
- Command dispatch → Remote commands: registers commands
- Command dispatch → Domain commands: registers commands
- Command dispatch → Database commands: registers commands
- Remote commands → Remote contracts: uses definitions
- Remote commands → Query execution: executes query
- Query execution → HTTP client: requests data
- HTTP client → Fuyao service: calls API
- Remote commands → Dump downloader: downloads dumps
- Dump downloader → Fuyao service: signs and downloads
- Remote commands → Structured output: renders result
- Database commands → DuckDB store: opens database
- Database commands → Schema migrations: migrates schema
- Database commands → Structured output: renders result
- Local SQL query → DuckDB store: queries and exports
- Python caller → Python SDK: calls SDK
- Python SDK → Fuyao REST API: requests data
- Python caller → marketdb CLI: runs command
- marketdb CLI → Database updates: dispatches update
- Database updates → Python DuckDB: updates database
- marketdb CLI → Quality checks: runs validation
- Quality checks → Python DuckDB: checks data
- REST / MCP clients → Fuyao service: uses hosted API