Skip to content

Commit e07a146

Browse files
Pigbibiclaude
Pigbibi
and
claude
authored
docs: add architecture doc, CLAUDE.md, update spec with combo/crypto (#135)
- ARCHITECTURE.md /.zh-CN.md: complete architecture overview with layer model, data flow, design patterns, naming conventions, scheduler rules - CLAUDE.md: project instructions for QuantPlatformKit - STRATEGY_PLATFORM_SPEC.md: add crypto, combo, snapshot monitoring sections Co-authored-by: Claude <noreply@anthropic.com>
1 parent 19f629b commit e07a146

4 files changed

Lines changed: 370 additions & 2 deletions

File tree

‎CLAUDE.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# QuantPlatformKit - Shared Infrastructure
2+
3+
Shared broker adapters, runtime contracts, strategy loading interfaces, and notification utilities for QuantStrategyLab trading platforms.
4+
5+
## Key Files
6+
7+
- `src/quant_platform_kit/common/strategies.py` — StrategyCatalog, PlatformCapabilityMatrix, PlatformStrategyPolicy
8+
- `src/quant_platform_kit/common/runtime_target.py` — RUNTIME_TARGET_JSON parsing
9+
- `src/quant_platform_kit/strategy_contracts.py` — StrategyRuntimeAdapter, execution contracts
10+
- `scripts/validate_platform_consistency.py` — Cross-platform strategy validation
11+
- `scripts/check_required_env.py` — Environment variable validation
12+
- `docs/ARCHITECTURE.md` — Full architecture documentation
13+
- `docs/STRATEGY_PLATFORM_SPEC.md` — Adding strategies/platforms/plugins spec
14+
15+
## Design Rules
16+
17+
1. **Single Source of Truth**: RUNTIME_TARGET_JSON is the canonical config entry-point
18+
2. **Strategy Registry Pattern**: strategy_registry.py imports catalogs, merges, filters through capability matrix
19+
3. **Auto-Sync**: Plugin mounts and monitor targets auto-align to RUNTIME_TARGET_JSON on startup
20+
4. **Scheduler TZ = Market TZ**: Not service region
21+
5. **Dataclass field order**: Required fields before default fields
22+
23+
## CI / Validation Scripts
24+
25+
- `python scripts/check_required_env.py --platform=schwab` — pre-deploy env check
26+
- `python scripts/validate_platform_consistency.py` — catalog vs registry consistency
27+
- `python scripts/sync_strategy_config.py` — auto-generate Scheduler jobs from config

‎docs/ARCHITECTURE.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# QuantStrategyLab Architecture
2+
3+
> Investing involves risk. This document describes system architecture only, not investment advice.
4+
5+
## Layer Model
6+
7+
```
8+
┌─────────────────────────────────────────────────────────┐
9+
│ EXECUTION LAYER │
10+
│ SchwabPlatform │ IBKRPlatform │ LongBridgePlatform │
11+
│ BinancePlatform │ FirstradePlatform │
12+
│ (Cloud Run) │ (Cloud Run) │ (GitHub Actions+VPS) │
13+
├─────────────────────────────────────────────────────────┤
14+
│ STRATEGY LAYER │
15+
│ UsEquityStrategies │ HkEquityStrategies │
16+
│ CnEquityStrategies │ CryptoStrategies │
17+
│ QuantUsComboStrategies │ QuantHkComboStrategies │
18+
│ (pip wheels, version-pinned in requirements.txt) │
19+
├─────────────────────────────────────────────────────────┤
20+
│ SNAPSHOT LAYER │
21+
│ UsEquitySnapshotPipelines │ HkEquitySnapshotPipelines │
22+
│ CnEquitySnapshotPipelines │ CryptoLivePoolPipelines │
23+
│ (GCS artifacts, consumed by execution layer) │
24+
├─────────────────────────────────────────────────────────┤
25+
│ INFRASTRUCTURE LAYER │
26+
│ QuantPlatformKit │ QuantRuntimeSettings │
27+
│ QuantStrategyPlugins │ MarketSignalSources │
28+
│ (shared contracts, adapters, runtime tooling) │
29+
└─────────────────────────────────────────────────────────┘
30+
```
31+
32+
## Data Flow
33+
34+
```
35+
Strategy Definition (pip package)
36+
→ Strategy Catalog (STRATEGY_CATALOG)
37+
→ Platform Capability Matrix (can this platform run it?)
38+
→ Snapshot Pipeline (generates artifacts → GCS)
39+
→ Runtime Adapter (loads strategy entrypoint)
40+
→ Platform Execution (fetch data → compute → submit orders)
41+
→ Execution Report (GCS + structured log)
42+
→ Monitor Dispatch (probe + dry-run checks)
43+
```
44+
45+
## Configuration Single Source of Truth
46+
47+
Every platform service has ONE canonical config entry-point:
48+
49+
```
50+
RUNTIME_TARGET_JSON = {
51+
"platform_id": "...",
52+
"strategy_profile": "...",
53+
"execution_mode": "live" | "paper",
54+
"dry_run_only": true | false,
55+
"account_scope": "...",
56+
"scheduler": {
57+
"main_time": "45 15 * * *",
58+
"precheck_time": "45 9 * * *",
59+
"probe_time": "35 9,15 * * *",
60+
"timezone": "America/New_York"
61+
}
62+
}
63+
```
64+
65+
**All other config values that reference strategy/platform names derive from this.** The auto-sync layer (config-sync) corrects stale references on startup.
66+
67+
## Design Patterns
68+
69+
### 1. Strategy Registry Pattern
70+
71+
Each platform has a `strategy_registry.py` that:
72+
- Imports shared strategy catalogs from pip packages
73+
- Merges multiple catalogs (US + HK + Combo)
74+
- Filters strategies through a capability matrix
75+
- Routes to the correct runtime adapter
76+
77+
```
78+
profile → domain check → adapter lookup → StrategyRuntimeAdapter
79+
```
80+
81+
### 2. Runtime Adapter Pattern
82+
83+
Every strategy exposes a `StrategyRuntimeAdapter` via `get_platform_runtime_adapter(profile, platform_id)`. The adapter declares:
84+
- `available_inputs` — what data the strategy needs
85+
- `managed_symbols_extractor` — symbols to monitor
86+
- `runtime_policy` — execution timing contract
87+
88+
### 3. Config Auto-Sync Pattern
89+
90+
At module load time, the `config-sync` layer:
91+
1. Reads `STRATEGY_PROFILE` from `RUNTIME_TARGET_JSON`
92+
2. Scans plugin mount JSON → corrects stale `strategy` fields
93+
3. Scans monitor target JSON → corrects stale `strategy_profile` fields
94+
4. Logs `[config-sync]` messages for each correction
95+
96+
**Result**: User only changes `RUNTIME_TARGET_JSON`. Everything else auto-aligns.
97+
98+
### 4. Single Source of Truth Pattern
99+
100+
- `RUNTIME_TARGET_JSON` = canonical strategy+platform assignment
101+
- `STRATEGY_PROFILE` env var = DEPRECATED (removed)
102+
- Plugin mount `strategy` field = auto-synced to match
103+
- Monitor target `strategy_profile` = auto-synced to match
104+
105+
### 5. Execution Timing Pattern
106+
107+
Strategies declare `signal_effective_after_trading_days` and `execution_timing_contract` in their runtime policy. The platform:
108+
- Checks market calendar before execution
109+
- Respects the timing contract (next_trading_day, etc.)
110+
- Uses `execution_dedup_enabled` for multi-day windows (monthly DCA)
111+
112+
## Naming Conventions
113+
114+
| Type | Convention | Example |
115+
|---|---|---|
116+
| Platform ID | lowercase, underscores | `schwab`, `interactive_brokers`, `longbridge` |
117+
| Strategy Profile | lowercase, underscores | `soxl_soxx_trend_income` |
118+
| Domain | lowercase, underscores | `us_equity`, `hk_equity`, `quant_combo` |
119+
| Repo Name | PascalCase for platforms, camelCase for packages | `CharlesSchwabPlatform`, `us-equity-strategies` |
120+
| Pip Package | lowercase-hyphenated | `us-equity-strategies`, `quant-us-combo-strategies` |
121+
| Python Package | lowercase_underscores | `us_equity_strategies`, `quant_us_combo_strategies` |
122+
| GCP Service | lowercase-hyphenated | `charles-schwab-quant-service` |
123+
| Scheduler Job | `{platform}-{strategy}-{type}` | `schwab-soxl-main`, `ibkr-u16608560-precheck` |
124+
125+
## Scheduler Rules
126+
127+
| Market | Calendar | Timezone | Execution Window | Cron |
128+
|---|---|---|---|---|
129+
| US Equity | NASDAQ | `America/New_York` | 3:45 PM ET | `45 15 * * *` |
130+
| HK Equity | XHKG | `Asia/Hong_Kong` | 3:45 PM HKT | `45 15 * * *` |
131+
| A-Share | XSHG | `Asia/Shanghai` | 2:45 PM CST | `45 14 * * *` |
132+
| Crypto | 24/7 | UTC | N/A | GitHub Actions `schedule` |
133+
134+
**Rule**: Scheduler timezone = **market** timezone, not service region.
135+
136+
## Adding a New Platform
137+
138+
1. Create platform repo from the closest existing template
139+
2. Implement `strategy_registry.py`:
140+
- Import shared catalogs, merge them
141+
- Define `PLATFORM_CAPABILITY_MATRIX`
142+
- Define `*_EXCLUDED_LIVE_PROFILES`
143+
- Implement `get_platform_runtime_adapter(profile, platform_id)`
144+
3. Implement `runtime_config_support.py`:
145+
- Define `PlatformRuntimeSettings` dataclass
146+
- REQUIRED fields FIRST, default fields AFTER (Python dataclass rule)
147+
- Implement `load_platform_runtime_settings()`
148+
4. Implement broker adapters, market data ports, execution ports
149+
5. Add `main.py` with Flask routes (`/run`, `/dry-run`, `/probe`, `/health`, `/monitor-dispatch`)
150+
6. Add Cloud Scheduler jobs (or GitHub Actions for self-hosted)
151+
7. Add `.env.example` with all required env vars
152+
8. Add to `MONITOR_DISPATCH_TARGETS_JSON` for cross-platform monitoring
153+
154+
## Adding a New Strategy
155+
156+
1. Add strategy definition to the appropriate shared catalog pip package
157+
2. Set `compatible_platforms` in the catalog
158+
3. Set `runtime_enabled_profiles` for rollout
159+
4. Implement `get_platform_runtime_adapter(profile, platform_id)` in the runtime_adapters module
160+
5. Each platform auto-discovers it via `derive_enabled_profiles_for_platform()`
161+
6. To deploy: update `RUNTIME_TARGET_JSON.strategy_profile` on the target service
162+
163+
## Adding a New Plugin
164+
165+
1. Add plugin definition to `STRATEGY_PLUGIN_MOUNTS_JSON`
166+
2. The `strategy` field auto-syncs to match `RUNTIME_TARGET_JSON.strategy_profile`
167+
3. Plugin signals are consumed by the strategy entrypoint
168+
169+
## Deployment Safety
170+
171+
1. `python scripts/check_required_env.py --platform=<id>` — validate env vars
172+
2. `python scripts/validate_platform_consistency.py` — validate catalog vs registry
173+
3. Deploy to Cloud Run with `--clear-base-image`
174+
4. Verify `/health` returns 200 with no module errors
175+
5. Trigger `/dry-run` via Scheduler — verify execution report
176+
6. Enable live execution only after dry-run passes
177+
178+
## Version History
179+
180+
| Version | Date | Changes |
181+
|---|---|---|
182+
| 1.0 | 2026-06-30 | Initial architecture document |

‎docs/ARCHITECTURE.zh-CN.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# QuantStrategyLab 架构设计
2+
3+
## 分层模型
4+
5+
```
6+
┌─────────────────────────────────────────────────────────┐
7+
│ 执行层 │
8+
│ SchwabPlatform │ IBKRPlatform │ LongBridgePlatform │
9+
│ BinancePlatform │ FirstradePlatform │
10+
│ (Cloud Run) │ (Cloud Run) │ (GitHub Actions+VPS) │
11+
├─────────────────────────────────────────────────────────┤
12+
│ 策略层 │
13+
│ UsEquityStrategies │ HkEquityStrategies │
14+
│ CnEquityStrategies │ CryptoStrategies │
15+
│ QuantUsComboStrategies │ QuantHkComboStrategies │
16+
│ (pip 包，版本锁定在 requirements.txt) │
17+
├─────────────────────────────────────────────────────────┤
18+
│ 快照层 │
19+
│ UsEquitySnapshotPipelines │ HkEquitySnapshotPipelines │
20+
│ CnEquitySnapshotPipelines │ CryptoLivePoolPipelines │
21+
│ (产出 GCS 产物，供执行层消费) │
22+
├─────────────────────────────────────────────────────────┤
23+
│ 基础设施层 │
24+
│ QuantPlatformKit │ QuantRuntimeSettings │
25+
│ QuantStrategyPlugins │ MarketSignalSources │
26+
│ (共享契约、适配器、运行时工具) │
27+
└─────────────────────────────────────────────────────────┘
28+
```
29+
30+
## 数据流
31+
32+
```
33+
策略定义（pip 包）
34+
→ 策略目录（STRATEGY_CATALOG）
35+
→ 平台能力矩阵（此平台能跑吗？）
36+
→ 快照管线（产出产物 → GCS）
37+
→ 运行时适配器（加载策略入口）
38+
→ 平台执行（拉数据 → 计算 → 下单）
39+
→ 执行报告（GCS + 结构化日志）
40+
→ 监控调度（probe + dry-run 检查）
41+
```
42+
43+
## 配置唯一数据源
44+
45+
每个平台服务只有一个权威配置入口：
46+
47+
```json
48+
RUNTIME_TARGET_JSON = {
49+
"platform_id": "...",
50+
"strategy_profile": "...",
51+
"execution_mode": "live",
52+
"scheduler": {
53+
"main_time": "45 15 * * *",
54+
"precheck_time": "45 9 * * *",
55+
"probe_time": "35 9,15 * * *",
56+
"timezone": "America/New_York"
57+
}
58+
}
59+
```
60+
61+
**所有其他引用策略/平台名称的配置值都从这里推导。** 自动同步层（config-sync）在启动时修正过期引用。
62+
63+
## 设计模式
64+
65+
### 1. 策略注册模式
66+
67+
每个平台有 `strategy_registry.py`：
68+
- 从 pip 包导入共享策略目录
69+
- 合并多个目录（US + HK + Combo）
70+
- 通过能力矩阵过滤策略
71+
- 路由到正确的运行时适配器
72+
73+
### 2. 运行时适配器模式
74+
75+
每个策略通过 `get_platform_runtime_adapter(profile, platform_id)` 暴露 `StrategyRuntimeAdapter`：
76+
- `available_inputs` — 需要什么数据
77+
- `managed_symbols_extractor` — 监控哪些标的
78+
- `runtime_policy` — 执行时点契约
79+
80+
### 3. 配置自动同步模式
81+
82+
模块加载时，`config-sync` 层：
83+
1. 从 `RUNTIME_TARGET_JSON` 读取 `STRATEGY_PROFILE`
84+
2. 扫描插件挂载 JSON → 修正过期的 `strategy` 字段
85+
3. 扫描监控目标 JSON → 修正过期的 `strategy_profile` 字段
86+
4. 打印 `[config-sync]` 日志记录每次修正
87+
88+
### 4. 唯一数据源模式
89+
90+
- `RUNTIME_TARGET_JSON` = 权威策略+平台配置
91+
- `STRATEGY_PROFILE` 环境变量 = 已废弃（已移除）
92+
- 插件挂载 `strategy` 字段 = 自动同步
93+
- 监控目标 `strategy_profile` = 自动同步
94+
95+
### 5. 执行时点契约
96+
97+
策略在运行时策略中声明 `signal_effective_after_trading_days` 和 `execution_timing_contract`。平台：
98+
- 执行前检查市场日历
99+
- 遵守时点契约（next_trading_day 等）
100+
- 对多日窗口（月度 DCA）使用 `execution_dedup_enabled`
101+
102+
## Scheduler 规则
103+
104+
**Scheduler 时区 = 市场时区，不是服务区域。**
105+
106+
| 市场 | 日历 | 时区 | 执行窗口 |
107+
|---|---|---|---|
108+
| US Equity | NASDAQ | `America/New_York` | 3:45 PM ET |
109+
| HK Equity | XHKG | `Asia/Hong_Kong` | 3:45 PM HKT |
110+
| A股 | XSHG | `Asia/Shanghai` | 2:45 PM CST |
111+
| Crypto | 24/7 | UTC | GitHub Actions |
112+
113+
## 新增平台规范
114+
115+
1. 从最相似现有模板创建平台仓库
116+
2. 实现 `strategy_registry.py`
117+
3. 实现 `runtime_config_support.py`（dataclass 必填字段在前）
118+
4. 实现券商适配器、行情端口、执行端口
119+
5. 添加 Flask 路由（`/run`, `/dry-run`, `/probe`, `/health`, `/monitor-dispatch`）
120+
6. 添加 Cloud Scheduler 任务
121+
7. 添加 `.env.example` 环境变量模板
122+
8. 加入跨平台监控
123+
124+
## 新增策略规范
125+
126+
1. 在共享目录 pip 包中添加策略定义
127+
2. 设置 `compatible_platforms`
128+
3. 在 `runtime_adapters` 中实现适配器
129+
4. 平台自动发现（无需改平台代码）
130+
5. 部署：改 `RUNTIME_TARGET_JSON.strategy_profile`
131+
132+
## 部署安全检查
133+
134+
1. `python scripts/check_required_env.py --platform=<id>`
135+
2. `python scripts/validate_platform_consistency.py`
136+
3. 部署后用 `/health` 验证模块导入
137+
4. `/dry-run` 验证全链路
138+
5. 确认执行报告无错误后启用实盘

‎docs/STRATEGY_PLATFORM_SPEC.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,9 +154,30 @@ The auto-sync layer handles everything else (plugin mounts, monitor targets).
154154

155155
The `execution_dedup_enabled` flag prevents duplicate execution within the month window.
156156

157+
| Crypto | GitHub Actions `schedule` | Self-hosted runner, 24/7, heartbeat `35 * * * *` |
158+
159+
The `execution_dedup_enabled` flag prevents duplicate execution within the month window.
160+
161+
## Snapshot Pipeline Monitoring
162+
163+
Snapshot-backed strategies depend on upstream pipelines. To detect failures:
164+
165+
1. `/probe` checks that required snapshot artifacts exist in GCS
166+
2. `feature_snapshot_fallback_mode` controls behavior when artifacts are missing
167+
3. 7-day DCA retry window absorbs transient pipeline delays
168+
169+
## Combo Strategy Pattern
170+
171+
Combo strategies (e.g., `us_equity_combo`) combine sub-strategies. They are:
172+
- Defined in separate pip packages, imported and merged into platform catalogs
173+
- Share the parent platform's Scheduler and monitoring
174+
- Sub-strategy execution handled internally by the combo entrypoint
175+
- Platform only needs to declare `quant_combo` domain and inputs
176+
157177
## Version History
158178

159179
| Version | Date | Changes |
160180
|---|---|---|
161-
| 1.0 | 2026-06-30 | Initial spec: single source of truth, auto-sync, validation scripts |
162-
| 1.1 | 2026-06-30 | Add scheduler timezone rules, strategy frequency types |
181+
| 1.0 | 2026-06-30 | Initial spec |
182+
| 1.1 | 2026-06-30 | Scheduler timezone rules, frequency types |
183+
| 1.2 | 2026-06-30 | Snapshot monitoring, combo strategy pattern, crypto platform |

0 commit comments

Comments
 (0)