Shadow Docs¶

System Map¶

The current Shadow stack is split by product shell, provider workspaces, read services, factor engine, and execution engine.

Area	Owns	Does not own	Start here
`shadow-assembly`	Product workspace, frontend/backend app contract, auth, admin, inbox, fundamentals, news, research, fund product and evidence surfaces	Internal tool storage, source crawling, factor materialization, backtest hot loop	Overview
`download_rqdata`	RiceQuant license use, local parquet data tree, data refresh jobs, quality checks	Public SDK contract, factor formulas, strategy execution	Overview
`download_capitaliq`	Capital IQ paid API requests, raw request ledger, provider observation database	Factor formulas, TTM/YoY logic, Shadow Factor storage	Overview
`shadow-ingest`	Read-only dataframe SDK and HTTP access over `download_rqdata/data`	A second database, crawling, factor materialization, document search	Quick Start
`shadow-octopus`	Web/source acquisition, raw records, object manifests, object downloads	Query APIs, search, read models, paid API provider DBs	Operations
`shadow-lighthouse`	Read-side catalogs, search, document lookup, evidence APIs	Crawling, source checkpoints, raw writes, PDF byte processing	Quick Start
`shadow-factor`	Factor definitions, materialization, formula DSL, supported factor catalog	External data acquisition, strategy execution	Supported Factors
`shadow-backtest`	Package-first stock/futures/options backtest execution core	Factor planning, provider loading, report products, Guorn evidence archive	Overview

Data Flow¶

Provider and source data use separate lanes.

RiceQuant API
  -> download_rqdata/data
  -> shadow-ingest SDK / HTTP
  -> shadow-factor source projections
  -> shadow-backtest market rows
  -> shadow-assembly user workflows

S&P Capital IQ API
  -> download_capitaliq/data/ciq_raw_db
  -> download_capitaliq/data/ciq_db/ciq_financial_observations.v1
  -> Shadow Factor provider adapter
  -> factor panels and downstream research

external websites, filings, feeds, manual files
  -> shadow-octopus
  -> shadow-lighthouse
  -> shadow-assembly document surfaces

Current Production Entrypoints¶

Entrypoint	URL or path	Purpose
Docs	`https://docs.zhengxinfund.com/`	This documentation site
Market data HTTP	`https://data.zhengxinfund.com/`	Public Shadow Ingest HTTP surface
Shadow Assembly local backend	`http://127.0.0.1:18000`	Local app-facing FastAPI API
Docs static root	`/dev/data1/shadow-docs/site/`	Deployed generated documentation

Most Common Tasks¶

Use Shadow Assembly when you need the current product workspace:

Shadow Assembly Overview

Use Shadow Ingest when you need a dataframe over RiceQuant-backed parquet data:

Use downloader workspaces when you need to refresh or audit provider data:

Use Shadow Octopus when you need to acquire or inspect raw source data:

Use Shadow Lighthouse when you need documents, search, objects, or evidence APIs:

Use Shadow Factor when you need computed factor values or formula definitions:

Use Shadow Backtest when you need execution simulation:

Shadow Backtest Overview

Documentation Deployment¶

This site is built locally and served as static HTML on Aliyun. There is no FastAPI, Node, database, or server-side documentation runtime for this site.

Production URL:

https://docs.zhengxinfund.com/

local shadow-docs repo
  -> make build
  -> site/
  -> rsync to aliyun:/dev/data1/shadow-docs/site/
  -> shadow-docs.service on 127.0.0.1:30000
  -> nginx docs.zhengxinfund.com

Deploy from the local docs repository:

cd /Users/yanghh/Documents/code/quant/shadow-docs
make install
make deploy

Production paths:

Item	Value
SSH target	`aliyun`
Static site root	`/dev/data1/shadow-docs/site/`
Systemd unit	`shadow-docs.service`
Local bind	`127.0.0.1:30000`
Public URL	`https://docs.zhengxinfund.com/`

Verification:

make remote-status
curl -I https://docs.zhengxinfund.com/

Do not patch generated files on the server. Update this repository, run make build, then deploy site/.