Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
177 lines (134 loc) · 10.8 KB

ARCHITECTURE.md

File metadata and controls

177 lines (134 loc) · 10.8 KB
Raw

QuantRuntimeSettings Architecture

Documentation index. This is the package architecture entry; repository governance is covered separately in organization architecture. The 2026-06-29 design preserves the earlier rationale and migration plan.

Overview

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 console. The console is evolving into the personal deployment's single human-facing global decision surface; see Unified Control Console V1. It remains separate from broker credentials and execution.

The generated RUNTIME_TARGET_JSON payload is the canonical desired-state contract for one deployment target. scheduler, market, market_calendar, market_timezone, and plugin mount outputs are derived from strategy_profile, while execution_mode is validated against strategy-profile policy. It and the repository-level CLOUD_RUN_SERVICE_TARGETS_JSON inventory are validated, non-secret deployment metadata written as GitHub Variables so the console can reconcile desired state; neither may contain credentials or account secrets. Platform consumers must prefer those Variables and may read legacy Secrets only as temporary migration fallbacks.

Multi-strategy identity and storage

  • A platform may run multiple strategies through multiple deployment targets, but one service_name has one active strategy_profile.
  • service_name is the primary target identity. account_scope may be shared by multiple services and is only a legacy fallback when an existing entry has no service identity.
  • CLOUD_RUN_SERVICE_TARGETS_JSON accepts either a bare target array or an object with targets.
  • Repository-scoped multi-service platforms update only the exact service entry. Creating a new service requires the explicit allow_create path.
  • LongBridge keeps its selected RUNTIME_TARGET_JSON and account variables in the GitHub Environment, while the repository-scoped service-target aggregate is updated in the same switch operation for deployment reconciliation.
  • Legacy targets may omit market metadata. Newly generated targets always carry the complete market metadata trio; partial metadata is rejected.

Deployment topology

  • LongBridge, IBKR, Schwab, and Firstrade use Cloud Run and may activate settings through their environment-sync workflows.
  • Binance uses an Oracle Cloud VPS self-hosted GitHub Actions runner. Settings become active on the next externally scheduled runtime workflow dispatch; the settings control plane never dispatches this live-capable workflow as a sync substitute and does not reconfigure the external VPS scheduler.
  • QMT has no live deployment configuration and remains dry-run only.
  • platform-config.json records runtime_model, settings_activation, and live_configured for every platform. Unsupported activation combinations fail validation.

P0–P6 runtime-authority boundary

platform-config.json.meta.runtime_authority is a separately validated, machine-readable status record for the P0–P6 control plane. It intentionally sits above legacy per-platform deployment metadata:

  • The current status, P0_CONTROL_PLANE_NOT_RUNTIME_WIRED, records that no active preauthorized autonomy policy or P0 execution gateway is wired into a runtime.
  • default_execution_mode, live_configured, strategy lifecycle labels, switch-console access, workflow dispatch, and CI results are not runtime, order, fund, or stage-change authorization.
  • P1–P3 non-live data acquisition requires an independent, exact contract; P0 does not authorize data acquisition by implication.
  • P4–P6 are explicitly undefined in this status record. This package must not assign their scope, ordering, acceptance criteria, or completion state.

The record is informational and fail-closed for this repository's generated metadata. It does not alter existing execution defaults, deploy a gateway, access credentials, dispatch workflows, or submit orders.

The repository has a three-tier architecture built around a single source of truth:

platform-config.json  (single source of truth)
       |
       v
  Python scripts      (validation, code generation, deployment tooling)
       |
       v
  Generated assets    (config.js, strategy_profiles_asset.js)
       |
       v
  Web application     (Cloudflare Worker + frontend SPA)

Directory Layout

