|
| 1 | +# QuantRuntimeSettings Architecture |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +QuantRuntimeSettings is a **config-driven** runtime settings package that serves as the central control plane for QuantStrategyLab deployments. It defines versioned strategy-to-platform assignments and hosts a Cloudflare Workers-based strategy switch console. |
| 6 | + |
| 7 | +The repository has a **three-tier architecture** built around a single source of truth: |
| 8 | + |
| 9 | +``` |
| 10 | +platform-config.json (single source of truth) |
| 11 | + | |
| 12 | + v |
| 13 | + Python scripts (validation, code generation, deployment tooling) |
| 14 | + | |
| 15 | + v |
| 16 | + Generated assets (config.js, page_asset.js, strategy_profiles_asset.js) |
| 17 | + | |
| 18 | + v |
| 19 | + Web application (Cloudflare Worker + frontend SPA) |
| 20 | +``` |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## Directory Layout |
| 25 | + |
| 26 | +``` |
| 27 | +. |
| 28 | +├── platform-config.json # Central configuration (single source of truth) |
| 29 | +├── internal_dependency_matrix.json # Internal git dependency pin tracking |
| 30 | +│ |
| 31 | +├── python/ # Python tooling (tests, CI, scripts) |
| 32 | +│ ├── pyproject.toml # Python project definition & linter config |
| 33 | +│ ├── scripts/ # Build & validation scripts |
| 34 | +│ │ ├── build_config.py # Full build pipeline |
| 35 | +│ │ ├── build_platform_config.py # Generate config.js from platform-config.json |
| 36 | +│ │ ├── build_runtime_switch.py # Build transient runtime targets |
| 37 | +│ │ ├── runtime_settings.py # Core validation & assignment engine |
| 38 | +│ │ ├── check_internal_dependency_matrix.py |
| 39 | +│ │ ├── gate_codex_app_review.py # PR merge gate |
| 40 | +│ │ ├── inject_platform_config.py # Inject config into index.html |
| 41 | +│ │ ├── run_codex_pr_review.py # Codex AI PR review |
| 42 | +│ │ └── sync_strategy_switch_page_asset.py |
| 43 | +│ ├── tests/ # Python unit tests |
| 44 | +│ │ ├── test_runtime_settings.py |
| 45 | +│ │ └── test_internal_dependency_matrix.py |
| 46 | +│ └── shell/ # Shell scripts (Python ecosystem) |
| 47 | +│ └── checkout_internal_dependency_consumers.sh |
| 48 | +│ |
| 49 | +├── web/ # JavaScript web application |
| 50 | +│ └── strategy-switch-console/ # Cloudflare Workers app |
| 51 | +│ ├── worker.js # Worker backend (OAuth, routing, KV) |
| 52 | +│ ├── index.html # SPA shell |
| 53 | +│ ├── app.js # Frontend JavaScript |
| 54 | +│ ├── app.css # Frontend styles |
| 55 | +│ ├── config.js # Generated: Platform config constants |
| 56 | +│ ├── page_asset.js # Generated: Embedded index.html |
| 57 | +│ ├── strategy_profiles_asset.js # Generated: Strategy catalog |
| 58 | +│ ├── app_css.js # Generated: Embedded styles |
| 59 | +│ ├── app_js.js # Generated: Embedded JS |
| 60 | +│ └── wrangler.toml.example # Cloudflare Workers config template |
| 61 | +│ |
| 62 | +├── schemas/ # Shared JSON Schema (consumed by both) |
| 63 | +│ └── runtime-target.schema.json # Runtime target validation schema |
| 64 | +│ |
| 65 | +├── tests/ # JavaScript tests |
| 66 | +│ ├── strategy_switch_worker_validation.mjs |
| 67 | +│ └── test_cash_financing.js |
| 68 | +│ |
| 69 | +├── docs/ # Documentation |
| 70 | +├── examples/targets/ # Example runtime targets per platform |
| 71 | +├── prompts/ # LLM prompt templates |
| 72 | +│ |
| 73 | +└── .github/workflows/ # CI/CD workflows |
| 74 | + ├── validate.yml # Python + JS validation (split jobs) |
| 75 | + ├── deploy-strategy-switch-console.yml |
| 76 | + ├── manual-strategy-switch.yml |
| 77 | + ├── codex_pr_review.yml |
| 78 | + └── codex_review_gate.yml |
| 79 | +``` |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## Tier 1: Source of Truth — `platform-config.json` |
| 84 | + |
| 85 | +Defines the entire runtime configuration universe: |
| 86 | + |
| 87 | +- **4 domains**: `us_equity`, `hk_equity`, `cn_equity`, `crypto` |
| 88 | +- **6 platforms**: `longbridge`, `ibkr`, `schwab`, `firstrade`, `qmt`, `binance` |
| 89 | +- **18 strategy profiles** with features: income layer, option overlay, DCA, combo |
| 90 | +- **Platform capabilities, CSS theming, default accounts, repositories, variable scopes** |
| 91 | + |
| 92 | +Never hardcode platform or strategy data in frontend code — regenerate from this file. |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## Tier 2: Python Tooling (`python/`) |
| 97 | + |
| 98 | +The `python/` directory contains all Python code, organized as a self-contained project with its own `pyproject.toml`. |
| 99 | + |
| 100 | +**Key scripts:** |
| 101 | + |
| 102 | +| Script | Purpose | |
| 103 | +|--------|---------| |
| 104 | +| `build_config.py` | Full pipeline: validate config, generate strategy profiles, inject into index.html | |
| 105 | +| `build_platform_config.py` | Generate `config.js` (ES module) from `platform-config.json` | |
| 106 | +| `runtime_settings.py` | Core engine: validate targets, render variables, apply via `gh` CLI | |
| 107 | +| `build_runtime_switch.py` | Build transient runtime targets for manual strategy switch | |
| 108 | +| `inject_platform_config.py` | Inject platform config globals into `index.html` | |
| 109 | +| `sync_strategy_switch_page_asset.py` | Embed HTML/JSON as ES module assets for Worker deployment | |
| 110 | + |
| 111 | +**Dependency boundary:** Python scripts consume `schemas/runtime-target.schema.json`, `platform-config.json`, and write to `web/strategy-switch-console/`. They do **not** depend on the JavaScript code. |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## Tier 3: Web Application (`web/`) |
| 116 | + |
| 117 | +A Cloudflare Workers-based strategy switch console. Built with vanilla JS (no framework) and deployed via Wrangler. |
| 118 | + |
| 119 | +**Key files:** |
| 120 | + |
| 121 | +| File | Role | |
| 122 | +|------|------| |
| 123 | +| `worker.js` | Backend: OAuth, session management, config serving, switch dispatch, KV caching | |
| 124 | +| `index.html` | SPA shell with bilingual (zh/en) UI, platform selection, strategy configuration | |
| 125 | +| `app.js` | Frontend form logic, i18n, summary panel | |
| 126 | +| `config.js` (generated) | Platform config constants consumed by both frontend and worker | |
| 127 | + |
| 128 | +**Dependency boundary:** The web app consumes generated assets (`config.js`, `page_asset.js`) and reads `platform-config.json` indirectly via the Worker API. It does **not** depend on Python scripts at runtime. |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +## CI/CD: Independent Validation |
| 133 | + |
| 134 | +The `validate.yml` workflow runs **two independent jobs**: |
| 135 | + |
| 136 | +1. **`python`** — Python tests, config validation, runtime target validation, dependency matrix checks |
| 137 | +2. **`js`** — JS module syntax checks, Worker asset validation, SPA integration tests |
| 138 | + |
| 139 | +Neither job depends on the other. This ensures that a change to Python scripts doesn't need to wait for JS tests, and vice versa. |
| 140 | + |
| 141 | +--- |
| 142 | + |
| 143 | +## Change Guide |
| 144 | + |
| 145 | +- **Add a platform/strategy**: Edit `platform-config.json`, then run `python3 python/scripts/build_config.py` to regenerate all derived files. |
| 146 | +- **Modify build logic**: Edit files in `python/scripts/`, run `python3 -m unittest discover -s python/tests`. |
| 147 | +- **Modify web UI**: Edit files in `web/strategy-switch-console/`, run `node tests/strategy_switch_worker_validation.mjs`. |
| 148 | +- **Update runner**: Run both Python and JS validation locally before committing. |
0 commit comments