.
├── platform-config.json                 # Central configuration (single source of truth)
├── internal_dependency_matrix.json      # Internal git dependency pin tracking
│
├── python/                              # Python tooling (tests, CI, scripts)
│   ├── pyproject.toml                   # Python project definition & linter config
│   ├── scripts/                         # Build & validation scripts
│   │   ├── build_config.py              # Full build pipeline
│   │   ├── build_platform_config.py     # Generate config.js from platform-config.json
│   │   ├── build_runtime_switch.py      # Build transient runtime targets
│   │   ├── runtime_settings.py          # Core validation & assignment engine
│   │   ├── check_internal_dependency_matrix.py
│   ├── tests/                           # Python unit tests
│   │   ├── test_runtime_settings.py
│   │   └── test_internal_dependency_matrix.py
│   └── shell/                           # Shell scripts (Python ecosystem)
│       └── checkout_internal_dependency_consumers.sh
│
├── web/                                 # JavaScript web application
│   └── strategy-switch-console/         # Cloudflare Workers app
│       ├── worker.js                    # Worker backend (OAuth, routing, KV)
│       ├── frontend/                    # React daily pages
│       ├── v2_asset_map.js              # Versioned frontend bundle map
│       ├── config.js                    # Generated: Platform config constants
│       ├── strategy_profiles_asset.js   # Generated: Strategy catalog
│       └── wrangler.toml.example        # Cloudflare Workers config template
│
├── schemas/                             # Shared JSON Schema (consumed by both)
│   └── runtime-target.schema.json       # Runtime target validation schema
│
├── tests/                               # JavaScript tests
│   ├── strategy_switch_worker_validation.mjs
│   └── test_cash_financing.js
│
├── docs/                                # Documentation
├── examples/targets/                    # Example runtime targets per platform
├── prompts/                             # LLM prompt templates
│
└── .github/workflows/                   # CI/CD workflows
    ├── validate.yml                     # Python + JS validation (split jobs)
    ├── deploy-strategy-switch-console.yml
    ├── manual-strategy-switch.yml
    ├── codex_pr_review.yml             # Reusable caller to AIAuditBridge

Tier 1: Source of Truth — platform-config.json

Defines the entire runtime configuration universe:

  • 4 domains: us_equity, hk_equity, cn_equity, crypto, including market calendar and timezone metadata
  • 6 platforms: longbridge, ibkr, schwab, firstrade, qmt, binance
  • 18 strategy profiles with features: income layer, option overlay, DCA, combo
  • Platform capabilities, CSS theming, default accounts, repositories, variable scopes

Never hardcode platform or strategy data in frontend code — regenerate from this file.

Tier 2: Python Tooling (python/)

The python/ directory contains all Python code, organized as a self-contained project with its own pyproject.toml.

Key scripts:

Script Purpose
build_config.py Validate config and run the platform catalog generator
build_platform_config.py Generate config.js and the strategy catalog from platform-config.json
runtime_settings.py Core engine: validate targets, render variables, apply via gh CLI
build_runtime_switch.py Build transient runtime targets for manual strategy switch

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.

Tier 3: Web Application (web/)

A Cloudflare Workers-based strategy switch console. The daily pages are the React app in frontend/, and the Worker is deployed via Wrangler.

Key files:

File Role
worker.js Backend: OAuth, session management, config serving, switch dispatch, KV caching
frontend/ React pages for overview, accounts, and decisions
v2_asset_map.js Versioned CSS and JS bundle served by the Worker
config.js (generated) Platform config constants consumed by the frontend and worker

Dependency boundary: The web app consumes generated assets (config.js, strategy_profiles_asset.js) and reads platform-config.json indirectly via the Worker API. It does not depend on Python scripts at runtime.

The cockpit's audit reader merges database keyset pages with the retained KV activity log. Its cursor fixes the first page's time ceiling and carries the last event's time and ID. Runtime readback projects existing lifecycle source snapshots through an explicit account-to-target binding; it neither queries a cloud control plane nor dispatches a runtime change. Missing and stale evidence retain unknown effective state. See Console API for pagination, coverage and error contracts.

CI/CD: Independent Validation

The validate.yml workflow runs two independent jobs:

  1. python — Python tests, config validation, runtime target validation, dependency matrix checks
  2. js — JS module syntax checks, Worker asset validation, SPA integration tests

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.

Change Guide

  • Add a platform/strategy: Edit platform-config.json, then run python3 python/scripts/build_config.py to regenerate all derived files.
  • Modify build logic: Edit files in python/scripts/, run python3 -m unittest discover -s python/tests.
  • Modify web UI: Edit files in web/strategy-switch-console/, run node tests/strategy_switch_worker_validation.mjs.
  • Update runner: Run both Python and JS validation locally before committing.
  • Org-level QSL governance: See QSL Org Architecture & Health Checks.